Esquema do catálogo do Aggrega (Feature)
Referência gerada. Não editar à mão — gerar novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/feature-v1beta1.schema.json
Uma funcionalidade operacional modular que se associa dinamicamente a componentes.
Consulte-se a referência de autoria da Feature para orientações em prosa sobre como escrever entidades Feature; esta página documenta o esquema estrutural que essa referência descreve.
Tipo de nível superior: object
Propriedades
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | sim | Constante: "aggrega.ai/v1beta1" |
kind | const “Feature” | sim | Constante: "Feature" |
metadata | objeto | sim | |
spec | objeto | sim | O contrato de validação, direcionamento e interoperabilidade de uma Feature do catálogo: os pilares de forma livre (values, infra, provides) escritos através de schema, os pilares de forma fixa (sockets de dependência usesSchema, slots de anexo featuresSchema), o direcionamento de componentes (appliesTo e appliesToAnyOf) e os controlos de interoperabilidade. |
Não são permitidas propriedades adicionais.
feature.metadata
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | Pelo menos 1 carácter. |
version | string | sim | Versionamento semântico estrito da funcionalidade (por exemplo, 1.0.0). Padrão: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
description | string | não | O que esta entidade é e para que serve, escrito para quem está a decidir se a vai usar. Convém começar por uma frase que nomeie a coisa e acrescentar depois o que um leitor precisa para a escolher e usar corretamente — o que espera da Release que a implementa, e tudo o que seja surpreendente no seu comportamento. Um parágrafo curto é a extensão habitual. |
maintainers | object[] | não | Lista dos responsáveis pela manutenção desta entidade. |
license | string | não | Identificador SPDX da licença do software que esta entidade descreve, como MIT ou AGPL-3.0. Regista os termos desse software, não os termos deste ficheiro. |
repository | string | não | O URL do repositório Git onde se encontram os ficheiros de origem. |
home | string | não | O URL da página inicial, da wiki ou da documentação desta entidade. |
keywords | string[] | não | Uma lista de palavras-chave descritivas para facilitar a descoberta na interface do utilizador. |
labels | objeto | não | Etiquetas de duck typing para a Feature. A etiqueta reservada ‘feature.aggrega.ai/kind’ com o valor ‘secret’ marca esta como uma Feature de credenciais para o autor e para as ferramentas que a apresentam. Uma Feature de credenciais e uma Feature comum são anexadas da mesma forma, sob a mesma superfície de anexação; o que um anexo produz é decidido pela FeatureRecipe para a qual o Manifest mapeia o seu tipo, não pela etiqueta. |
annotations | mapa de string | não | Características intrínsecas e imutáveis da funcionalidade, escritas pelo arquiteto de plataforma no Domínio 2. Propagam-se em cascata até ao compartimento .context.annotations.catalog. |
Não são permitidas propriedades adicionais.
feature.metadata.maintainers[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | |
email | string | não | |
url | string | não |
Não são permitidas propriedades adicionais.
feature.metadata.labels
Etiquetas de duck typing para a Feature. A etiqueta reservada ‘feature.aggrega.ai/kind’ com o valor ‘secret’ marca esta como uma Feature de credenciais para o autor e para as ferramentas que a apresentam. Uma Feature de credenciais e uma Feature comum são anexadas da mesma forma, sob a mesma superfície de anexação; o que um anexo produz é decidido pela FeatureRecipe para a qual o Manifest mapeia o seu tipo, não pela etiqueta.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
feature.aggrega.ai/kind | string (enum) | não | Etiqueta do tipo de Feature. O valor ‘secret’ marca esta como uma Feature de credenciais. Valores permitidos: "secret" |
feature.spec
O contrato de validação, direcionamento e interoperabilidade de uma Feature do catálogo: os pilares de forma livre (values, infra, provides) escritos através de schema, os pilares de forma fixa (sockets de dependência usesSchema, slots de anexo featuresSchema), o direcionamento de componentes (appliesTo e appliesToAnyOf) e os controlos de interoperabilidade.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
extends | string | não | Referência a uma Feature base da qual esta Feature herda. Nomeia a base pelo seu metadata.name em vez de pela coordenada de registo sob a qual a Feature é publicada, e aceita as mesmas três formas de versão que qualquer referência de catálogo: simples (core/queue) para a versão mais alta disponível, exata (core/queue:1.0.0) ou um intervalo com acento circunflexo (core/queue:^1.0.0). O que é herdado vai além dos metadados: metadata.labels e metadata.annotations da base, os seus seletores appliesTo e appliesToAnyOf, o seu bloco interoperability, o seu usesSchema e o seu featuresSchema são todos fundidos para baixo, e as suas declarações JSON Schema 2020-12 em schema são fundidas automaticamente. O valor próprio do filho prevalece numa chave partilhada, e os campos de identidade nunca são herdados. |
featuresSchema | mapa de object | não | Definições declarativas de slots de anexo: os pontos de associação com nome nos quais esta Feature espera que outra Feature seja anexada. Um slot restringe qual preenchimento se pode associar a ele (selector) e como o material do preenchimento pode ser entregue (inject); a Feature própria do preenchimento detém o seu contrato de values e infra. Declarar um slot nunca fecha o bloco de anexos — um autor pode anexar uma Feature com um nome que nenhum slot declara. Um slot é um ponto de associação, não um socket de dependência: usesSchema declara a superfície de topologia separada. |
appliesTo | string | não | String de seletor de etiquetas ao estilo do Kubernetes que seleciona Components. Os requisitos separados por vírgulas têm de valer todos (AND). Formas suportadas: key=value, key!=value, key in (v1, v2), key notin (v1, v2), chave simples (etiqueta presente), !key (etiqueta ausente). Exemplo: “tier in (critical, production), !legacy”. Um seletor vazio ou ausente não declara qualquer restrição. O seletor é lido face a estas formas sempre que um anexo desta Feature é avaliado, e um requisito fora delas interrompe a compilação, nomeando-o: um requisito vazio (uma vírgula inicial, final ou duplicada), ou uma chave que contém espaços em branco ou qualquer um de = ! ( ) e a vírgula — assim, “!tier=frontend” é recusado, e tier!=frontend é a forma de excluir um valor. Um valor é o texto após o seu operador, quaisquer que sejam os caracteres que contenha. O padrão neste campo recusa apenas algumas formas malformadas, antes de qualquer anexo ser avaliado. Padrão: ^(?:[^()]*[()][\s\S]*|[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?(?:,[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?)*)$. |
appliesToAnyOf | string ou mapa de string[] | não | Uma lista de seletores; a Feature aplica-se se QUALQUER item corresponder (lógica OR). Cada item é uma string de seletor de etiquetas (mesma gramática que appliesTo; os requisitos dentro da string combinam-se com AND) ou um mapa plano de chave-valor em que cada par tem de corresponder (apenas igualdade). |
interoperability | objeto | não | Controlos avançados de segurança operacional e interoperabilidade. |
usesSchema | mapa de object | não | Os sockets de dependência que esta entidade declara, indexados pelo nome do socket; cada ligação traçada através de um socket é verificada face à declaração desse socket — o seu seletor e os mecanismos de injeção que permite. Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
schema | objeto | não | Conteúdo JSON Schema 2020-12 que abrange os pilares de forma livre: values (o domínio do Programador — parâmetros com a forma da aplicação que o Programador configura por anexo de Feature no Aggregate); infra (o domínio do Operador — controlos de dimensionamento físico fornecidos pela Release); e provides (chaves de contexto a jusante que esta Feature expõe aos consumidores através do pipe da topologia). Aceita três modos de autoria através de despacho conforme a forma do conteúdo: (1) conteúdo inline (um mapa YAML com forma compacta, JSON Schema YAML ou misto); (2) substituição por ficheiro via {$import: |
assertions | mapa de string | não | Validação entre campos em tempo de compilação. Cada entrada é uma asserção com nome: a chave é um identificador de regra estável que surge nas mensagens de erro; o valor é uma string de template Go com semântica de interrupção {{ fail "message" }}. Várias asserções com nome por entidade são avaliadas por instância pela ordem declarada pelo autor; a primeira asserção que falha interrompe a compilação. As asserções de Feature são avaliadas após a resolução e a análise estática, antes da renderização, e exprimem invariantes arquiteturais do contrato. Contexto do template: .values / .infra / .uses / .features / .metadata. O avaliador usa missingkey=error: as referências a chaves não definidas provocam uma interrupção com um diagnóstico no-such-key. Como a referência simples provoca a interrupção antes de qualquer fallback poder ser executado, um default simples não fornece um fallback de campo opcional nesta superfície — convém proteger a referência com hasKey, ou usar o helper optional, que realiza diretamente a verificação de presença. Ler a chave através de index também não fornece um: index provoca uma interrupção perante uma chave de mapa que o mapa não contém, nomeando a chave. |
Não são permitidas propriedades adicionais.
feature.spec.interoperability
Controlos avançados de segurança operacional e interoperabilidade.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
conflictsWith | string[] | não | Nomes das Features juntamente com as quais esta Feature não pode chegar a um componente, cada um escrito da forma como o tipo de um anexo nomeia uma Feature. A compilação é interrompida antes da renderização quando um componente acaba por transportar esta Feature e uma Feature aqui nomeada — quer cada uma tenha sido anexada no componente, num subsistema ou fronteira que o contém, numa entrada de componente da Release ou por expansão orientada por anotações. Basta uma declaração: a interrupção não precisa de que a outra Feature liste esta. Os nomes são comparados sem qualquer versão, pelo que uma entrada corresponde a todas as versões da Feature que nomeia. Duas Features anexadas a fronteiras irmãs que não partilham nenhum componente nunca se encontram e não causam interrupção. |
Não são permitidas propriedades adicionais.