Aller au contenu
AggregaAggrega
Selectionner la langue: Français
Cette page a été traduite automatiquement. Lire l’original en anglais.

Résolution de `$ref:` inter-documents

Cette page documente la sémantique de résolution des références $ref: inter-documents dans la surface de rédaction des schémas d’Aggrega — ce que voient les auteurs de Components, de Features et d’entrées de SchemaLibrary lorsqu’un $ref: franchit une frontière de document vers une bibliothèque, et les règles required: par syntaxe qui fixent quelles formes de rédaction fonctionnent proprement avec l’expansion inter-documents.

$ref: est natif de JSON Schema 2020-12. Il apparaît dans le contenu de schema: (entrées de Component, de Feature et de SchemaLibrary), dans les schémas en forme compacte et dans la couche JSON Schema synthétisée qu’émettent usesSchema: et featuresSchema:. Cette page se concentre sur le cas inter-documents, où $ref: cible une entrée de SchemaLibrary dans un fichier distinct ou un artefact OCI.

Pour l’héritage entre entités du catalogue (Component-extends-Component), voir inheritance-and-interface.md. Une Release qui étend une Release est un mécanisme différent, portant sur un document qui n’est pas indexé dans le catalogue ; il est documenté dans entities/release.md.

$import: est l’autre mot-clé qui atteint un contenu extérieur au document, et les deux répondent à des questions différentes. $ref: nomme une entrée d’une SchemaLibrary par identité — le catalogue la résout, le lockfile fournit la version — et il se compose à n’importe quel nœud. $import: nomme un fichier situé à côté de l’entité et remplace le contenu entier par ce que contient ce fichier. $import: s’applique sur la surface des schémas ainsi qu’à valuesMapping:, workload:, artifacts: et parameters: ; pour $import: sur un schéma, voir compact-form-authoring.md §« Importing a contract from a file (Importer un contrat depuis un fichier) ».

Sémantique de résolution de $ref:

$ref: suit la résolution standard de JSON Schema 2020-12. Les formes de référence suivantes apparaissent en pratique :

  • Fragments locaux au sein du même document : { $ref: "#/$defs/PodResources" } — se résout vers l’entrée PodResources sous les $defs du schéma.
  • Références à des entrées de SchemaLibrary par identité : { $ref: "WebPrimitives#/schemas/URL" } — la forme à nom nu <Library>#/schemas/<Entry>. Le nom de la bibliothèque se résout par rapport au catalogue résolu et le fragment JSON Pointer #/schemas/<Entry> sélectionne l’entrée ; la version est fournie par le lockfile, non par la référence. Une référence ne porte aucun hôte de registry — une forme oci://<host>/… portant un hôte est refusée à la compilation avec un diagnostic qui oriente l’auteur vers la forme par identité, de sorte qu’un emplacement physique de registry n’entre jamais dans la source rédigée. L’endroit d’où sont servis les octets de la bibliothèque (un répertoire local du catalogue, le cache de contenu ou un registry distant) relève du résolveur, est lié au moment de la résolution et ne fait jamais partie de la référence.
  • Un chemin de fichier n’est pas une cible de référence : { $ref: "./schemas/foo.yaml#/definitions/Foo" } est refusé lorsque le schéma se compile, avec un diagnostic nommant la forme <Library>#/schemas/<Entry>. Un contenu de schéma conservé dans un fichier à côté de l’entité est importé à la place avec $import:, qui est borné au répertoire propre de l’entité comme tout fichier que lit une entité.

La référence se résout à la compilation. L’expanseur intègre en ligne le contenu référencé dans le schéma du consommateur ; l’IR rendue porte le contenu intégré, non l’indirection.

$ref: se compose naturellement avec les mots-clés de composition de JSON Schema :

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

Le allOf compose la forme NodePool référencée avec les contraintes supplémentaires.

Syntaxe de required: sous un $ref: inter-documents

Les auteurs du catalogue choisissent entre deux formes de rédaction lorsqu’ils déclarent des propriétés obligatoires sur un Component ou une Feature : des marqueurs au niveau de la feuille (required: true sur chaque propriété) ou le tableau au niveau du parent (required: [name1, name2, ...] dans la portée de l’objet). Les deux formes sont valides en JSON Schema 2020-12, et toutes deux comptent sous l’expansion de $ref: inter-documents, écrites là où le montre cette section.

Rédaction en forme inférée sans $ref: — les marqueurs au niveau de la feuille s’accumulent à la compilation. Le compilateur parcourt chaque propriété et, là où une feuille porte required: true, ajoute le nom de la propriété au tableau required: du parent synthétisé.

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

Le compilateur émet required: [database, display_name] dans la portée parente.

Consommateurs porteurs d’un $ref: — à côté d’un $ref: inter-documents, seuls properties, required et description peuvent être écrits, et les exigences qu’ajoute le consommateur sont celles qu’il y écrit : un tableau required: au niveau du parent, ou un marqueur required: true au niveau de la feuille sur une propriété qu’il déclare sous properties:. Les exigences propres de l’entrée référencée — marqueurs au niveau de la feuille dans sa forme inférée, ou un tableau required: qui lui est propre — s’appliquent inchangées à travers la référence. Un tableau au niveau du parent nomme des exigences sans redéclarer les propriétés que l’entrée déclare déjà :

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

Un marqueur au niveau de la feuille compte également, sur une propriété que le consommateur déclare à côté de la référence — ainsi properties: { database: { type: string, required: true } } écrit là rend database obligatoire exactement comme le fait required: [database]. La propriété du consommateur remplace la propriété de l’entrée portant le même nom (voir Le consommateur restreint l’entrée de bibliothèque), redéclarez-la donc avec la forme que vous voulez.

Expansion des chaînes de bibliothèque à bibliothèque

Une entrée de SchemaLibrary peut elle-même contenir un $ref: pointant vers une autre entrée de SchemaLibrary, ce qui produit une chaîne. Le compilateur parcourt la chaîne à la compilation : chaque $ref: rencontré pendant l’expansion d’une entrée est lui-même expansé, dans les termes de la bibliothèque qui le contient.

# 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 consommateur qui référence DatabasePayload reçoit la forme entièrement expansée, avec credentials renseigné à partir du BasicAuth de la bibliothèque B. Une valeur qui enfreint une contrainte apportée par la chaîne est refusée à son propre chemin dans le document vérifié, et le refus ne nomme pas l’entrée de bibliothèque d’où vient la contrainte ; suivez la chaîne de $ref: depuis le consommateur pour la trouver.

Le consommateur restreint l’entrée de bibliothèque

Un Component consommateur peut déclarer une propriété dont le nom correspond à une propriété importée d’une entrée de bibliothèque. Dans ce cas, la propriété compilée du consommateur remplace entièrement celle de l’entrée de bibliothèque dans la forme fusionnée.

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

Dans la forme fusionnée, side_effects reflète le contrat plus étroit du consommateur (enum: [read], avec un default) ; le enum: [read, write, delete] plus large de l’entrée de bibliothèque a disparu. La propriété est rédigée par le consommateur.

C’est le comportement attendu : des consommateurs qui affinent la propriété d’une entrée de bibliothèque constituent le motif canonique de restriction. La restriction est silencieuse : la propriété du consommateur repose sur sa propre provenance.

Renvois

  • Pour l’héritage entre entités du catalogue (Component-extends-Component, Feature-extends-Feature), voir inheritance-and-interface.md.
  • Pour l’héritage entre les documents côté déploiement, dont les références nomment des fichiers plutôt que des entités du catalogue : une Release qui étend une Release est documentée dans entities/release.md, et un Manifest qui étend un Manifest dans entities/manifest.md.
  • Pour les pointeurs de source propres au fournisseur (Recipe.spec.source.chart:, Recipe.spec.source.modulePath:), voir la documentation de la Recipe propre à chaque entité. Les pointeurs de source de Provider ne sont pas unifiés sous $ref: ; le plugin du fournisseur les consomme directement.
  • Pour les règles d’expansion des raccourcis d’URI OCI (domaine par défaut, expansion contextuelle des entités, priorité de résolution, gestion des versions), voir uri-grammar.md.