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 (Component)

Referência gerada. Não edite à mão — gere novamente a partir do JSON Schema publicado.

ID do esquema: https://aggrega.ai/schemas/component-v1beta1.schema.json

A definição abstrata de um bloco de construção atômico.

Consulte a referência de autoria do Component para orientações em prosa sobre como escrever entidades Component; 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 “Component”simConstante: "Component"
metadataobjectsim
specobjectsimDefinições de validação e de esquema que regem o payload opaco de valores do desenvolvedor.

Não são permitidas propriedades adicionais.

component.metadata

PropriedadeTipoObrigatóriaDescrição
namestringsimPelo menos 1 caractere.
versionstringsimVersionamento semântico estrito da interface (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.
labelsobjectsimRótulos de duck typing para declarar características. Devem incluir a chave reservada ‘component.aggrega.ai/type’.
annotationsmapa de stringnãoCaracterísticas intrínsecas e imutáveis do componente, 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.

component.metadata.maintainers[]
PropriedadeTipoObrigatóriaDescrição
namestringsim
emailstringnão
urlstringnão

Não são permitidas propriedades adicionais.

component.metadata.labels

Rótulos de duck typing para declarar características. Devem incluir a chave reservada ‘component.aggrega.ai/type’.

PropriedadeTipoObrigatóriaDescrição
component.aggrega.ai/typestring (enum)simO eixo reservado que nomeia que tipo de coisa este componente é. O Aggrega define esta chave e os valores que ela aceita, portanto o conjunto é fechado; para classificar componentes em um eixo próprio, adicione sua própria chave de rótulo ao lado desta. Valores permitidos: "server", "worker", "task", "function", "stateful-server", "resource"

component.spec

Definições de validação e de esquema que regem o payload opaco de valores do desenvolvedor.

PropriedadeTipoObrigatóriaDescrição
extendsstringnãoURI de um Component base que este Component estende. A extensão compõe a estrutura: os rótulos e as anotações de metadados da base, seus slots de vinculação (featuresSchema), sua lista de permissões de autoinjeção (inject) e seus sockets de topologia (usesSchema) são herdados, e este Component pode acrescentar entradas a eles ou substituir uma entrada herdada chave por chave. Os pilares de dados da base NÃO são compostos — o bloco schema da base é herdado exatamente como a base o escreveu, então um Component que estende escreve schema: inherited e não escreve nenhum conteúdo de pilar próprio.
featuresSchemamapa de objectnãoDefinições declarativas de slots de vinculação: os pontos de associação nomeados nos quais esta entidade espera que uma 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, de modo que uma mesma entidade atende tanto a uma vinculação que preenche um slot quanto a uma credencial compartilhada em um escopo mais amplo. Um slot é um ponto de associação, não um socket de dependência: usesSchema declara a superfície de topologia separada.
injectstring[]nãoMecanismos de entrega de autoinjeção permitidos pela lista de permissões (por exemplo, [‘env’, ‘file’, ‘arg’]). Quando presente, os desenvolvedores podem usar o bloco inject: no nível do componente no Aggregate para injetar seus próprios values ou chaves provides diretamente no pipe de entrega. Se omitido, a autoinjeção no nível do componente é proibida (padrão Black-Box — a Recipe cuida de toda a fiação interna). Mesma semântica de usesSchema[].inject, mas rege os values próprios do componente em vez da topologia entre componentes. Qualquer nome de mecanismo pode ser listado, exceto all, que nenhum bloco inject pode nomear.
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, os mecanismos de injeção que ele permite e seus contratos por conexão. Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$.
schemaanynã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 instância de Component no Aggregate); infra (o domínio do Operador — controles de dimensionamento físico fornecidos pela Release); e provides (chaves de contexto a jusante que este Component expõe aos consumidores por meio do pipe da topologia). Aceita quatro 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); (4) a string simples inherited, que é a única forma que um Component que declara extends pode escrever — ela afirma que os três pilares vêm do Component base exatamente como a base os escreveu. Os modos 1 a 3 escrevem conteúdo e estão disponíveis apenas para um Component que não declara extends; o modo 4 não escreve nenhum e é exigido de todo Component que o declara. 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 Component são avaliadas após a resolução e a análise estática, antes da renderização, e expressam invariantes arquiteturais do contrato que valem independentemente de qual Recipe se vincule. 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. A herança é aditiva: um Component que declara extends é avaliado em relação às asserções que herda, além das suas próprias, com as regras herdadas primeiro, e uma cadeia de qualquer profundidade se acumula da raiz da cadeia para baixo — assim, quando mais de uma regra falharia, a relatada é a declarada mais acima na cadeia. Reutilizar um nome herdado para declarar uma regra diferente é rejeitado quando a cadeia de extends é resolvida em relação ao catálogo, nomeando ambos os Components e o nome compartilhado — portanto, isso aparece assim que o Component base está presente, não apenas a partir do documento que estende; um Component que estende adiciona regras e nunca substitui nenhuma. Redeclarar uma regra herdada byte a byte sob seu próprio nome é aceito como a operação nula que é. Nada verifica se duas regras podem valer ao mesmo tempo: um par mutuamente insatisfazível é um erro de autoria que aparece como uma falha de asserção comum quando uma instância aciona a que dispara primeiro, nunca como um aviso antecipado.

Não são permitidas propriedades adicionais.

Definições

extending-component-must-declare-schema-inherited

Aplica-se quando spec.extends está presente. Um Component que estende recebe os values / infra / provides da sua base exatamente como a base os escreveu, então declara spec.schema: inherited e não escreve conteúdo de pilar. Os dois outros resultados são erros, e são equívocos diferentes: omitir spec.schema por completo, o que deixaria um leitor incapaz de distinguir um bloco de pilares herdado de um esquecido; e escrever conteúdo de pilar sob spec.schema, o que pediria um segundo contrato, divergente, em um Component cujo contrato é o da sua base.

PropriedadeTipoObrigatóriaDescrição
schemaconst “inherited”simO marcador de herança, e o único valor que spec.schema assume em um Component que declara extends. Ele indica de onde vêm os pilares; o conteúdo dos pilares em si é o do Component base. Constante: "inherited"

non-extending-component-authors-its-own-schema

Aplica-se quando spec.extends está ausente. Um Component que não estende nenhuma base escreve seu próprio conteúdo values / infra / provides sob spec.schema, então o campo traz conteúdo escrito pelo autor em vez do marcador inherited: o marcador afirma que os pilares vêm de uma base, e este Component não tem nenhuma.

PropriedadeTipoObrigatóriaDescrição
schemaobjectnãoConteúdo de pilar escrito pelo autor — um mapa, em qualquer um dos três modos de autoria de conteúdo que spec.schema documenta.