Esquema da intenção do programador do Aggrega (Aggregate)
Referência gerada. Não editar à mão — gerar novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/aggregate-v1beta1.schema.json
A arquitetura AI recursiva e parametrizada. Funciona tanto como raiz de uma compilação como módulo reutilizável.
Consulte-se a referência de autoria do Aggregate para orientações em prosa sobre como escrever entidades Aggregate; 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 “Aggregate” | sim | Constante: "Aggregate" |
metadata | objeto | sim | |
defs | string[] | não | Bloco opcional para as âncoras normalizadas do YAML (& e *), que mantém o Aggregate DRY e conserva para o compilador um dicionário plano O(1). Espelha o bloco equivalente no Manifest. |
spec | objeto | sim | A superfície da intenção do programador: o contrato global de parâmetros, as importações de agregados aninhados, a API pública dos componentes exportados, os agrupamentos em subsistemas e as instâncias de componente que compõem o módulo. |
Não são permitidas propriedades adicionais.
aggregate.metadata
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
name | string | sim | Pelo menos 1 carácter. |
version | string | sim | Versionamento semântico estrito do módulo agregado. 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 | |
maintainers | object[] | não | Lista dos responsáveis pela manutenção desta entidade. |
license | string | não | Identificador 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. |
repository | string | não | O URL do repositório Git onde se encontram os ficheiros de origem. |
home | string | não | O URL da página inicial, da wiki ou da documentação desta entidade. |
keywords | string[] | não | Uma lista de palavras-chave descritivas para facilitar a descoberta na interface do utilizador. |
labels | mapa de string | não | Etiquetas de duck typing ao nível do módulo para a descoberta no catálogo, a avaliação de políticas e a filtragem no Studio/IDE. Estas etiquetas descrevem a identidade do Aggregate enquanto módulo reutilizável (por exemplo, aggregate.aggrega.ai/tier: infrastructure, aggregate.aggrega.ai/compliance: pci-dss). NÃO se propagam em cascata para os nós de componentes filhos — as etiquetas dos componentes provêm exclusivamente da entidade de catálogo Component no Domínio 2. |
Não são permitidas propriedades adicionais.
aggregate.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.
aggregate.spec
A superfície da intenção do programador: o contrato global de parâmetros, as importações de agregados aninhados, a API pública dos componentes exportados, os agrupamentos em subsistemas e as instâncias de componente que compõem o módulo.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
parameters | mapa de object | não | Contrato global de ambiente. Cada entrada é um objeto de contrato tipado que utiliza o subconjunto do vocabulário em forma compacta (type, description, default, enum, min/max, minLength/maxLength, pattern, format, validate, validateMessage, required, items, valuesType, properties). A estrutura aninhada exprime-se através do subcampo properties: da forma tipada. A Release pode satisfazê-lo inline (parameters: {…}) ou por importação de um único ficheiro de origem (parameters: {$import: |
aggregates | mapa de object | não | Agregados aninhados que funcionam como módulos importados. Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
exportedComponents | mapa de string | não | A interface da API pública. Associa um nome público exposto a um ID de componente interno. Os Aggregates pais que importam este módulo referenciam os componentes por estes nomes públicos. |
subsystems | mapa de subsystem | não | Agrupamentos lógicos com nome dos componentes de um Aggregate em subsistemas. Mutuamente exclusivos com os componentes de nível superior — declarar ambos é rejeitado. Um subsistema a que o autor chama default é um subsistema declarado comum, distinto do default sintetizado que o compilador cria para um Aggregate apenas com componentes. Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
components | mapa de component_instance | não | O mapa dos componentes lógicos atómicos que compõem este Aggregate, escritos diretamente no nível superior. Os componentes de nível superior e os subsistemas são mutuamente exclusivos — declarar ambos é rejeitado. Quando os componentes são escritos aqui (sem subsistemas), o compilador reúne-os no carregamento num subsistema default sintetizado, e a IR marca esse subsistema como sintetizado. Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
Não são permitidas propriedades adicionais.
Definições
inject_delivery
Um único mecanismo de entrega, escrito como um array de entradas. Cada entrada tem um ‘in’ (identificador local — nome de variável de ambiente, caminho de ficheiro, flag de argumento ou chave personalizada específica do mecanismo) e exatamente um de ‘from’ (uma chave provides a resolver) ou ‘value’ (uma string literal, que pode conter expressões de template Go avaliadas na resolução da autoinjeção). ‘from’ resolve-se face aos provides do destino no contexto uses[].inject, face aos provides que a FeatureRecipe do anexo publica no contexto features.
Tipo: object[]
inject_block
Encaminhamento agnóstico da injeção. Associa variáveis locais a chaves provides do destino (uses[].inject), às chaves provides que a FeatureRecipe de um anexo publica (features.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
env | inject_delivery | não | Um único mecanismo de entrega, escrito como um array de entradas. Cada entrada tem um ‘in’ (identificador local — nome de variável de ambiente, caminho de ficheiro, flag de argumento ou chave personalizada específica do mecanismo) e exatamente um de ‘from’ (uma chave provides a resolver) ou ‘value’ (uma string literal, que pode conter expressões de template Go avaliadas na resolução da autoinjeção). ‘from’ resolve-se face aos provides do destino no contexto uses[].inject, face aos provides que a FeatureRecipe do anexo publica no contexto features. |
file | inject_delivery | não | Um único mecanismo de entrega, escrito como um array de entradas. Cada entrada tem um ‘in’ (identificador local — nome de variável de ambiente, caminho de ficheiro, flag de argumento ou chave personalizada específica do mecanismo) e exatamente um de ‘from’ (uma chave provides a resolver) ou ‘value’ (uma string literal, que pode conter expressões de template Go avaliadas na resolução da autoinjeção). ‘from’ resolve-se face aos provides do destino no contexto uses[].inject, face aos provides que a FeatureRecipe do anexo publica no contexto features. |
arg | inject_delivery | não | Um único mecanismo de entrega, escrito como um array de entradas. Cada entrada tem um ‘in’ (identificador local — nome de variável de ambiente, caminho de ficheiro, flag de argumento ou chave personalizada específica do mecanismo) e exatamente um de ‘from’ (uma chave provides a resolver) ou ‘value’ (uma string literal, que pode conter expressões de template Go avaliadas na resolução da autoinjeção). ‘from’ resolve-se face aos provides do destino no contexto uses[].inject, face aos provides que a FeatureRecipe do anexo publica no contexto features. |
component_uses_block
As ligações que um componente estabelece com os componentes de que depende, indexadas por socket. Cada socket lista os seus destinos, ou nomeia cada ligação sob um alias. Uma ligação nomeada sob um alias pode transportar os valores por ligação do programador e os anexos que preenchem os slots que o socket declara.
Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$.
Os valores são string[] or map of object.
Nenhuma outra chave é permitida.
feature_uses_block
As ligações que uma Feature anexada estabelece, indexadas por um socket que a Feature declara no seu usesSchema. Cada socket lista os seus destinos, ou nomeia cada ligação sob um alias. Uma ligação estabelecida por uma Feature não transporta anexos próprios: uma credencial de que precise preenche um slot que a Feature declara no seu próprio featuresSchema e é anexada ao lado da Feature.
Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$.
Os valores são string[] or map of object.
Nenhuma outra chave é permitida.
connection_attachment
Um anexo que uma ligação transporta: a Feature que preenche um slot declarado pelo socket da ligação, com a configuração do programador para ela.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
type | string | sim | O URI da interface de Feature que este anexo solicita (por exemplo, core/referenced-secret:1.0.0). |
description | string | não | Documentação opcional que explica por que motivo esta ligação transporta o anexo. |
values | objeto | não | Configuração fornecida pelo programador para a Feature, validada pela declaração do seu esquema. |
Não são permitidas propriedades adicionais.
subsystem
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
description | string | não | Documentação opcional que descreve o propósito deste subsistema e o agrupamento lógico que representa. |
annotations | mapa de string ou object ou null | não | Anotações escritas pelo programador neste subsistema. Os valores são strings, objetos estruturados (um mapa de subchave para valor, fundido por subchave com um valor estruturado herdado) ou null; um null explícito numa chave herdada de um subsistema pai remove deste subsistema a associação herdada (renúncia a uma Feature orientada por anotações). As anotações declaradas aqui são herdadas pelos subsistemas aninhados e pelos componentes contidos; o nível mais próximo prevalece por chave. Propagam-se em cascata até ao compartimento .context.annotations.aggregate em cada nó IR derivado. |
features | mapa de object | não | Funcionalidades transversais anexadas a todos os componentes deste subsistema. O mesmo esquema das funcionalidades ao nível do componente (type, values, uses, inject). Achatadas em cada componente na finalização do grafo, posicionadas depois das funcionalidades ao nível do componente na ordem de execução. Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
subsystems | mapa de subsystem | não | Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
components | mapa de component_instance | não | Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
Não são permitidas propriedades adicionais.
component_instance
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
type | string | sim | O Component abstrato pedido, como referência: o seu metadata.name mais um :version opcional (por exemplo, core/api-server:1.0.0), nunca um caminho de ficheiro. Resolvido através do modelo de resolução de entidades em três camadas (diretórios de catálogo do espaço de trabalho → cache → registry): um Component escrito localmente fica em catalog/ na raiz do espaço de trabalho ou num diretório listado em workspace.catalog_dirs, e um type escrito como caminho de ficheiro relativo interrompe a compilação como uma entidade que nenhum catálogo contém. |
active | boolean ou string | não | Indica se este componente está presente na topologia compilada. Um boolean, ou um template de string sobre .parameters que tem de se resolver num boolean. Quando se resolve em false, o componente é removido da topologia, em cascata para as suas arestas uses e os seus anexos. Derivar o valor de um parâmetro permite a uma Release ativar ou desativar a presença do componente ao satisfazer esse parâmetro. Assume true quando omitido. Predefinição: true |
description | string | não | Documentação opcional que descreve o papel desta instância de componente na aplicação. Transportada até ao grafo IR. |
annotations | mapa de string ou object ou null | não | Anotações escritas pelo programador neste componente. Os valores são strings, objetos estruturados (um mapa de subchave para valor, fundido por subchave com um valor estruturado herdado) ou null; um null explícito numa chave herdada de um subsistema pai remove deste componente a associação herdada (renúncia a uma Feature orientada por anotações). As anotações ao nível de Component substituem por chave as anotações herdadas ao nível do subsistema; os componentes irmãos no mesmo subsistema mantêm os seus próprios mapas de anotações de forma independente. |
values | objeto | não | Propriedades cognitivas opacas passadas ao Component, validadas pelo seu esquema. |
uses | component_uses_block | não | As ligações que um componente estabelece com os componentes de que depende, indexadas por socket. Cada socket lista os seus destinos, ou nomeia cada ligação sob um alias. Uma ligação nomeada sob um alias pode transportar os valores por ligação do programador e os anexos que preenchem os slots que o socket declara. |
inject | inject_block | não | Autoinjeção ao nível de Component. Injeta os valores do próprio componente (através de ‘value:’) ou as suas próprias chaves provides (através de ‘from:’) diretamente no pipe de entrega (.context.inject). Só é permitido se a entidade de catálogo Component declarar ‘spec.inject’ com os mecanismos correspondentes. Uma chave inject que colida com uma chave declarada em uses[].inject interrompe a compilação como chave de entrega duplicada entre fontes de inject. |
features | mapa de object | não | As Features anexadas a este componente, indexadas pelo nome de instância que o autor dá a cada anexo. Esta é a única superfície de anexação: uma Feature operacional, uma Feature de credenciais (uma com a etiqueta feature.aggrega.ai/kind: secret) e uma Feature de identidade são todas anexadas aqui, com a mesma palavra-chave e a mesma forma. O que as distingue é o que o anexo produz, não a forma como é declarado. Um anexo cujo nome de instância corresponda a um slot que o Component declara em featuresSchema preenche esse slot; qualquer outro nome de instância é um anexo livre. Chaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$. |
Não são permitidas propriedades adicionais.