Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Portugal)
Esta página foi traduzida automaticamente. Ler o original em inglês.

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

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

PropriedadeTipoObrigatóriaDescrição
namestringsimPelo menos 1 carácter.
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 dos responsáveis pela manutenção desta entidade.
licensestringnãoIdentificador 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.
repositorystringnãoO URL do repositório Git onde se encontram os ficheiros de origem.
homestringnãoO URL da página inicial, da wiki ou da documentação desta entidade.
keywordsstring[]nãoUma lista de palavras-chave descritivas para facilitar a descoberta na interface do utilizador.
labelsmapa de stringnãoEtiquetas 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[]
PropriedadeTipoObrigatóriaDescrição
namestringsim
emailstringnão
urlstringnã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.

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

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..inject), ou a strings literais / expressões de template e às 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 fundidos numa única vista em .context.inject.all, pelo que um mecanismo com esse nome ficaria oculto por ela, e nomear um assim interrompe a compilação.

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

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.

PropriedadeTipoObrigatóriaDescrição
typestringsimO URI da interface de Feature que este anexo solicita (por exemplo, core/referenced-secret:1.0.0).
descriptionstringnãoDocumentação opcional que explica por que motivo esta ligação transporta o anexo.
valuesobjetonãoConfiguração fornecida pelo programador 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 representa.
annotationsmapa de string ou object ou nullnãoAnotaçõ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.
featuresmapa de objectnãoFuncionalidades 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_-]+$.
subsystemsmapa de subsystemnãoChaves: uma ou mais letras, algarismos, sublinhados ou hífenes. Não é permitido um ponto. Padrão: ^[a-zA-Z0-9_-]+$.
componentsmapa de component_instancenãoChaves: 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

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