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

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

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

PropriedadeTipoObrigatóriaDescrição
namestringsimPelo menos 1 carácter.
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á 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.
maintainersobject[]nãoLista dos responsáveis pela manutenção desta entidade.
licensestringnãoIdentificador 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.
repositorystringnãoO URL do repositório Git onde se encontram os ficheiros de origem.
homestringnãoO URL da página inicial, da wiki ou da documentação desta entidade.
keywordsstring[]nãoUma lista de palavras-chave descritivas para facilitar a descoberta na interface do utilizador.
labelsobjetonãoEtiquetas 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.
annotationsmapa de stringnãoCaracterí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[]
PropriedadeTipoObrigatóriaDescrição
namestringsim
emailstringnão
urlstringnã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.

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

PropriedadeTipoObrigatóriaDescrição
extendsstringnãoReferê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.
featuresSchemamapa de objectnãoDefiniçõ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.
appliesTostringnãoString 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,!][^,]*)?)*)$.
appliesToAnyOfstring ou mapa de string[]nãoUma 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).
interoperabilityobjetonãoControlos 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 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_-]+$.
schemaobjetonãoConteú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: }, escrita em spec.schema para fornecer o contrato inteiro a partir de um ficheiro ou num único pilar para fornecer apenas esse pilar, sendo 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 ficheiro de bloqueio de cada Release; nenhum host de registo aparece na referência). Os campos complementares usesSchema e featuresSchema abrangem os pilares de forma fixa (sockets de dependência, slots de anexo); o compilador compõe os três no único esquema face ao qual uma instância é validada.
assertionsmapa de stringnãoValidaçã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.

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