Zum Inhalt springen
AggregaAggrega
Sprache wählen: Deutsch
Diese Seite wurde maschinell übersetzt. Das englische Original lesen.

Dokumentübergreifende `$ref:`-Auflösung

Diese Seite dokumentiert die Auflösungssemantik dokumentübergreifender $ref:-Referenzen in der Schema-Authoring-Oberfläche von Aggrega — was Autoren von Components, Features und SchemaLibrary-Einträgen sehen, wenn ein $ref: eine Dokumentgrenze in eine Bibliothek hinein überschreitet, und die required:-Regeln pro Syntax, die festlegen, welche Authoring-Formen sauber mit der dokumentübergreifenden Expansion funktionieren.

$ref: ist nativ in JSON Schema 2020-12. Es erscheint innerhalb von schema:-Inhalten (Component-, Feature- und SchemaLibrary-Einträge), innerhalb von Schemas in kompakter Form und innerhalb der synthetisierten JSON-Schema-Schicht, die usesSchema: und featuresSchema: ausgeben. Diese Seite konzentriert sich auf den dokumentübergreifenden Fall, in dem $ref: auf einen SchemaLibrary-Eintrag in einer separaten Datei oder einem OCI-Artefakt zielt.

Für die Vererbung zwischen Katalogentitäten (Component-extends-Component) siehe inheritance-and-interface.md. Ein Release, das ein Release erweitert, ist ein anderer Mechanismus über einem Dokument, das nicht im Katalog indexiert ist; er ist unter entities/release.md dokumentiert.

$import: ist das andere Schlüsselwort, das Inhalte außerhalb des Dokuments erreicht, und die beiden beantworten unterschiedliche Fragen. $ref: benennt einen Eintrag in einer SchemaLibrary über seine Identität — der Katalog löst ihn auf, das Lockfile liefert die Version — und es lässt sich an jedem Knoten komponieren. $import: benennt eine Datei neben der Entität und ersetzt den gesamten Inhalt durch das, was diese Datei enthält. $import: gilt auf der Schema-Oberfläche ebenso wie bei valuesMapping:, workload:, artifacts: und parameters:; zu $import: in einem Schema siehe compact-form-authoring.md §„Importing a contract from a file (Einen Vertrag aus einer Datei importieren)“.

Auflösungssemantik von $ref:

$ref: folgt der Standardauflösung von JSON Schema 2020-12. In der Praxis kommen folgende Referenzformen vor:

  • Lokale Fragmente innerhalb desselben Dokuments: { $ref: "#/$defs/PodResources" } — wird zum Eintrag PodResources unter den $defs des Schemas aufgelöst.
  • Referenzen auf SchemaLibrary-Einträge über die Identität: { $ref: "WebPrimitives#/schemas/URL" } — die Form mit bloßem Namen <Library>#/schemas/<Entry>. Der Bibliotheksname wird gegen den aufgelösten Katalog aufgelöst, und das JSON-Pointer-Fragment #/schemas/<Entry> wählt den Eintrag aus; die Version liefert das Lockfile, nicht die Referenz. Eine Referenz trägt keinen Registry-Host — eine Form mit Host oci://<host>/… wird beim Kompilieren mit einer Diagnose abgelehnt, die den Autor zur Identitätsform lenkt, sodass ein physischer Registry-Speicherort nie in verfassten Quelltext gelangt. Von wo die Bytes der Bibliothek ausgeliefert werden (ein lokales Katalogverzeichnis, der Inhalts-Cache oder eine entfernte Registry), ist Sache des Resolvers, wird zum Zeitpunkt der Auflösung gebunden und ist nie Teil der Referenz.
  • Ein Dateipfad ist kein Referenzziel: { $ref: "./schemas/foo.yaml#/definitions/Foo" } wird beim Kompilieren des Schemas abgelehnt, mit einer Diagnose, die die Form <Library>#/schemas/<Entry> nennt. Schemainhalt, der in einer Datei neben der Entität liegt, wird stattdessen mit $import: eingebunden, das wie jede Datei, die eine Entität liest, auf das eigene Verzeichnis der Entität begrenzt ist.

Die Referenz wird zur Kompilierzeit aufgelöst. Der Expander fügt den referenzierten Inhalt direkt in das Schema des Konsumenten ein; die gerenderte IR trägt den eingefügten Inhalt, nicht die Indirektion.

$ref: lässt sich auf natürliche Weise mit den Kompositions-Schlüsselwörtern von JSON Schema kombinieren:

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

Das allOf kombiniert die referenzierte NodePool-Form mit den zusätzlichen Einschränkungen.

Syntax für required: bei dokumentübergreifendem $ref:

Katalogautoren wählen beim Deklarieren von Pflichteigenschaften an einer Component oder einem Feature zwischen zwei Authoring-Formen: Markierungen auf Blattebene (required: true an jeder Eigenschaft) oder dem Array auf Elternebene (required: [name1, name2, ...] im Objektbereich). Beide Formen sind in JSON Schema 2020-12 gültig, und beide zählen bei der dokumentübergreifenden $ref:-Expansion, wenn sie dort geschrieben werden, wo dieser Abschnitt es zeigt.

Authoring in inferierter Form ohne $ref: — Markierungen auf Blattebene sammeln sich zur Kompilierzeit an. Der Compiler durchläuft jede Eigenschaft und trägt, wo ein Blatt required: true trägt, den Eigenschaftsnamen in das required:-Array des synthetisierten Elternobjekts ein.

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

Der Compiler gibt required: [database, display_name] im Elternbereich aus.

Konsumenten mit $ref: — neben einem dokumentübergreifenden $ref: dürfen nur properties, required und description geschrieben werden, und die Anforderungen, die der Konsument hinzufügt, sind die, die er dort schreibt: ein required:-Array auf Elternebene oder eine required: true-Markierung auf Blattebene an einer Eigenschaft, die er unter properties: deklariert. Die eigenen Anforderungen des referenzierten Eintrags — Markierungen auf Blattebene in seiner inferierten Form oder ein eigenes required:-Array — gelten unverändert über die Referenz. Ein Array auf Elternebene benennt Anforderungen, ohne die Eigenschaften neu zu deklarieren, die der Eintrag bereits deklariert:

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

Auch eine Markierung auf Blattebene zählt, an einer Eigenschaft, die der Konsument neben der Referenz deklariert — so macht properties: { database: { type: string, required: true } }, dort geschrieben, database genau so zur Pflicht, wie es required: [database] tut. Die Eigenschaft des Konsumenten ersetzt die gleichnamige Eigenschaft des Eintrags (siehe Konsument schränkt Bibliothekseintrag ein), deklarieren Sie sie also mit der gemeinten Form neu.

Expansion von Ketten zwischen Bibliotheken

Ein SchemaLibrary-Eintrag kann selbst ein $ref: enthalten, das auf einen anderen SchemaLibrary-Eintrag zeigt, wodurch eine Kette entsteht. Der Compiler durchläuft die Kette zur Kompilierzeit: Jedes $ref:, auf das er beim Expandieren eines Eintrags trifft, wird seinerseits expandiert, und zwar in den Begriffen der Bibliothek, die es enthält.

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

Eine konsumierende Component, die DatabasePayload referenziert, erhält die vollständig expandierte Form, wobei credentials aus dem BasicAuth von Bibliothek B befüllt ist. Ein Wert, der eine von der Kette beigesteuerte Einschränkung verletzt, wird an seinem eigenen Pfad im geprüften Dokument abgelehnt, und die Ablehnung nennt nicht den Bibliothekseintrag, aus dem die Einschränkung stammt; folgen Sie der $ref:-Kette vom Konsumenten aus, um ihn zu finden.

Konsument schränkt Bibliothekseintrag ein

Eine konsumierende Component kann eine Eigenschaft deklarieren, deren Name einer aus einem Bibliothekseintrag übernommenen Eigenschaft entspricht. In diesem Fall ersetzt die kompilierte Eigenschaft des Konsumenten die des Bibliothekseintrags in der zusammengeführten Form vollständig.

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

In der zusammengeführten Form spiegelt side_effects den engeren Vertrag des Konsumenten wider (enum: [read], mit einem default); das breitere enum: [read, write, delete] des Bibliothekseintrags ist verschwunden. Die Eigenschaft ist vom Konsumenten verfasst.

Das ist das erwartete Verhalten: Konsumenten, die die Eigenschaft eines Bibliothekseintrags verfeinern, sind das kanonische Einschränkungsmuster. Das Einschränken geschieht stillschweigend: Die Eigenschaft des Konsumenten steht auf ihrer eigenen Herkunft.

Querverweise

  • Für die Vererbung zwischen Katalogentitäten (Component-extends-Component, Feature-extends-Feature) siehe inheritance-and-interface.md.
  • Für die Vererbung zwischen den Dokumenten auf der Bereitstellungsseite, deren Referenzen Dateien statt Katalogentitäten nennen: Ein Release, das ein Release erweitert, ist unter entities/release.md dokumentiert, und ein Manifest, das ein Manifest erweitert, unter entities/manifest.md.
  • Für Provider-spezifische Quellzeiger (Recipe.spec.source.chart:, Recipe.spec.source.modulePath:) siehe die Recipe-Dokumentation der jeweiligen Entität. Provider-Quellzeiger werden nicht unter $ref: vereinheitlicht; das Provider-Plugin konsumiert sie direkt.
  • Zu den Expansionsregeln für OCI-URI-Kurzschreibweisen (Standarddomäne, kontextabhängige Entitätsexpansion, Auflösungsreihenfolge, Versionsbehandlung) siehe uri-grammar.md.