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 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

PropriedadeTipoObrigatóriaDescrição
apiVersionconst “aggrega.ai/v1beta1”simConstante: "aggrega.ai/v1beta1"
kindconst “Aggregate”simConstante: "Aggregate"
metadataobjectsim
defsstring[]nãoBloco 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.
specobjectsimA 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

PropriedadeTipoObrigatóriaDescrição
namestringsimPelo menos 1 caractere.
versionstringsimVersionamento 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-]+)*))?$.
descriptionstringnão
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.
labelsmapa de stringnãoRó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[]
PropriedadeTipoObrigatóriaDescrição
namestringsim
emailstringnão
urlstringnã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.

PropriedadeTipoObrigatóriaDescrição
parametersmapa de objectnãoContrato 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: }); a camada do contrato de parâmetros valida o mapa mesclado em relação a este contrato antes da interpolação de parâmetros. A página do Aggregate na referência da linguagem ensina o vocabulário completo.
aggregatesmapa de objectnãoAgregados 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_-]+$.
exportedComponentsmapa de stringnãoA 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.
subsystemsmapa de subsystemnãoAgrupamentos 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_-]+$.
componentsmapa de component_instancenãoO 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..inject de uma vinculação, ou em relação aos provides do próprio componente no contexto component.inject. No features..inject de uma vinculação, um ‘from’ que nomeia uma chave que a FeatureRecipe não publica interrompe o build, a menos que essa FeatureRecipe leia ela mesma as entradas da vinculação em .inject em um template que ela avalia em relação ao contexto de renderização da vinculação (seu valuesMapping, workload, artifacts, omits, ou o with ou o when de uma etapa de pipeline — não seu injectMapping), caso em que a chave é uma que ela consome, e não uma entregue pelo .context.inject do componente. ‘value’ é entregue apenas em component.inject: uma entrada que o traz em uses[].inject ou no features..inject de uma vinculação interrompe o build, porque esses blocos entregam apenas chaves que outra entidade publica.

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..inject), ou para strings literais / expressões de template e as chaves provides do próprio componente (component.inject). Cada mecanismo de entrega (env, file, arg ou personalizado) é escrito como um array de entradas {in, from?, value?} — ‘from’ explícito para referências a provides e ‘value’ para literais. Um mecanismo personalizado pode ter qualquer nome exceto all: um template lê todos os mecanismos mesclados em uma única visão em .context.inject.all, de modo que um mecanismo com esse nome ficaria oculto por ela, e nomear um assim interrompe o build.

PropriedadeTipoObrigatóriaDescrição
envinject_deliverynãoUm ú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..inject de uma vinculação, ou em relação aos provides do próprio componente no contexto component.inject. No features..inject de uma vinculação, um ‘from’ que nomeia uma chave que a FeatureRecipe não publica interrompe o build, a menos que essa FeatureRecipe leia ela mesma as entradas da vinculação em .inject em um template que ela avalia em relação ao contexto de renderização da vinculação (seu valuesMapping, workload, artifacts, omits, ou o with ou o when de uma etapa de pipeline — não seu injectMapping), caso em que a chave é uma que ela consome, e não uma entregue pelo .context.inject do componente. ‘value’ é entregue apenas em component.inject: uma entrada que o traz em uses[].inject ou no features..inject de uma vinculação interrompe o build, porque esses blocos entregam apenas chaves que outra entidade publica.
fileinject_deliverynãoUm ú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..inject de uma vinculação, ou em relação aos provides do próprio componente no contexto component.inject. No features..inject de uma vinculação, um ‘from’ que nomeia uma chave que a FeatureRecipe não publica interrompe o build, a menos que essa FeatureRecipe leia ela mesma as entradas da vinculação em .inject em um template que ela avalia em relação ao contexto de renderização da vinculação (seu valuesMapping, workload, artifacts, omits, ou o with ou o when de uma etapa de pipeline — não seu injectMapping), caso em que a chave é uma que ela consome, e não uma entregue pelo .context.inject do componente. ‘value’ é entregue apenas em component.inject: uma entrada que o traz em uses[].inject ou no features..inject de uma vinculação interrompe o build, porque esses blocos entregam apenas chaves que outra entidade publica.
arginject_deliverynãoUm ú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..inject de uma vinculação, ou em relação aos provides do próprio componente no contexto component.inject. No features..inject de uma vinculação, um ‘from’ que nomeia uma chave que a FeatureRecipe não publica interrompe o build, a menos que essa FeatureRecipe leia ela mesma as entradas da vinculação em .inject em um template que ela avalia em relação ao contexto de renderização da vinculação (seu valuesMapping, workload, artifacts, omits, ou o with ou o when de uma etapa de pipeline — não seu injectMapping), caso em que a chave é uma que ela consome, e não uma entregue pelo .context.inject do componente. ‘value’ é entregue apenas em component.inject: uma entrada que o traz em uses[].inject ou no features..inject de uma vinculação interrompe o build, porque esses blocos entregam apenas chaves que outra entidade publica.

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.

PropriedadeTipoObrigatóriaDescrição
typestringsimA URI da interface de Feature que esta vinculação solicita (por exemplo, core/referenced-secret:1.0.0).
descriptionstringnãoDocumentação opcional explicando por que esta conexão carrega a vinculação.
valuesobjectnãoConfiguração fornecida pelo desenvolvedor para a Feature, validada pela declaração do seu esquema.

Não são permitidas propriedades adicionais.

subsystem

PropriedadeTipoObrigatóriaDescrição
descriptionstringnãoDocumentação opcional que descreve o propósito deste subsistema e o agrupamento lógico que ele representa.
annotationsmapa de string ou object ou nullnãoAnotaçõ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.
featuresmapa de objectnãoFuncionalidades 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_-]+$.
subsystemsmapa de subsystemnãoChaves: uma ou mais letras, dígitos, sublinhados ou hifens. Um ponto não é permitido. Padrão: ^[a-zA-Z0-9_-]+$.
componentsmapa de component_instancenãoChaves: 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

PropriedadeTipoObrigatóriaDescrição
typestringsimO 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.
activeboolean ou stringnãoIndica 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
descriptionstringnãoDocumentação opcional que descreve o papel desta instância de componente na aplicação. Levada até o grafo IR.
annotationsmapa de string ou object ou nullnãoAnotaçõ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.
valuesobjectnãoPropriedades cognitivas opacas passadas ao Component, validadas pelo seu esquema.
usescomponent_uses_blocknãoAs 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.
injectinject_blocknãoAutoinjeçã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.
featuresmapa de objectnãoAs 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.