Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Risoluzione di `$ref:` tra documenti

Questa pagina documenta la semantica di risoluzione dei riferimenti $ref: tra documenti nella superficie di scrittura degli schemi di Aggrega — ciò che vedono gli autori di Components, Features e voci di SchemaLibrary quando un $ref: attraversa il confine di un documento verso una libreria, e le regole required: per sintassi che stabiliscono quali forme di scrittura funzionano senza problemi con l’espansione tra documenti.

$ref: è nativo di JSON Schema 2020-12. Compare all’interno del contenuto di schema: (voci di Component, Feature e SchemaLibrary), all’interno degli schemi in forma compatta e all’interno dello strato JSON Schema sintetizzato che usesSchema: e featuresSchema: emettono. Questa pagina si concentra sul caso tra documenti, in cui $ref: punta a una voce di SchemaLibrary in un file separato o in un artefatto OCI.

Per l’ereditarietà tra entità del catalogo (Component-extends-Component), vedi inheritance-and-interface.md. Una Release che estende una Release è un meccanismo diverso, su un documento che non è indicizzato nel catalogo; è documentato in entities/release.md.

$import: è l’altra parola chiave che raggiunge contenuti esterni al documento, e le due rispondono a domande diverse. $ref: nomina una voce in una SchemaLibrary per identità — il catalogo la risolve, il lockfile fornisce la versione — e si compone in qualsiasi nodo. $import: nomina un file accanto all’entità e sostituisce l’intero contenuto con ciò che quel file contiene. $import: si applica sulla superficie degli schemi così come in valuesMapping:, workload:, artifacts: e parameters:; per $import: su uno schema, vedi compact-form-authoring.md §«Importing a contract from a file (Importare un contratto da un file)».

Semantica di risoluzione di $ref:

$ref: segue la risoluzione standard di JSON Schema 2020-12. In pratica compaiono le seguenti forme di riferimento:

  • Frammenti locali all’interno dello stesso documento: { $ref: "#/$defs/PodResources" } — si risolve nella voce PodResources sotto i $defs dello schema.
  • Riferimenti a voci di SchemaLibrary per identità: { $ref: "WebPrimitives#/schemas/URL" } — la forma a nome semplice <Library>#/schemas/<Entry>. Il nome della libreria si risolve rispetto al catalogo risolto e il frammento JSON Pointer #/schemas/<Entry> seleziona la voce; la versione è fornita dal lockfile, non dal riferimento. Un riferimento non porta alcun host di registry — una forma con host oci://<host>/… viene rifiutata in compilazione con una diagnostica che indirizza l’autore verso la forma per identità, così una posizione fisica di registry non entra mai nel sorgente scritto. Da dove vengono serviti i byte della libreria (una directory locale del catalogo, la cache dei contenuti o un registry remoto) è compito del risolutore, stabilito al momento della risoluzione, mai parte del riferimento.
  • Un percorso di file non è un target di riferimento: { $ref: "./schemas/foo.yaml#/definitions/Foo" } viene rifiutato quando lo schema si compila, con una diagnostica che nomina la forma <Library>#/schemas/<Entry>. Il contenuto di schema tenuto in un file accanto all’entità si porta invece dentro con $import:, che è limitato alla directory propria dell’entità come ogni file che un’entità legge.

Il riferimento si risolve in fase di compilazione. L’espansore incorpora il contenuto referenziato nello schema del consumatore; l’IR renderizzato porta il contenuto incorporato, non l’indirezione.

$ref: si compone naturalmente con le parole chiave di composizione di JSON Schema:

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

L’allOf compone la forma NodePool referenziata con i vincoli aggiuntivi.

Sintassi di required: sotto un $ref: tra documenti

Gli autori del catalogo scelgono tra due forme di scrittura quando dichiarano proprietà obbligatorie su un Component o una Feature: marcatori a livello di foglia (required: true su ogni proprietà) o l’array a livello del genitore (required: [name1, name2, ...] nell’ambito dell’oggetto). Entrambe le forme sono valide in JSON Schema 2020-12, ed entrambe contano sotto l’espansione di $ref: tra documenti, se scritte dove mostra questa sezione.

Scrittura in forma inferita senza $ref: — i marcatori a livello di foglia si accumulano in fase di compilazione. Il compilatore percorre ogni proprietà e, dove una foglia porta required: true, aggiunge il nome della proprietà all’array required: del genitore sintetizzato.

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

Il compilatore emette required: [database, display_name] nell’ambito del genitore.

Consumatori che portano un $ref: — accanto a un $ref: tra documenti si possono scrivere solo properties, required e description, e i requisiti che il consumatore aggiunge sono quelli che scrive lì: un array required: a livello del genitore, o un marcatore required: true a livello di foglia su una proprietà che dichiara sotto properties:. I requisiti propri della voce referenziata — marcatori a livello di foglia nella sua forma inferita, o un proprio array required: — si applicano attraverso il riferimento senza modifiche. Un array a livello del genitore nomina i requisiti senza ridichiarare le proprietà che la voce dichiara già:

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

Conta anche un marcatore a livello di foglia, su una proprietà che il consumatore dichiara accanto al riferimento — così properties: { database: { type: string, required: true } } scritto lì rende database obbligatorio esattamente come fa required: [database]. La proprietà del consumatore sostituisce la proprietà della voce con lo stesso nome (vedi Il consumatore restringe la voce di libreria), quindi ridichiarala con la forma che intendi.

Espansione delle catene da libreria a libreria

Una voce di SchemaLibrary può a sua volta contenere un $ref: che punta a un’altra voce di SchemaLibrary, producendo una catena. Il compilatore percorre la catena in fase di compilazione: ogni $ref: incontrato mentre una voce viene espansa viene a sua volta espanso, nei termini della libreria che lo contiene.

# 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 }

Un Component consumatore che fa riferimento a DatabasePayload riceve la forma completamente espansa, con credentials popolato dal BasicAuth della libreria B. Un valore che viola un vincolo apportato dalla catena viene rifiutato al proprio percorso nel documento sottoposto a controllo, e il rifiuto non nomina la voce di libreria da cui proviene il vincolo; per trovarla, segui la catena di $ref: a partire dal consumatore.

Il consumatore restringe la voce di libreria

Un Component consumatore può dichiarare una proprietà il cui nome coincide con quello di una proprietà importata da una voce di libreria. In questo caso, la proprietà compilata del consumatore sostituisce interamente quella della voce di libreria nella forma unita.

# 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]

Nella forma unita, side_effects riflette il contratto più ristretto del consumatore (enum: [read], con un default); l’enum: [read, write, delete] più ampio della voce di libreria è scomparso. La proprietà è scritta dal consumatore.

Questo è il comportamento previsto: i consumatori che affinano la proprietà di una voce di libreria sono il pattern canonico di restringimento. Il restringimento è silenzioso: la proprietà del consumatore si regge sulla propria provenienza.

Riferimenti incrociati

  • Per l’ereditarietà tra entità del catalogo (Component-extends-Component, Feature-extends-Feature), vedi inheritance-and-interface.md.
  • Per l’ereditarietà tra i documenti del lato distribuzione, i cui riferimenti nominano file anziché entità del catalogo: una Release che estende una Release è documentata in entities/release.md, e un Manifest che estende un Manifest in entities/manifest.md.
  • Per i puntatori di sorgente specifici del provider (Recipe.spec.source.chart:, Recipe.spec.source.modulePath:), vedi la documentazione della Recipe per ciascuna entità. I puntatori di sorgente dei Provider non sono unificati sotto $ref:; il plugin del provider li consuma direttamente.
  • Per le regole di espansione delle abbreviazioni degli URI OCI (dominio predefinito, espansione contestuale delle entità, precedenza di risoluzione, gestione delle versioni), vedi uri-grammar.md.