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

Resolução de `$ref:` entre documentos

Esta página documenta a semântica de resolução das referências $ref: entre documentos na superfície de criação de esquemas do Aggrega — o que os autores de Components, Features e entradas de SchemaLibrary veem quando um $ref: atravessa a fronteira de um documento em direção a uma biblioteca, e as regras de required: por sintaxe que fixam quais as formas de criação que funcionam sem problemas com a expansão entre documentos.

$ref: é nativo do JSON Schema 2020-12. Aparece dentro do conteúdo de schema: (entradas de Component, Feature e SchemaLibrary), dentro de esquemas em forma compacta e dentro da camada de JSON Schema sintetizada que usesSchema: e featuresSchema: emitem. Esta página centra-se no caso entre documentos, em que $ref: aponta para uma entrada de SchemaLibrary num ficheiro separado ou num artefacto OCI.

Para a herança entre entidades do catálogo (Component-extends-Component), ver inheritance-and-interface.md. Uma Release que estende uma Release é um mecanismo diferente, sobre um documento que não está indexado no catálogo; está documentado em entities/release.md.

$import: é a outra palavra-chave que alcança conteúdo fora do documento, e as duas respondem a perguntas diferentes. $ref: nomeia uma entrada numa SchemaLibrary por identidade — o catálogo resolve-a, o lockfile fornece a versão — e compõe-se em qualquer nó. $import: nomeia um ficheiro ao lado da entidade e substitui o conteúdo inteiro pelo que esse ficheiro contém. $import: aplica-se na superfície de esquemas, bem como em valuesMapping:, workload:, artifacts: e parameters:; para $import: num esquema, ver compact-form-authoring.md §«Importing a contract from a file (Importar um contrato a partir de um ficheiro)».

Semântica de resolução de $ref:

$ref: segue a resolução normalizada do JSON Schema 2020-12. Na prática, surgem as seguintes formas de referência:

  • Fragmentos locais dentro do mesmo documento: { $ref: "#/$defs/PodResources" } — resolve-se para a entrada PodResources sob os $defs do esquema.
  • Referências a entradas de SchemaLibrary por identidade: { $ref: "WebPrimitives#/schemas/URL" } — a forma de nome simples <Library>#/schemas/<Entry>. O nome da biblioteca é resolvido face ao catálogo resolvido e o fragmento JSON Pointer #/schemas/<Entry> seleciona a entrada; a versão é fornecida pelo lockfile, não pela referência. Uma referência não contém nenhum host de registry — uma forma oci://<host>/… com host é recusada na compilação com um diagnóstico que encaminha o autor para a forma por identidade, pelo que uma localização física de registry nunca entra no código-fonte escrito. O local de onde os bytes da biblioteca são servidos (um diretório local do catálogo, a cache de conteúdo ou um registry remoto) é da responsabilidade do resolvedor, fixado no momento da resolução, e nunca faz parte da referência.
  • Um caminho de ficheiro não é um destino de referência: { $ref: "./schemas/foo.yaml#/definitions/Foo" } é recusado quando o esquema é compilado, com um diagnóstico que nomeia a forma <Library>#/schemas/<Entry>. O conteúdo de esquema guardado num ficheiro ao lado da entidade é trazido antes com $import:, que está limitado ao diretório da própria entidade, como qualquer ficheiro que uma entidade lê.

A referência é resolvida em tempo de compilação. O expansor incorpora o conteúdo referenciado no esquema do consumidor; a IR renderizada contém o conteúdo incorporado, não a indireção.

$ref: compõe-se naturalmente com as palavras-chave de composição do JSON Schema:

secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }
- description: "Replication-mode secondary instances."

O allOf compõe a forma NodePool referenciada com as restrições adicionais.

Sintaxe de required: sob um $ref: entre documentos

Os autores do catálogo escolhem entre duas formas de criação ao declarar propriedades obrigatórias num Component ou numa Feature: marcadores ao nível da folha (required: true em cada propriedade) ou o array ao nível do pai (required: [name1, name2, ...] no âmbito do objeto). Ambas as formas são válidas no JSON Schema 2020-12, e ambas contam sob a expansão de $ref: entre documentos, escritas onde esta secção mostra.

Criação em forma inferida sem $ref: — os marcadores ao nível da folha acumulam-se em tempo de compilação. O compilador percorre cada propriedade e, onde uma folha tem required: true, acrescenta o nome da propriedade ao array required: do pai sintetizado.

spec:
schema:
values:
database: { type: string, required: true }
display_name: { type: string, required: true }
default_locale: { type: string, default: "en-US" }

O compilador emite required: [database, display_name] no âmbito do pai.

Consumidores com $ref: — ao lado de um $ref: entre documentos só podem ser escritos properties, required e description, e os requisitos que o consumidor acrescenta são os que escreve aí: um array required: ao nível do pai, ou um marcador required: true ao nível da folha numa propriedade que declara sob properties:. Os requisitos próprios da entrada referenciada — marcadores ao nível da folha na sua forma inferida, ou um array required: próprio — aplicam-se através da referência sem alteração. Um array ao nível do pai nomeia requisitos sem voltar a declarar as propriedades que a entrada já declara:

spec:
schema:
values:
$ref: "Datastores#/schemas/PostgresPayload"
required: [database, display_name]

Um marcador ao nível da folha também conta, numa propriedade que o consumidor declara ao lado da referência — assim, properties: { database: { type: string, required: true } } escrito aí torna database obrigatório exatamente como required: [database] faz. A propriedade do consumidor substitui a propriedade da entrada com o mesmo nome (ver O consumidor restringe a entrada da biblioteca), pelo que deve ser declarada de novo com a forma pretendida.

Expansão de cadeias de biblioteca para biblioteca

Uma entrada de SchemaLibrary pode ela própria conter um $ref: que aponta para outra entrada de SchemaLibrary, produzindo uma cadeia. O compilador percorre a cadeia em tempo de compilação: cada $ref: encontrado enquanto uma entrada é expandida é ele próprio expandido, nos termos da biblioteca que o contém.

# Library A
spec:
schemas:
DatabasePayload:
type: object
properties:
host: { type: string }
credentials: { $ref: "Credentials#/schemas/BasicAuth" }
# Library B (referenced from library A above)
spec:
schemas:
BasicAuth:
type: object
properties:
username: { type: string }
password: { type: string }

Um Component consumidor que referencia DatabasePayload recebe a forma totalmente expandida, com credentials preenchido a partir do BasicAuth da biblioteca B. Um valor que viola uma restrição contribuída pela cadeia é recusado no seu próprio caminho no documento que está a ser verificado, e a recusa não nomeia a entrada da biblioteca de onde a restrição veio; para a encontrar, basta seguir a cadeia de $ref: a partir do consumidor.

O consumidor restringe a entrada da biblioteca

Um Component consumidor pode declarar uma propriedade cujo nome corresponde a uma propriedade trazida de uma entrada de biblioteca. Quando isso acontece, a propriedade compilada do consumidor substitui inteiramente a da entrada de biblioteca na forma combinada.

# Library entry
spec:
schemas:
ToolContract:
type: object
properties:
side_effects:
type: array
items: { type: string, enum: [read, write, delete] }
# Consumer Component
spec:
schema:
values:
$ref: "Tools#/schemas/ToolContract"
properties:
side_effects:
type: array
items: { type: string, enum: [read] }
default: [read]

Na forma combinada, side_effects reflete o contrato mais restrito do consumidor (enum: [read], com um default); o enum: [read, write, delete] mais amplo da entrada de biblioteca desaparece. A propriedade é escrita pelo consumidor.

Este é o comportamento esperado: consumidores que refinam a propriedade de uma entrada de biblioteca são o padrão canónico de restrição. A restrição é silenciosa: a propriedade do consumidor assenta na sua própria proveniência.

Referências cruzadas

  • Para a herança entre entidades do catálogo (Component-extends-Component, Feature-extends-Feature), ver inheritance-and-interface.md.
  • Para a herança entre os documentos do lado da implementação, cujas referências nomeiam ficheiros em vez de entidades do catálogo: uma Release que estende uma Release está documentada em entities/release.md, e um Manifest que estende um Manifest, em entities/manifest.md.
  • Para ponteiros de origem específicos do fornecedor (Recipe.spec.source.chart:, Recipe.spec.source.modulePath:), ver a documentação da Recipe de cada entidade. Os ponteiros de origem de Provider não são unificados sob $ref:; o plugin do fornecedor consome-os diretamente.
  • Para as regras de expansão das abreviaturas de URI OCI (domínio predefinido, expansão contextual de entidades, precedência de resolução, tratamento de versões), ver uri-grammar.md.