Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia o original em inglês.

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

PropriedadeTipoObrigatóriaDescrição
apiVersionconst “aggrega.ai/v1beta1”simConstante: "aggrega.ai/v1beta1"
kindconst “Feature”simConstante: "Feature"
metadataobjectsim
specobjectsimO 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

PropriedadeTipoObrigatóriaDescrição
namestringsimPelo menos 1 caractere.
versionstringsimVersionamento 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-]+)*))?$.
descriptionstringnãoO 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.
maintainersobject[]nãoLista de mantenedores responsáveis por esta entidade.
licensestringnãoIdentificador 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.
repositorystringnãoA URL do repositório Git onde ficam os arquivos-fonte.
homestringnãoA URL da página inicial, do wiki ou da documentação desta entidade.
keywordsstring[]nãoUma lista de palavras-chave descritivas para facilitar a descoberta na interface do usuário.
labelsobjectnãoRó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.
annotationsmapa de stringnãoCaracterí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[]
PropriedadeTipoObrigatóriaDescrição
namestringsim
emailstringnão
urlstringnã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.

PropriedadeTipoObrigatóriaDescrição
feature.aggrega.ai/kindstring (enum)nãoRó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.

PropriedadeTipoObrigatóriaDescrição
extendsstringnãoReferê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.
featuresSchemamapa de objectnãoDefiniçõ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.
appliesTostringnãoString 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,!][^,]*)?)*)$.
appliesToAnyOfstring ou mapa de string[]nãoUma 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).
interoperabilityobjectnãoControles avançados de segurança operacional e interoperabilidade.
usesSchemamapa de objectnãoOs 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_-]+$.
schemaobjectnãoConteú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: }, escrita em spec.schema para fornecer o contrato inteiro a partir de um arquivo ou em um único pilar para fornecer apenas esse pilar, com um caminho relativo lido em relação ao diretório que contém a entidade que o declarou; (3) referência entre documentos via {$ref: #/schemas/} para uma entrada de uma SchemaLibrary por identidade de nome simples (a versão é fornecida pelo arquivo de bloqueio de cada Release; nenhum host de registro aparece na referência). Os campos complementares usesSchema e featuresSchema cobrem os pilares de forma fixa (sockets de dependência, slots de vinculação); o compilador compõe os três no único esquema em relação ao qual uma instância é validada.
assertionsmapa de stringnãoValidaçã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.

PropriedadeTipoObrigatóriaDescrição
conflictsWithstring[]nãoNomes 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.