Pular para o conteúdo
AggregaAggrega
Selecionar língua: Português (Brasil)
Esta página foi traduzida automaticamente. Leia 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 autoria de esquemas do Aggrega — o que os autores de Components, Features e entradas de SchemaLibrary veem quando um $ref: cruza a fronteira de um documento em direção a uma biblioteca, e as regras de required: por sintaxe que fixam quais formas de autoria funcionam bem com a expansão entre documentos.

$ref: é nativo do JSON Schema 2020-12. Ele 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 se concentra no caso entre documentos, em que $ref: aponta para uma entrada de SchemaLibrary em um arquivo separado ou em um artefato OCI.

Para a herança entre entidades do catálogo (Component-extends-Component), veja inheritance-and-interface.md. Uma Release que estende uma Release é um mecanismo diferente, sobre um documento que não é indexado no catálogo; ele 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 em uma SchemaLibrary por identidade — o catálogo a resolve, o lockfile fornece a versão — e se compõe em qualquer nó. $import: nomeia um arquivo ao lado da entidade e substitui o conteúdo inteiro pelo que esse arquivo contém. $import: se aplica na superfície de esquemas assim como em valuesMapping:, workload:, artifacts: e parameters:; para $import: em um esquema, veja compact-form-authoring.md §“Importing a contract from a file (Importar um contrato de um arquivo)”.

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

$ref: segue a resolução padrão do JSON Schema 2020-12. As seguintes formas de referência aparecem na prática:

  • Fragmentos locais dentro do mesmo documento: { $ref: "#/$defs/PodResources" } — resolve 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 em relação 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 carrega nenhum host de registry — uma forma oci://<host>/… com host é recusada na compilação com um diagnóstico que direciona o autor para a forma por identidade, de modo que uma localização física de registry nunca entra no código-fonte escrito. De onde os bytes da biblioteca são servidos (um diretório local do catálogo, o cache de conteúdo ou um registry remoto) é responsabilidade do resolvedor, definida no momento da resolução, nunca parte da referência.
  • Um caminho de arquivo 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 mantido em um arquivo ao lado da entidade é trazido com $import: em vez disso, que é limitado ao diretório da própria entidade, como todo arquivo 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 carrega o conteúdo incorporado, não a indireção.

$ref: se compõe 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 autoria ao declarar propriedades obrigatórias em um Component ou uma Feature: marcadores no nível da folha (required: true em cada propriedade) ou o array no nível do pai (required: [name1, name2, ...] no escopo 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 seção mostra.

Autoria em forma inferida sem $ref: — os marcadores no nível da folha se acumulam em tempo de compilação. O compilador percorre cada propriedade e, onde uma folha carrega required: true, contribui com o nome da propriedade para o 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 escopo 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 adiciona são os que ele escreve ali: um array required: no nível do pai, ou um marcador required: true no nível da folha em uma propriedade que ele declara sob properties:. Os requisitos próprios da entrada referenciada — marcadores no nível da folha na sua forma inferida, ou um array required: próprio — se aplicam através da referência sem alteração. Um array no nível do pai nomeia requisitos sem redeclarar as propriedades que a entrada já declara:

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

Um marcador no nível da folha também conta, em uma propriedade que o consumidor declara ao lado da referência — assim, properties: { database: { type: string, required: true } } escrito ali torna database obrigatório exatamente como required: [database] faz. A propriedade do consumidor substitui a propriedade da entrada com o mesmo nome (veja O consumidor restringe a entrada da biblioteca), então redeclare-a com a forma que você pretende.

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á sendo verificado, e a recusa não nomeia a entrada da biblioteca de onde a restrição veio; siga a cadeia de $ref: a partir do consumidor para encontrá-la.

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

# 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 mesclada, 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 se sustenta na sua própria proveniência.

Referências cruzadas

  • Para a herança entre entidades do catálogo (Component-extends-Component, Feature-extends-Feature), veja inheritance-and-interface.md.
  • Para a herança entre os documentos do lado da implantação, cujas referências nomeiam arquivos 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 provedor (Recipe.spec.source.chart:, Recipe.spec.source.modulePath:), veja a documentação da Recipe de cada entidade. Os ponteiros de origem de Provider não são unificados sob $ref:; o plugin do provedor os consome diretamente.
  • Para as regras de expansão das abreviações de URI OCI (domínio padrão, expansão contextual de entidades, precedência de resolução, tratamento de versões), veja uri-grammar.md.