Esquema do catálogo do Aggrega (Feature)
Referência gerada. Não edite à mão — gere novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/feature-v1beta1.schema.json
Uma funcionalidade operacional modular que se vincula dinamicamente a componentes.
Consulte 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 | object | sim | |
spec | object | sim | O contrato de validação, direcionamento e interoperabilidade de uma Feature do catálogo: os pilares de forma livre (values, infra, provides) escritos via schema, os pilares de forma fixa (sockets de dependência usesSchema, slots de vinculação featuresSchema), o direcionamento de componentes (appliesTo e appliesToAnyOf) e os controles de interoperabilidade. |
Não são permitidas propriedades adicionais.
feature.metadata
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | Pelo menos 1 caractere. |
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á decidindo se vai usá-la. Comece com uma frase que nomeie a coisa e depois acrescente o que um leitor precisa para escolhê-la e usá-la corretamente — o que ela espera da Release que a implanta, e qualquer coisa surpreendente sobre como ela se comporta. Um parágrafo curto é o tamanho habitual. |
maintainers | object[] | não | Lista de mantenedores responsáveis por esta entidade. |
license | string | não | Identificador SPDX da licença do software que esta entidade descreve, como MIT ou AGPL-3.0. Ele registra os termos desse software, não os termos deste arquivo. |
repository | string | não | A URL do repositório Git onde ficam os arquivos-fonte. |
home | string | não | A URL da página inicial, do wiki ou da documentação desta entidade. |
keywords | string[] | não | Uma lista de palavras-chave descritivas para facilitar a descoberta na interface do usuário. |
labels | object | não | Rótulos de duck typing para a Feature. O rótulo reservado ‘feature.aggrega.ai/kind’ com o valor ‘secret’ marca esta como uma Feature de credenciais para o autor e para as ferramentas que a exibem. Uma Feature de credenciais e uma Feature comum são vinculadas da mesma forma, sob a mesma superfície de vinculação; o que uma vinculação produz é decidido pela FeatureRecipe para a qual o Manifest mapeia seu tipo, não pelo rótulo. |
annotations | mapa de string | não | Características intrínsecas e imutáveis da funcionalidade, escritas pelo arquiteto de plataforma no Domínio 2. Elas se propagam em cascata até o 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
Rótulos de duck typing para a Feature. O rótulo reservado ‘feature.aggrega.ai/kind’ com o valor ‘secret’ marca esta como uma Feature de credenciais para o autor e para as ferramentas que a exibem. Uma Feature de credenciais e uma Feature comum são vinculadas da mesma forma, sob a mesma superfície de vinculação; o que uma vinculação produz é decidido pela FeatureRecipe para a qual o Manifest mapeia seu tipo, não pelo rótulo.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
feature.aggrega.ai/kind | string (enum) | não | Rótulo 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 via schema, os pilares de forma fixa (sockets de dependência usesSchema, slots de vinculação featuresSchema), o direcionamento de componentes (appliesTo e appliesToAnyOf) e os controles de interoperabilidade.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
extends | string | não | Referência a uma Feature base da qual esta Feature herda. Ela nomeia a base por seu metadata.name em vez de pela coordenada de registro sob a qual a Feature é publicada, e aceita as mesmas três formas de versão que toda referência de catálogo aceita: 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, seus seletores appliesTo e appliesToAnyOf, seu bloco interoperability, seu usesSchema e seu featuresSchema são todos mesclados para baixo, e suas declarações JSON Schema 2020-12 em schema são mescladas automaticamente. O valor próprio do filho prevalece em uma chave compartilhada, e os campos de identidade nunca são herdados. |
featuresSchema | mapa de object | não | Definições declarativas de slots de vinculação: os pontos de associação nomeados nos quais esta Feature espera que outra Feature seja vinculada. Um slot restringe qual preenchimento pode se associar a ele (selector) e como o material do preenchimento pode ser entregue (inject); a Feature própria do preenchimento é dona do seu contrato de values e infra. Declarar um slot nunca fecha o bloco de vinculações — um autor pode vincular 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 rótulos no estilo do Kubernetes que seleciona Components. Os requisitos separados por vírgulas devem valer todos (AND). Formas suportadas: key=value, key!=value, key in (v1, v2), key notin (v1, v2), chave simples (rótulo presente), !key (rótulo ausente). Exemplo: “tier in (critical, production), !legacy”. Um seletor vazio ou ausente não declara nenhuma restrição. O seletor é lido em relação a essas formas cada vez que uma vinculação desta Feature é avaliada, e um requisito fora delas interrompe o build, 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 seu operador, quaisquer que sejam os caracteres que contenha. O padrão neste campo recusa apenas algumas formas malformadas, antes que qualquer vinculação seja avaliada. 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 se aplica se QUALQUER item corresponder (lógica OR). Cada item é uma string de seletor de rótulos (mesma gramática de appliesTo; os requisitos dentro da string se combinam com AND) ou um mapa plano de chave-valor em que cada par deve corresponder (somente igualdade). |
interoperability | object | não | Controles 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 conexão traçada por meio de um socket é verificada em relação à declaração desse socket — seu seletor e os mecanismos de injeção que ele permite. Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$. |
schema | object | não | Conteúdo JSON Schema 2020-12 que cobre os pilares de forma livre: values (o domínio do Desenvolvedor — parâmetros com o formato da aplicação que o Desenvolvedor configura por vinculação de Feature no Aggregate); infra (o domínio do Operador — controles de dimensionamento físico fornecidos pela Release); e provides (chaves de contexto a jusante que esta Feature expõe aos consumidores por meio do pipe da topologia). Aceita três modos de autoria por despacho conforme o formato do conteúdo: (1) conteúdo inline (um mapa YAML com forma compacta, JSON Schema YAML ou misto); (2) substituição por arquivo via {$import: |
assertions | mapa de string | não | Validação entre campos em tempo de build. Cada entrada é uma asserção nomeada: a chave é um identificador de regra estável que aparece nas mensagens de erro; o valor é uma string de template Go com semântica de interrupção {{ fail "message" }}. Várias asserções nomeadas por entidade são avaliadas por instância na ordem declarada pelo autor; a primeira asserção que falha interrompe o build. As asserções de Feature são avaliadas após a resolução e a análise estática, antes da renderização, e expressam invariantes arquiteturais do contrato. Contexto do template: .values / .infra / .uses / .features / .metadata. O avaliador usa missingkey=error: referências a chaves não definidas causam uma interrupção com um diagnóstico no-such-key. Como a referência simples causa a interrupção antes que qualquer fallback possa ser executado, um default simples não fornece um fallback de campo opcional nesta superfície — proteja a referência com hasKey, ou use o helper optional, que realiza diretamente a verificação de presença. Ler a chave por meio de index também não fornece um: index causa uma interrupção em uma chave de mapa que o mapa não contém, nomeando a chave. |
Não são permitidas propriedades adicionais.
feature.spec.interoperability
Controles avançados de segurança operacional e interoperabilidade.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
conflictsWith | string[] | não | Nomes das Features junto com as quais esta Feature não pode chegar a um componente, cada um escrito da forma como o tipo de uma vinculação nomeia uma Feature. O build é interrompido antes da renderização quando um componente acaba carregando esta Feature e uma Feature nomeada aqui — seja cada uma vinculada no componente, em um subsistema ou fronteira que o contém, em uma entrada de componente da Release ou por expansão orientada por anotações. Uma declaração basta: a interrupção não precisa que a outra Feature liste esta. Os nomes são comparados sem qualquer versão, de modo que uma entrada corresponde a todas as versões da Feature que nomeia. Duas Features vinculadas a fronteiras irmãs que não compartilham nenhum componente nunca se encontram e não causam interrupção. |
Não são permitidas propriedades adicionais.