Gramática de URI e inventário de strings de formato
As entidades do Aggrega referenciam umas às outras por meio de strings URI que aparecem em várias posições de autoria distintas. A mesma forma de URI (core/postgres:1.0.0) aparece em cinco ou mais contextos de tipo de entidade, com o compilador inferindo o tipo de entidade a partir da posição no schema, e não de um sigilo ou prefixo. Autores que leem ou mantêm um arquivo YAML precisam ter em mente as regras de interpretação baseadas em posição para saber se core/postgres:1.0.0 se refere a um tipo de Component, um módulo Aggregate, uma Recipe, uma FeatureRecipe ou um plugin Wasm.
Esta página consolida a gramática de URI em todas as posições, as regras de precedência para chaves type: versionadas e não versionadas nos níveis de mapeamento do Manifest, as regras de inferência das formas abreviadas de URI OCI e o inventário mais amplo de strings de formato em todo o corpus (sintaxe de templates Go, funções Sprig, declarações JSON Schema 2020-12, JSONPath, padrões glob, regex SemVer). Autores que precisam saber “o que o Aggrega faz com esta string?” devem encontrar a resposta aqui.
Inferência do tipo de entidade baseada em posição
A mesma string URI tem um significado de tipo de entidade diferente dependendo de onde aparece no schema. A tabela abaixo enumera cada posição em que o Aggrega espera um URI de referência a entidade, junto com o tipo de entidade inferido:
| Position | Tipo de entidade inferido | Expansão do caminho OCI |
|---|---|---|
Aggregate.spec.components.<id>.type | Component | /component/{publisher}/{category}/{name} |
Aggregate.spec.subsystems.<name>.components.<id>.type | Component (igual a components — subsistemas são agrupamentos de componentes) | /component/{publisher}/{category}/{name} |
Aggregate.spec.aggregates.<id>.type | Aggregate (módulo de subagregado) | /aggregate/{publisher}/{name} |
Aggregate.spec.components.<id>.features.<id>.type | Feature | /feature/{publisher}/{name} |
Aggregate.spec.components.<id>.features.<id>.type | Feature (credencial — com o rótulo feature.aggrega.ai/kind: secret) | /feature/{publisher}/{name} |
Manifest.spec.mappings.components.type.<key> | Component (o URI usado como chave de pesquisa); o valor é um URI de Recipe | chave: /component/; valor: /recipe/{provider}/{name} |
Manifest.spec.mappings.components.name.<id> | Recipe (vinculação granular de substituição) | /recipe/{provider}/{name} |
Manifest.spec.mappings.features.type.<key> | Feature (chave de pesquisa); o valor é um URI de FeatureRecipe | chave: /feature/; valor: /featurerecipe/{provider}/{name} |
Manifest.spec.mappings.features.name.<id> | FeatureRecipe (vinculação granular de substituição) | /featurerecipe/{provider}/{name} |
Manifest.spec.mappings.features.annotations.<key>.feature | Feature (vinculada a uma anotação) | /feature/{publisher}/{name} |
Recipe.spec.implements | Component (contrato de interface) | /component/{publisher}/{category}/{name} |
FeatureRecipe.spec.implements | Feature (contrato de interface) | /feature/{publisher}/{name} |
Component.spec.extends / Feature.spec.extends | Component / Feature (pai na cadeia de herança) | /component/{publisher}/{category}/{name} ou /feature/{publisher}/{name} |
Manifest.spec.extends | Manifest (pai na cadeia de herança de mapeamentos) | não é uma posição de URI — um caminho relativo, ou o metadata.name simples de um Manifest ao lado da Release |
Release.spec.extends | Release (pai na cadeia de herança) | não é uma posição de URI — um caminho relativo para um arquivo de Release, e nenhuma outra forma |
Release.spec.aggregate | Aggregate (o destino de implantação da Release) | /aggregate/{publisher}/{name} |
Release.spec.manifest | Manifest (o lockfile de mapeamento da Release) | não é uma posição de URI — um caminho relativo, ou o metadata.name simples de um Manifest ao lado da Release |
FeatureRecipe.spec.pipeline.<step>.plugin | plugin Wasm | /plugin/{pluginType}/{name} |
Três posições são listadas porque os autores recorrem a elas esperando um URI, e elas não são um. Um Manifest e uma Release são documentos do lado da implantação escritos lado a lado, e não entidades indexadas no catálogo, de modo que nem o extends: de um nem o do outro, nem nenhum manifest: de uma Release, é resolvido em relação ao catálogo ou a um registro. O manifest: de uma Release nomeia um arquivo, ou o metadata.name simples de um Manifest situado ao lado da Release. Nas duas posições extends:, o valor nomeia um arquivo, e uma coordenada de registro escrita em qualquer uma delas é recusada, com a forma aceita nomeada no diagnóstico. As duas posições extends: também não são escritas da mesma forma — um Manifest também aceita o metadata.name simples de um Manifest situado ao lado da Release, enquanto uma Release aceita o caminho relativo e nada mais. Veja entities/release.md para a forma da Release e errors/fatal-halts.md para o que cada recusa diz.
A regra de inferência: a posição no schema YAML determina o tipo de entidade. Não há nenhum marcador de superfície (sigilo, prefixo, anotação no nível do schema) dizendo ao autor a que tipo de entidade um determinado campo type: faz referência. Os autores têm em mente as regras baseadas em posição ao ler YAML; as ferramentas (o preenchimento automático do editor, aggrega inspect) leem as mesmas regras para apresentar sugestões específicas do tipo de entidade.
Duas formas de URI — plugins de coordenadas derivadas vs. entidades de catálogo com o tipo nos metadados
Um URI de entidade de catálogo não carrega nenhum sigilo de tipo (a seção anterior). Os URIs de Plugin são o contraponto deliberado: um URI de plugin de fato escreve um segmento classificador — seu tipo de socket — diretamente no caminho. As duas famílias de referências são lidas de forma diferente de propósito, e saber a qual família um URI pertence diz a você onde procurar sua classificação.
As coordenadas de Plugin são derivadas do tipo do plugin. Uma referência de plugin é oci://hub.aggrega.ai/plugin/<pluginType>/<name>. A coordenada é derivada: o segmento <pluginType> e o <name> simples vêm do bloco de endereçamento do plugin — metadata.pluginType e metadata.name — compostos no caminho. O socket não é codificado como caminho no nome; metadata.name é simples. A coordenada derivada É a chave do registro (e do conjunto de plugins embutidos), de modo que o registro organiza os plugins por socket. Os plugins básicos são resolvidos para coordenadas como plugin/provider/helm, plugin/linter/publishing e plugin/parser/yaml — cada uma a composição de um metadata.name simples (helm, publishing, yaml) com seu metadata.pluginType (provider, linter, parser). O segmento <pluginType> é exatamente o tipo de socket do plugin: o mesmo <name> simples sob um pluginType diferente é um plugin diferente, porque a coordenada derivada — e portanto a identidade — difere. Para a taxonomia completa de sockets segundo a qual o segmento <pluginType> classifica, veja entities/plugin.md.
As entidades de catálogo carregam o tipo nos metadados. A referência escrita é <publisher>/<category>/<name> (por exemplo, core/datastore/postgres). O kind: da entidade fica no arquivo; o tipo de entidade do URI é inferido da posição no schema, conforme Inferência do tipo de entidade baseada em posição acima. O caminho é organizado por categoria, não por tipo: um Component carrega um segmento de categoria (core/datastore/postgres); uma Recipe ou uma FeatureRecipe carrega sua capacidade de renderização como primeiro segmento (helm/postgres); os tipos restantes são planos, <publisher>/<name>. Nada no caminho escreve o tipo de entidade.
Por que as duas formas diferem. Os Plugins são organizados no registro por socket, então o segmento do socket é a chave natural do registro e está presente em todo URI de plugin. As entidades de catálogo são organizadas no registro por categoria, então é a categoria — não o tipo — que o caminho escreve. Um URI, portanto, diz a você o socket de um plugin apenas pelo caminho, mas só diz o tipo de uma entidade de catálogo depois que você lê o arquivo (o tipo fica em metadata; a posição o fornece em um ponto de referência). Essa assimetria é intencional: o caminho de cada família espelha como essa família é organizada no registro, e não uma gramática única e uniforme imposta às duas.
Forma do URI — versionado vs. não versionado
Toda posição de URI acima aceita uma referência em uma de três formas — não versionada, ou fixada após dois-pontos com uma versão exata ou um intervalo com caret:
| Forma | Exemplo | Semântica |
|---|---|---|
| Sem versão | core/postgres | É resolvido para “qualquer versão” ou para “a mais recente registrada”, dependendo da semântica de resolução da posição |
| Fixação exata | core/postgres:1.0.0 | Fixa uma versão específica. A versão é uma versão semântica, a forma que o metadata.version de toda entidade assume |
| Fixação com caret | core/postgres:^1.0.0 | Seleciona a versão mais alta compatível com a indicada — para ^1.0.0, igual ou superior a 1.0.0 e inferior a 2.0.0 |
A fixação é o texto após os últimos dois-pontos da referência, e somente quando esse texto não contém nenhuma /. Uma referência a um host de registro com porta — localhost:5000/core/postgres — portanto não carrega nenhuma fixação: o texto após os dois-pontos da porta continua a referência.
Uma fixação que não tem nenhuma dessas formas — um caret cujo texto não pode ser lido como um intervalo de versões (core/postgres:^garbage), ou uma fixação exata que não é uma versão semântica (core/postgres:1.x, core/postgres:1.0, core/postgres:v1.0.0) — não nomeia versão alguma. Quando um comando resolve uma referência assim e ela não é resolvida, a recusa nomeia a referência, a fixação e as três formas acima, em vez de relatar uma entidade ou uma versão que o catálogo não contém; o diagnóstico é descrito em errors/fatal-halts.md em “A version pin is none of the forms a pin takes (Uma fixação de versão não tem nenhuma das formas que uma fixação assume)”. A fixação só é avaliada ali, de modo que uma fixação malformada nunca muda quais referências são resolvidas, e uma fixação bem formada que nenhuma versão disponível satisfaz é relatada como tal. Nenhum schema define a gramática da fixação, então uma fixação malformada é relatada quando algo resolve a referência — aggrega validate, aggrega pull, aggrega build — e não quando o arquivo é carregado.
As formas coexistem na mesma posição. Os autores escolhem conforme precisem de fixação de versão ou de flexibilidade de versão. O nível mappings.{components,features}.type do Manifest suporta ambas as variantes como chaves de dicionário distintas, com a precedência a chave versionada vence a não versionada — uma chave versionada (core/api-server:1.0.0) tem precedência sobre a chave não versionada (core/api-server) quando ambas correspondem à mesma pesquisa. As duas variantes não são exclusivas; ambas podem ficar no mesmo mapa type: e o resolvedor escolhe a mais específica. O despacho do Provider decorre do campo spec.capability da Recipe resolvida, de modo que o Manifest mapeia um tipo para uma Recipe e nada mais.
Para o regime de consumo de versões por entidade (quais entidades têm de fato seu campo de versão consumido pelo despacho de resolução e quais o usam como proveniência descritiva), veja vocabulary/inheritance-and-interface.md “Cross-entity version consumption (Consumo de versões entre entidades)”.
Uma referência a um Component, uma Feature, um Aggregate ou um Plugin também aceita um intervalo com caret (core/postgres:^1.0.0) e, qualquer que seja a forma, seleciona a versão mais alta que a satisfaz entre as que o catálogo contém, por uma única regra que todo comando aplica — veja version-resolution.md. Para a correspondência de três formas de implements:, que é a verificação de consistência de um mapeamento e não uma seleção, veja 10-status.md “Version matching (Correspondência de versões)”.
Identidade, não localização
Uma referência canônica a uma entidade — incluindo uma referência de plugin — é uma identidade, não uma localização: ela nomeia o que a entidade é, nunca onde ela está no momento.
A identidade é simples e sem host. Ela não carrega nenhum host de registro; o host é uma coordenada de resolução fornecida pela configuração por meio de default_registry e vinculada no momento da resolução. Mudar um registro de lugar, ou espelhar a mesma entidade em outro lugar, é uma mudança de configuração — as referências que nomeiam a entidade permanecem intactas.
A identidade também é sem versão. Uma referência pode carregar uma fixação de versão opcional (:<version> ou :^<version>) para restringir quais versões a satisfazem, e cada Release registra a versão exata resolvida como fixação em seu lockfile, mas a versão é fornecida ao lado da identidade em vez de embutida nela.
No momento da resolução, o compilador une a identidade simples ao host configurado e à versão fixada para chegar a bytes concretos. Como ambos são fornecidos separadamente, a mesma referência é resolvida em relação a um registro diferente ou a uma versão fixada diferente sem nenhuma edição no código-fonte que a nomeia.
Inferência das formas abreviadas de URI OCI
Os autores não precisam escrever cada URI como um URI OCI totalmente qualificado. O compilador aplica quatro regras de inferência ortogonais para expandir as formas abreviadas de autoria em URIs OCI canônicos no momento da resolução. As regras:
Regra 1 — Domínio padrão
Todo URI sem domínio recebe como prefixo o default_registry configurado em .aggrega-config.yaml (padrão: hub.aggrega.ai/).
# Shorthandtype: core/postgres:1.0.0
# Equivalent canonical formtype: hub.aggrega.ai/component/core/postgres:1.0.0Regra 2 — Expansão contextual da entidade
O compilador acrescenta o segmento de tipo de entidade correto com base na posição no schema. O mapeamento é o mesmo da tabela de inferência por posição acima (/component/, /aggregate/, /recipe/, /featurerecipe/, /feature/, /plugin/).
# Same string, two positions, two expansionsAggregate.spec.components.foo.type: core/postgres:1.0.0# → hub.aggrega.ai/component/core/postgres:1.0.0
Manifest.spec.mappings.components.type."core/postgres:1.0.0": helm/postgres:1.0.0# Key: hub.aggrega.ai/component/core/postgres:1.0.0# Value: hub.aggrega.ai/recipe/helm/postgres:1.0.0Regra 3 — Precedência em três camadas
Antes de aplicar a inferência OCI, o compilador resolve o URI por meio do modelo de resolução de entidades em três camadas documentado em architecture/13-catalog-and-registry.md:
- Caminho local — para os documentos que uma Release e seu Manifest nomeiam. O
aggregate, omanifestou oextendsde uma Release, ou oextendsde um Manifest, escritos com um prefixo./ou../, são lidos como um arquivo relativo ao próprio diretório da Release; a inferência OCI não é executada. Nenhuma outra posição aceita um caminho: umtype, uma chave ou um valor de mapeamento do Manifest, umimplementsou umpluginde pipeline escritos como./…não nomeiam nenhuma entidade e interrompem o build. Uma entidade escrita localmente é colocada emcatalog/na raiz do espaço de trabalho ou em um diretório queworkspace.catalog_dirslista, e é resolvida pelo nome por meio da camada do espaço de trabalho e do cache. - Espaço de trabalho e cache — a pilha de busca do catálogo do espaço de trabalho, depois o cache. Os diretórios
catalog_dirs:do espaço de trabalho de.aggrega-config.yaml— ou, para uma Release à qual a configuração dá diretórios próprios emworkspace.releases, os dessa Release — são pesquisados na ordem escrita, e o diretóriocatalog/da raiz do espaço de trabalho é pesquisado por último — depois de cada entrada listada, e somente quando esse diretório existe. Uma correspondência em qualquer ponto da pilha interrompe a inferência OCI. Uma falha consulta entãoartifact_cache_dir, que guarda o que pulls anteriores do registro buscaram. - Registro. Quando a camada do espaço de trabalho e do cache não encontra nada, as regras de inferência OCI se aplicam e a referência é buscada no registro remoto por
aggrega pull, ou por um build executado com--auto-pullou com a configuraçãoauto_pulldo espaço de trabalho; um build sem nenhum dos dois lê apenas o que seu lockfile fixa.
A cascata permite que um projeto misture os documentos que uma Release nomeia por caminho (a camada do caminho local) com conteúdo de catálogo copiado para o repositório e local ao espaço de trabalho (a camada do espaço de trabalho e do cache) e conteúdo do registro buscado remotamente (a camada do registro), e uma referência a uma entidade é escrita da mesma forma, qualquer que seja a das duas últimas camadas que contém a entidade.
Quando catalog_dirs: lista mais de um diretório, a lista é uma pilha de precedência ordenada em que o primeiro vence: uma identidade de entidade presente em mais de um diretório listado é resolvida para o diretório listado primeiro, e a ocorrência posterior é sombreada (substituída, não é um erro) — assim um projeto pode colocar seu próprio diretório de catálogo à frente de um compartilhado e substituir entidades pela identidade, enquanto o restante recai no compartilhado. A substituição é informada no detalhe da resolução. Dois arquivos que reivindicam a mesma identidade dentro de um único diretório continuam sendo um erro de autoria que interrompe o carregamento.
O diretório catalog/ da raiz do espaço de trabalho fica no fim dessa pilha, e não no topo, de modo que tudo o que um projeto lista prevalece sobre ele em uma colisão, e listar um diretório não relacionado nunca impede que ele seja lido. Ele é ignorado quando uma entrada listada já o alcança — a varredura de um diretório listado é recursiva, então uma pilha que nomeia a raiz do espaço de trabalho já o leu. Omitir catalog_dirs: e escrevê-lo como lista vazia são declarações diferentes: omitido, o espaço de trabalho ainda lê catalog/; escrito como [], ele não lê nenhum catálogo local, e é assim que um espaço de trabalho diz que não tem nenhum.
Regra 4 — Tratamento da versão
Um URI pode incluir ou omitir o segmento de versão. O tratamento da versão depende da posição de resolução (resolução do nível do Manifest, correspondência de implements:, importação de subagregados) conforme as regras de consumo de versões próprias da posição. Veja inheritance-and-interface.md “Cross-entity version consumption (Consumo de versões entre entidades)” para a semântica de versões por entidade.
Inventário de strings de formato
Além das strings URI, a superfície de autoria do Aggrega contém várias convenções distintas de strings de formato. Os autores que escrevem ou leem arquivos YAML encontram os seguintes formatos em posições diferentes:
| Formato | Onde é escrito | Validado por |
|---|---|---|
Template Go ({{ .field }}) | Recipe valuesMapping: / workload: / artifacts: / provides: / locals: / source:; FeatureRecipe injectMapping: / with: de pipeline; interpolação de parameters: no Aggregate; Release directory: / subDirectory: | Parser de templates Go no momento da avaliação; regras de disponibilidade por local em templates/expansion-matrix.md |
Referência de funções Sprig ({{ default 1 .v }} etc.) | As mesmas superfícies dos templates Go | FuncMap do Sprig v3 registrado na inicialização do mecanismo de templates; lista completa de helpers em templates/sprig-functions.md |
| JSON Schema 2020-12 (forma compacta ou completa) | Conteúdo schema: de Component / Feature (ou um $ref: para uma entrada de uma SchemaLibrary) | Validador JSON Schema no carregamento da entidade durante a resolução |
| JSON Pointer (RFC 6901) | Chaves locals.<*_path>: da Recipe (volumes_path, containers_path etc.); referências à saída das etapas de pipeline: da FeatureRecipe; payloads JSONPatch de plugins Wasm | Base RFC 6901 conforme o contrato de plugins Wasm; declarada em plugins/plugin-contract.md |
| Regex SemVer | Campos metadata.version em toda entidade | Regex JSON Schema ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-...)?$ por schema de entidade |
Fixação de versão (:<version>, :^<version>) | O segmento de versão de uma referência a uma entidade, em toda posição de URI acima | O compilador, quando resolve a referência: uma fixação exata é uma versão semântica e o intervalo de uma fixação com caret é analisado, e uma fixação malformada é recusada sob sua própria condição — veja Forma do URI acima |
| Caminho do sistema de arquivos | Caminhos relativos ao catálogo (por exemplo, entradas catalog_dirs: de .aggrega-config.yaml); caminhos de arquivo $import: da Recipe em workload: / artifacts: / valuesMapping: | Lido como escrito na resolução — uma entrada catalog_dirs: relativa ao arquivo de configuração que a declara, um caminho $import: relativo ao próprio diretório da entidade; nenhum glob é expandido, então um * nomeia um arquivo ou diretório com esse nome |
| Expressão de seletor de rótulos | Component.spec.usesSchema.<socket>.selector; appliesTo: / appliesToAnyOf: da Feature | Parser de seletores do Aggrega onde o seletor é avaliado; gramática de seletores documentada em vocabulary/modifier-system.md |
Forma da chave de anotação (<namespace>/<name>) | Chaves metadata.annotations; chaves features.annotations do Manifest; cascata de anotações da fronteira | Regex JSON Schema por entidade; disciplina de prefixos reservados em vocabulary/labels-and-annotations.md |
Nome do Provider, opcionalmente com fixação de versão (helm, helm:^1.0.0) | Recipe.spec.capability; FeatureRecipe.spec.capability | Busca de despacho do Provider; uma fixação que nenhuma versão de plugin satisfaz interrompe o build |
Chave de entrega de inject (env.<KEY>, file.<path>, arg.<flag>) | Blocos inject: do Aggregate; saída de injectMapping: da FeatureRecipe | Schema de inject em vocabulary/topology-triad.md |
Cada formato tem sua própria gramática, seu próprio validador e sua própria forma de relatar erros. Os autores que encontram um erro de análise de uma string de formato leem a referência do respectivo formato para as regras de sintaxe.
O editor relata esses erros enquanto você escreve: aggrega serve valida cada documento que recebe em relação ao schema do seu tipo e retorna o mesmo veredito que um build daria (veja cli/aggrega-serve.md “Live validation (Validação em tempo real)”), e aggrega scaffold cria o rascunho de um documento inicial de qualquer tipo.
Referências cruzadas
entities/manifest.md— resolução do nível de mapeamento do Manifest + seção URIs abreviados sensíveis ao contexto.entities/plugin.md— taxonomia de sockets de Plugin + a forma de URI codificada por socketplugin/<socket>/<name>.architecture/13-catalog-and-registry.md— modelo de resolução de entidades em três camadas + taxonomia OCI canônica para a distribuição do catálogo.vocabulary/inheritance-and-interface.md— vinculação de interfaceimplements:+ consumo de versões entre entidades.templates/expansion-matrix.md— regras de disponibilidade por local de template para as strings de formato de templates Go.templates/sprig-functions.md— inventário de helpers do Sprig v3 conectados ao mecanismo de templates.vocabulary/topology-triad.md— convenções das chaves de entrega de inject; a gramática das expressões de seletor está emvocabulary/modifier-system.md.vocabulary/labels-and-annotations.md— forma da chave de anotação e disciplina de prefixos reservados.10-status.md— estado de maturidade da correspondência de três formas deimplements:e dos comandos da CLI que resolvem referências.