Gramática de URI e inventário de cadeias de formato
As entidades do Aggrega referenciam-se umas às outras através de cadeias 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 a inferir o tipo de entidade a partir da posição no schema e não de um sigilo ou prefixo. Os autores que leem ou mantêm um ficheiro YAML têm de ter presentes as regras de interpretação baseadas na posição para saber se core/postgres:1.0.0 se refere a um tipo de Component, a um módulo Aggregate, a uma Recipe, a uma FeatureRecipe ou a 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: com e sem versão 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 cadeias 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). Os autores que precisem de saber «o que faz o Aggrega com esta cadeia?» devem encontrar aqui a resposta.
Inferência do tipo de entidade com base na posição
A mesma cadeia URI tem um significado de tipo de entidade diferente consoante o sítio onde aparece no schema. A tabela abaixo enumera cada posição em que o Aggrega espera um URI de referência a uma entidade, juntamente 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 — os 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 a etiqueta 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 (associaçã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 (associação granular de substituição) | /featurerecipe/{provider}/{name} |
Manifest.spec.mappings.features.annotations.<key>.feature | Feature (associada 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 ficheiro de Release, e nenhuma outra forma |
Release.spec.aggregate | Aggregate (o destino de implementaçã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} |
São listadas três posições porque os autores recorrem a elas à espera de um URI, e não o são. Um Manifest e uma Release são documentos do lado da implementação escritos lado a lado, e não entidades indexadas no catálogo, pelo 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 registo. O manifest: de uma Release indica um ficheiro, ou o metadata.name simples de um Manifest situado ao lado da Release. Nas duas posições extends:, o valor indica um ficheiro, e uma coordenada de registo escrita em qualquer uma delas é recusada, com a forma aceite indicada no diagnóstico. As duas posições extends: também não se escrevem da mesma forma — um Manifest aceita também o metadata.name simples de um Manifest situado ao lado da Release, enquanto uma Release aceita o caminho relativo e nada mais. Consulte entities/release.md para a forma da Release e errors/fatal-halts.md para o que diz cada recusa.
A regra de inferência: a posição no schema YAML determina o tipo de entidade. Não existe nenhum marcador de superfície (sigilo, prefixo, anotação ao nível do schema) que indique ao autor a que tipo de entidade se refere um determinado campo type:. Os autores têm presentes as regras baseadas na 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 tem nenhum sigilo de tipo (a secção anterior). Os URIs de Plugin são o contraponto deliberado: um URI de plugin escreve de facto um segmento classificador — o seu tipo de socket — diretamente no caminho. As duas famílias de referências leem-se de forma diferente de propósito, e saber a que família pertence um URI indica onde procurar a sua classificação.
As coordenadas de Plugin derivam 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 provê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 registo (e do conjunto de plugins incorporados), pelo que o registo organiza os plugins por socket. Os plugins de base resolvem-se em 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 o 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, consulte entities/plugin.md.
As entidades de catálogo têm o tipo nos metadados. A referência escrita é <publisher>/<category>/<name> (por exemplo, core/datastore/postgres). O kind: da entidade está no ficheiro; o tipo de entidade do URI é inferido da posição no schema, conforme Inferência do tipo de entidade com base na posição acima. O caminho organiza-se por categoria, não por tipo: um Component tem um segmento de categoria (core/datastore/postgres); uma Recipe ou uma FeatureRecipe tem a 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.
Porque diferem as duas formas. Os Plugins estão organizados no registo por socket, pelo que o segmento do socket é a chave natural do registo e está presente em todos os URIs de plugin. As entidades de catálogo estão organizadas no registo por categoria, pelo que é a categoria — não o tipo — que o caminho escreve. Um URI indica, portanto, o socket de um plugin apenas a partir do caminho, mas só indica o tipo de uma entidade de catálogo depois de lido o ficheiro (o tipo está em metadata; a posição fornece-o num ponto de referência). Esta assimetria é intencional: o caminho de cada família espelha a forma como essa família está organizada no registo, e não uma gramática única e uniforme imposta a ambas.
Forma do URI — com versão vs. sem versão
Todas as posições de URI acima aceitam uma referência numa de três formas — sem versão, 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 | Resolve-se em «qualquer versão» ou em «a mais recente registada», consoante a 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 cada 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 a seguir aos últimos dois pontos da referência, e apenas quando esse texto não contém nenhuma /. Uma referência a um host de registo com porta — localhost:5000/core/postgres — não tem, portanto, nenhuma fixação: o texto a seguir aos dois pontos da porta continua a referência.
Uma fixação que não tem nenhuma destas formas — um caret cujo texto não se lê 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 indica versão nenhuma. Quando um comando resolve uma referência destas e esta não se resolve, a recusa indica a referência, a fixação e as três formas acima, em vez de reportar uma entidade ou uma versão que o catálogo não contém; o diagnóstico está 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 aí, pelo que uma fixação malformada nunca altera que referências se resolvem, e uma fixação bem formada que nenhuma versão disponível satisfaz é reportada como tal. Nenhum schema define a gramática da fixação, pelo que uma fixação malformada é reportada quando algo resolve a referência — aggrega validate, aggrega pull, aggrega build — e não quando o ficheiro é carregado.
As formas coexistem na mesma posição. Os autores escolhem consoante precisem de fixar a 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 com versão ganha à chave sem versão — uma chave com versão (core/api-server:1.0.0) tem precedência sobre a chave sem versão (core/api-server) quando ambas correspondem à mesma pesquisa. As duas variantes não são exclusivas; ambas podem estar no mesmo mapa type: e o resolvedor escolhe a mais específica. O despacho do Provider decorre do campo spec.capability da Recipe resolvida, pelo que o Manifest mapeia um tipo para uma Recipe e nada mais.
Para o regime de consumo de versões por entidade (que entidades têm efetivamente o seu campo de versão consumido pelo despacho de resolução e quais o usam como proveniência descritiva), consulte vocabulary/inheritance-and-interface.md «Cross-entity version consumption (Consumo de versões entre entidades)».
Uma referência a um Component, a uma Feature, a um Aggregate ou a um Plugin aceita também um intervalo com caret (core/postgres:^1.0.0) e, seja qual for a sua forma, seleciona a versão mais alta que a satisfaz entre as que o catálogo contém, segundo uma única regra que todos os comandos aplicam — consulte 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, consulte 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: indica o que a entidade é, nunca onde se encontra atualmente.
A identidade é simples e sem host. Não tem nenhum host de registo; o host é uma coordenada de resolução fornecida pela configuração através de default_registry e associada no momento da resolução. Mudar um registo de sítio, ou espelhar a mesma entidade noutro lado, é uma alteração de configuração — as referências que indicam a entidade ficam intactas.
A identidade é também sem versão. Uma referência pode ter uma fixação de versão opcional (:<version> ou :^<version>) para restringir que versões a satisfazem, e cada Release regista a versão exata resolvida como fixação no seu lockfile, mas a versão é fornecida ao lado da identidade em vez de nela incorporada.
No momento da resolução, o compilador junta 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 resolve-se face a um registo diferente ou a uma versão fixada diferente sem nenhuma edição na fonte que a indica.
Inferência das formas abreviadas de URI OCI
Os autores não têm de 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 predefinido
A qualquer URI sem domínio é anteposto o default_registry configurado em .aggrega-config.yaml (predefiniçã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 de três níveis
Antes de aplicar a inferência OCI, o compilador resolve o URI através do modelo de resolução de entidades em três níveis documentado em architecture/13-catalog-and-registry.md:
- Caminho local — para os documentos que uma Release e o seu Manifest indicam. O
aggregate, omanifestou oextendsde uma Release, ou oextendsde um Manifest, escritos com um prefixo./ou../, são lidos como um ficheiro 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 indicam nenhuma entidade e interrompem o build. Uma entidade escrita localmente é colocada emcatalog/na raiz do espaço de trabalho ou num diretório queworkspace.catalog_dirslista, e resolve-se pelo nome através do nível do espaço de trabalho e da cache. - Espaço de trabalho e cache — a pilha de pesquisa do catálogo do espaço de trabalho, depois a cache. Os diretórios
catalog_dirs:do espaço de trabalho de.aggrega-config.yaml— ou, para uma Release à qual a configuração atribui diretórios próprios emworkspace.releases, os dessa Release — são pesquisados pela ordem escrita, e o diretóriocatalog/da raiz do espaço de trabalho é pesquisado em último lugar — depois de cada entrada listada, e apenas 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 registo obtiveram. - Registo. Quando o nível do espaço de trabalho e da cache não encontra nada, aplicam-se as regras de inferência OCI e a referência é obtida do registo remoto por
aggrega pull, ou por um build executado com--auto-pullou com a definiçãoauto_pulldo espaço de trabalho; um build sem nenhum dos dois lê apenas o que o seu lockfile fixa.
A cascata permite a um projeto combinar os documentos que uma Release indica por caminho (o nível do caminho local) com conteúdo de catálogo incorporado e local ao espaço de trabalho (o nível do espaço de trabalho e da cache) e com conteúdo do registo obtido remotamente (o nível do registo), e uma referência a uma entidade escreve-se da mesma forma, seja qual for o dos dois últimos níveis que contém a entidade.
Quando catalog_dirs: lista mais do que um diretório, a lista é uma pilha de precedência em que o primeiro ganha, ordenada: uma identidade de entidade presente em mais do que um diretório listado resolve-se no diretório listado primeiro, e a ocorrência posterior é sombreada (substituída, sem ser um erro) — assim, um projeto pode colocar o seu próprio diretório de catálogo à frente de um partilhado e substituir entidades pela identidade, enquanto as restantes recaem sobre o partilhado. A substituição é reportada no detalhe da resolução. Dois ficheiros que reclamem a mesma identidade dentro de um único diretório continuam a ser 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, pelo que tudo o que um projeto lista prevalece sobre ele numa colisão, e listar um diretório não relacionado nunca impede que seja lido. É ignorado quando uma entrada listada já o alcança — o percurso de um diretório listado é recursivo, pelo que uma pilha que indica 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 continua a ler catalog/; escrito como [], não lê nenhum catálogo local, e é assim que um espaço de trabalho declara 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) segundo as regras de consumo de versões próprias da posição. Consulte 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 cadeias de formato
Para além das cadeias URI, a superfície de autoria do Aggrega contém várias convenções distintas de cadeias de formato. Os autores que escrevem ou leem ficheiros 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 registada na inicialização do motor 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 dos passos de pipeline: da FeatureRecipe; payloads JSONPatch de plugins Wasm | Base RFC 6901 segundo o contrato de plugins Wasm; declarada em plugins/plugin-contract.md |
| Regex SemVer | Campos metadata.version em todas as entidades | 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 todas as posições 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 a sua própria condição — consulte Forma do URI acima |
| Caminho do sistema de ficheiros | Caminhos relativos ao catálogo (por exemplo, entradas catalog_dirs: de .aggrega-config.yaml); caminhos de ficheiro $import: da Recipe em workload: / artifacts: / valuesMapping: | Lido tal como está escrito na resolução — uma entrada catalog_dirs: relativa ao ficheiro de configuração que a declara, um caminho $import: relativo ao próprio diretório da entidade; nenhum glob é expandido, pelo que um * indica um ficheiro ou diretório com esse nome |
| Expressão de seletor de etiquetas | 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 dos 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 | Pesquisa 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 a sua própria gramática, o seu próprio validador e a sua própria forma de reportar erros. Os autores que encontram um erro de análise de uma cadeia de formato leem a referência do respetivo formato para as regras de sintaxe.
O editor reporta estes erros durante a escrita: aggrega serve valida cada documento que recebe face ao schema do seu tipo e devolve o mesmo veredicto que um build daria (consulte 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 + secçã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 níveis + taxonomia OCI canónica para a distribuição do catálogo.vocabulary/inheritance-and-interface.md— associação de interfaceimplements:+ consumo de versões entre entidades.templates/expansion-matrix.md— regras de disponibilidade por local de template para as cadeias de formato de templates Go.templates/sprig-functions.md— inventário de helpers do Sprig v3 ligados ao motor 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 dos 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.