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 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 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 formaoci://<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 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á 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 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 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, ementities/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.