Esquema da intenção do desenvolvedor do Aggrega (Aggregate)
Referência gerada. Não edite à mão — gere novamente a partir do JSON Schema publicado.
ID do esquema: https://aggrega.ai/schemas/aggregate-v1beta1.schema.json
A arquitetura AI recursiva e parametrizada. Atua tanto como raiz de um build quanto como módulo reutilizável.
Consulte 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 | object | sim | |
defs | string[] | não | Bloco opcional para âncoras YAML padrão (& e *) que mantém o Aggregate DRY enquanto preserva um dicionário plano O(1) para o compilador. Espelha o bloco equivalente no Manifest. |
spec | object | sim | A superfície da intenção do desenvolvedor: 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 caractere. |
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 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 | mapa de string | não | Rótulos de duck typing no nível do módulo para descoberta no catálogo, avaliação de políticas e filtragem no Studio/IDE. Esses rótulos descrevem a identidade do Aggregate como módulo reutilizável (por exemplo, aggregate.aggrega.ai/tier: infrastructure, aggregate.aggrega.ai/compliance: pci-dss). Eles NÃO se propagam em cascata para os nós de componentes filhos — os rótulos dos componentes vê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 desenvolvedor: 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 usa o subconjunto do vocabulário na forma compacta (type, description, default, enum, min/max, minLength/maxLength, pattern, format, validate, validateMessage, required, items, valuesType, properties). A estrutura aninhada é expressa pelo subcampo properties: da forma tipada. A Release pode atendê-lo inline (parameters: {…}) ou pela importação de um único arquivo-fonte (parameters: {$import: |
aggregates | mapa de object | não | Agregados aninhados que atuam como módulos importados. Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$. |
exportedComponents | mapa de string | não | A interface da API pública. Mapeia um nome público exposto para um ID de componente interno. Os Aggregates pais que importam este módulo referenciam componentes por esses nomes públicos. |
subsystems | mapa de subsystem | não | Agrupamentos lógicos nomeados dos componentes de um Aggregate em subsistemas. Mutuamente exclusivos com os componentes de nível superior — declarar ambos é rejeitado. Um subsistema que o autor chama de default é um subsistema declarado comum, distinto do default sintetizado que o compilador cria para um Aggregate só com componentes. Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. 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. Componentes de nível superior e subsistemas são mutuamente exclusivos — declarar ambos é rejeitado. Quando os componentes são escritos aqui (sem subsistemas), o compilador os reúne no carregamento em um subsistema default sintetizado, e a IR marca esse subsistema como sintetizado. Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. 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 traz um ‘in’ (identificador local — nome de variável de ambiente, caminho de arquivo, flag de argumento ou chave personalizada específica do mecanismo) mais exatamente um entre ‘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’ é resolvido em relação aos provides do destino no contexto uses[].inject, em relação aos provides que a FeatureRecipe da vinculação publica no contexto features.
Tipo: object[]
inject_block
Roteamento agnóstico da injeção. Mapeia variáveis locais para chaves provides do destino (uses[].inject), para as chaves provides que a FeatureRecipe de uma vinculação 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 traz um ‘in’ (identificador local — nome de variável de ambiente, caminho de arquivo, flag de argumento ou chave personalizada específica do mecanismo) mais exatamente um entre ‘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’ é resolvido em relação aos provides do destino no contexto uses[].inject, em relação aos provides que a FeatureRecipe da vinculação publica no contexto features. |
file | inject_delivery | não | Um único mecanismo de entrega, escrito como um array de entradas. Cada entrada traz um ‘in’ (identificador local — nome de variável de ambiente, caminho de arquivo, flag de argumento ou chave personalizada específica do mecanismo) mais exatamente um entre ‘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’ é resolvido em relação aos provides do destino no contexto uses[].inject, em relação aos provides que a FeatureRecipe da vinculação publica no contexto features. |
arg | inject_delivery | não | Um único mecanismo de entrega, escrito como um array de entradas. Cada entrada traz um ‘in’ (identificador local — nome de variável de ambiente, caminho de arquivo, flag de argumento ou chave personalizada específica do mecanismo) mais exatamente um entre ‘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’ é resolvido em relação aos provides do destino no contexto uses[].inject, em relação aos provides que a FeatureRecipe da vinculação publica no contexto features. |
component_uses_block
As conexões que um componente traça até os componentes dos quais depende, indexadas por socket. Cada socket lista seus destinos, ou nomeia cada conexão sob um alias. Uma conexão nomeada sob um alias pode carregar os valores por conexão do desenvolvedor e as vinculações que preenchem os slots que o socket declara.
Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$.
Os valores são string[] or map of object.
Nenhuma outra chave é permitida.
feature_uses_block
As conexões que uma Feature vinculada traça, indexadas por um socket que a Feature declara em seu usesSchema. Cada socket lista seus destinos, ou nomeia cada conexão sob um alias. Uma conexão traçada por uma Feature não carrega vinculações próprias: uma credencial de que ela precise preenche um slot que a Feature declara em seu próprio featuresSchema e é vinculada ao lado da Feature.
Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$.
Os valores são string[] or map of object.
Nenhuma outra chave é permitida.
connection_attachment
Uma vinculação que uma conexão carrega: a Feature que preenche um slot declarado pelo socket da conexão, com a configuração do desenvolvedor para ela.
| Propriedade | Tipo | Obrigatória | Descrição |
|---|---|---|---|
type | string | sim | A URI da interface de Feature que esta vinculação solicita (por exemplo, core/referenced-secret:1.0.0). |
description | string | não | Documentação opcional explicando por que esta conexão carrega a vinculação. |
values | object | não | Configuração fornecida pelo desenvolvedor 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 ele representa. |
annotations | mapa de string ou object ou null | não | Anotações escritas pelo desenvolvedor neste subsistema. Os valores são strings, objetos estruturados (um mapa de subchave para valor, mesclado por subchave com um valor estruturado herdado) ou null; um null explícito em uma chave herdada de um subsistema pai remove deste subsistema a associação herdada (renúncia a uma Feature guiada 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. Elas se propagam em cascata até o compartimento .context.annotations.aggregate em cada nó IR derivado. |
features | mapa de object | não | Funcionalidades transversais vinculadas a todos os componentes deste subsistema. Mesmo esquema das funcionalidades no nível do componente (type, values, uses, inject). Achatadas em cada componente na finalização do grafo, posicionadas após as funcionalidades no nível do componente na ordem de execução. Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$. |
subsystems | mapa de subsystem | não | Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$. |
components | mapa de component_instance | não | Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. 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 solicitado, como referência: seu metadata.name mais um :version opcional (por exemplo, core/api-server:1.0.0), nunca um caminho de arquivo. Resolvido pelo 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 em um diretório listado em workspace.catalog_dirs, e um type escrito como caminho de arquivo relativo interrompe o build 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 deve ser resolvido para um boolean. Quando é resolvido para false, o componente é removido da topologia, em cascata para suas arestas uses e suas vinculações. Derivar o valor de um parâmetro permite que uma Release ative ou desative a presença do componente ao atender esse parâmetro. Vale true quando omitido. Valor padrão: true |
description | string | não | Documentação opcional que descreve o papel desta instância de componente na aplicação. Levada até o grafo IR. |
annotations | mapa de string ou object ou null | não | Anotações escritas pelo desenvolvedor neste componente. Os valores são strings, objetos estruturados (um mapa de subchave para valor, mesclado por subchave com um valor estruturado herdado) ou null; um null explícito em uma chave herdada de um subsistema pai remove deste componente a associação herdada (renúncia a uma Feature guiada por anotações). As anotações no nível de Component substituem por chave as anotações herdadas no nível do subsistema; componentes irmãos no mesmo subsistema mantêm seus próprios mapas de anotações de forma independente. |
values | object | não | Propriedades cognitivas opacas passadas ao Component, validadas pelo seu esquema. |
uses | component_uses_block | não | As conexões que um componente traça até os componentes dos quais depende, indexadas por socket. Cada socket lista seus destinos, ou nomeia cada conexão sob um alias. Uma conexão nomeada sob um alias pode carregar os valores por conexão do desenvolvedor e as vinculações que preenchem os slots que o socket declara. |
inject | inject_block | não | Autoinjeção no nível de Component. Injeta os próprios valores do componente (via ‘value:’) ou suas próprias chaves provides (via ‘from:’) diretamente no pipe de entrega (.context.inject). Permitido somente se a entidade de catálogo Component declarar ‘spec.inject’ com os mecanismos correspondentes. Uma chave inject que colide com uma chave declarada em uses[].inject interrompe o build como chave de entrega duplicada entre fontes de inject. |
features | mapa de object | não | As Features vinculadas a este componente, indexadas pelo nome de instância que o autor dá a cada vinculação. Esta é a única superfície de vinculação: uma Feature operacional, uma Feature de credenciais (uma com o rótulo feature.aggrega.ai/kind: secret) e uma Feature de identidade são todas vinculadas aqui, com a mesma palavra-chave e a mesma forma. O que as diferencia é o que a vinculação produz, não como ela é declarada. Uma vinculação cujo nome de instância corresponde a um slot que o Component declara em featuresSchema preenche esse slot; qualquer outro nome de instância é uma vinculação livre. Chaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$. |
Não são permitidas propriedades adicionais.