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
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | sim | Constante: "aggrega.ai/v1beta1" |
kind | const “Component” | sim | Constante: "Component" |
metadata | object | sim | |
spec | object | sim | Definiçõ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
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | Pelo menos 1 caractere. |
version | string | sim | Versionamento 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-]+)*))?$. |
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 | sim | Rótulos de duck typing para declarar características. Devem incluir a chave reservada ‘component.aggrega.ai/type’. |
annotations | mapa de string | não | Caracterí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[]
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | |
email | string | não | |
url | string | nã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’.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
component.aggrega.ai/type | string (enum) | sim | O 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.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
extends | string | não | URI 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. |
featuresSchema | mapa de object | não | Definiçõ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. |
inject | string[] | não | Mecanismos 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. |
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, 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_-]+$. |
schema | any | 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 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: |
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 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.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
schema | const “inherited” | sim | O 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.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
schema | object | não | Conteúdo de pilar escrito pelo autor — um mapa, em qualquer um dos três modos de autoria de conteúdo que spec.schema documenta. |