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 entradaPodResourcessob os$defsdo 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 formaoci://<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 Aspec: 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 entryspec: schemas: ToolContract: type: object properties: side_effects: type: array items: { type: string, enum: [read, write, delete] }
# Consumer Componentspec: 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, ementities/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.