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

Authoring in kompakter Form

Die kompakte Form ist eine YAML-artige deklarative Kurzschreibweise für JSON Schema 2020-12. Autoren schreiben Einschränkungen pro Feld als YAML-Maps im Inline-Flow-Stil (port: { type: integer, min: 1, max: 65535, default: 8080 }); Zwischenknoten für Objekte sind natürliche YAML-Verschachtelung; Referenzen verwenden das standardmäßige $ref: von JSON Schema. Der Compiler wandelt die kompakte Form in JSON Schema 2020-12 um, bevor eine Validierung läuft, sodass Validierung, Fehlermeldung und jedes Werkzeug, das ein Schema liest, mit dem aufgelösten JSON Schema arbeiten, in welcher Form es auch verfasst wurde.

Diese Seite dokumentiert das Vokabular der kompakten Form, die strukturellen Konventionen, den Dispatch zwischen inferierter und expliziter Objektform, die Abschlusssemantik, die Heterogenität von type:, die Arrays zulässiger Typen erlaubt, die in jedem Bereich in inferierter Form reservierten Schlüsselwörter und den Erweiterungs-Namespace x-aggrega-*. Zur Auflösungssemantik von dokumentübergreifendem $ref: siehe cross-document-ref.md. Zur Authoring-Grammatik des Assertions-Blocks siehe templates/assertions-block.md. Zur Menge der Datensäulen (values:, infra:, provides:, uses:, features:, locals:, parameters:) siehe data-pillars.md.

Die kompakte Form ist die Standard-Authoring-Oberfläche für schema:, parameters: und SchemaLibrary-Einträge. JSON Schema in YAML ist eine gleichwertige Authoring-Option; beide Formen sind erstklassig und können innerhalb eines einzelnen Schemas gemischt werden. Die beiden Formen werden in dasselbe aufgelöste JSON-Schema-Dokument kompiliert; nachgelagerte Werkzeuge und die Validierung sind dem Authoring-Weg gegenüber gleichgültig.

Vokabular

Die Schlüsselwörter der kompakten Form sind die in den folgenden Tabellen. Autoren lernen sie einmal und wenden sie in schema:, parameters: und SchemaLibrary-Einträgen an.

Schlüsselwörter für Typ und Identität

SchlüsselwortBedeutungWird kompiliert zu JSON Schema
typeFeldtyp (string, integer, number, boolean, object, array oder ein Array zulässiger Typen)type:
descriptionMenschenlesbare Dokumentationdescription:
defaultStandardwert, wenn das Feld fehltdefault:
requiredMarkierung pro Blatt (required: true) für Felder, die vorhanden sein müssenFügt den Feldnamen dem required:-Array des übergeordneten Objekts hinzu

Schlüsselwörter für Einschränkungen

SchlüsselwortBedeutungWird kompiliert zu JSON Schema
enumZulässige Werte (Liste)enum:
constDer eine zulässige Wert — ein Skalar, eine Map oder eine Listeconst:
minMinimalwert (numerisch) oder Mindestlänge (Zeichenkette/Array)minimum: (numerisch); minLength: (Zeichenkette); minItems: (Array) — gewählt nach type:
maxMaximalwert oder -länge, parallel zu minmaximum: / maxLength: / maxItems:
minLength / maxLengthExplizite Einschränkungen der ZeichenkettenlängeDirekte Abbildung auf minLength: / maxLength: (verwenden, wenn min/max mehrdeutig wären)
patternRegex-Muster für Zeichenkettenpattern:
formatBenanntes Format, das eine Zeichenkette haben muss — eines von email, uri, hostname, ipv4, ipv6, uuid, date-time, date (siehe Benannte Formate)format:

In den parameters: eines Aggregate werden einige davon auch an der Deklaration selbst geprüft, bevor irgendein Release-Wert gelesen wird. Die eigenen minLength und maxLength eines Parameters sind null oder mehr — ein negativer Wert wird abgelehnt, wenn das Aggregate geladen wird —, und jedes pattern, auch eines innerhalb eines verschachtelten items-, properties- oder valuesType-Vertrags, muss ein regulärer Ausdruck sein, der sich kompilieren lässt, da das Muster beim Lesen des Parametervertrags kompiliert wird. Jedes format muss in jeder Tiefe eines der unten benannten Formate sein. Ein min oder max an einem booleschen oder Objekt-Parameter wird ebenfalls abgelehnt, da das Paar bei diesen Typen nichts begrenzt. Jeder Fehler hält den Build an und nennt den Parameter, unabhängig davon, ob ein Release ihn liefert. Eine Längengrenze innerhalb eines verschachtelten Vertrags unterliegt dieser Untergrenze nicht; siehe entities/aggregate.md dazu, wo jede Prüfung läuft.

Benannte Formate

format benennt die Form, die ein Zeichenkettenwert haben muss. Die Namen sind die von der JSON-Schema-Spezifikation definierten, so geschrieben, wie sie sie schreibt, und jeder prüft, was die Spezifikation als seine Bedeutung definiert:

NameEin konformer Wert istDefiniert durch
emailein Postfach: ein lokaler Teil (durch Punkte getrennte Atome oder eine Zeichenkette in Anführungszeichen), @, dann eine Domain oder ein Adressliteral in eckigen Klammern — ops@example.com. Ein Anzeigename wie Joe <joe@example.com> ist kein PostfachRFC 5321, Abschnitt 4.1.2 (Mailbox)
uriein absoluter URI: ein Scheme, :, dann der Rest, wobei jedes Zeichen außerhalb des URI-Alphabets prozentkodiert ist — https://example.com/a%20b, s3://bucket/key. Eine relative Referenz wie /path ist keinerRFC 3986 (URI)
hostnameein Hostname: durch Punkte getrennte Labels aus Buchstaben, Ziffern und Bindestrichen, jedes 1–63 Zeichen lang, das weder mit einem Bindestrich beginnt noch endet, insgesamt höchstens 253 Zeichen — db-primary.data.svc.cluster.local. Ein Punycode-Label (xn--…) wird so akzeptiert, wie es geschrieben ist; ein Platzhalter *, ein Unterstrich oder ein abschließender Punkt nichtRFC 1123, Abschnitt 2.1
ipv4vier Dezimalzahlen von 0 bis 255, durch Punkte getrennt — 192.0.2.1RFC 2673, Abschnitt 3.2 (Dotted-Quad)
ipv6eine IPv6-Adresse in einer beliebigen ihrer Textformen — vollständig, mit :: komprimiert oder auf eine IPv4-Adresse endend — 2001:db8::1. Eine Zone (%eth0) oder eine Präfixlänge (/64) ist nicht Teil einer AdresseRFC 4291, Abschnitt 2.2
uuid32 Hexadezimalziffern in Gruppen von 8-4-4-4-12, durch Bindestriche getrennt, in Groß- oder Kleinschreibung — 2eb8aa08-aa98-11ea-b4aa-73b441d16380RFC 4122, Abschnitt 3
date-timeein Zeitstempel mit einem Offset — 2026-09-28T12:34:56Z, 2026-09-28T12:34:56.5+02:00, ein Tag, der in seinem Monat existiert, und eine Schaltsekunde nur um 23:59 UTCRFC 3339, Abschnitt 5.6 (date-time)
dateein Kalenderdatum — 2026-09-28 —, dessen Tag in seinem Monat und Jahr existiertRFC 3339, Abschnitt 5.6 (full-date)

Ein Format beurteilt eine Zeichenkette und sonst nichts: Einen Wert eines anderen Typs beurteilt dessen type. Und es beurteilt nur die Syntax des Werts — ein Hostname wird nie aufgelöst, ein URI nie abgerufen, ein Postfach nie kontaktiert —, sodass die Prüfung bei jedem Build dieselbe Antwort gibt und kein Netzwerk benötigt.

Die Prüfung läuft überall dort, wo ein Wert gegen sein Schema validiert wird: die parameters: eines Aggregate, die values und infra, die die schema:-Säulen einer Component oder eines Feature einschränken, die values und infra pro Kante, die die Payload-Schemas eines usesSchema:-Sockets einschränken, und jeder SchemaLibrary-Eintrag, den diese Schemas erreichen. Die Formatnamen einer provides-Säule werden beim Laden des Katalogs wie die jedes anderen Schemas beurteilt; die Werte, die ein Recipe veröffentlicht, werden nicht gegen die Säule validiert, daher wird an ihnen kein Format geprüft. Innerhalb von allOf, anyOf, oneOf und not ist ein Wert, der sein Format verfehlt, ein Wert, der diesen Zweig verfehlt, genau wie ein Wert, der irgendeine andere Einschränkung verfehlt. Ein nicht konformer Wert wird abgelehnt, wobei Feld, Wert und Format genannt werden.

Ein Name außerhalb der Tabelle wird abgelehnt, wenn das Schema geladen wird, unabhängig davon, ob ein Wert ihn erreicht, und die Ablehnung listet die unterstützten Namen auf — so ist ein Tippfehler wie emial eine Diagnose statt einer Einschränkung, die nichts prüft. Führen Sie für einen SchemaLibrary-Eintrag aggrega validate über den gesamten Katalog aus, um den fehlerhaften Namen zu sehen: Ein Release, dessen Schemas den Eintrag erreichen, wird ebenfalls abgelehnt, meldet die Bibliothek aber als nicht gefunden. password ist kein Format: Ein Feld, das geheimes Material trägt, deklariert stattdessen sensitive: true.

Eine Grenze gilt für indirekt erreichte Formen. Wo die Form eines Felds über ein $ref: kommt, das daneben weitere Schlüsselwörter trägt (etwa eine properties:-Map), über das then: oder else: eines when: oder über einen Zeiger in eine deklarierte Eigenschaft, wird sein format an den Feldern geprüft, die die Form direkt und über allOf deklariert — aber nicht innerhalb eines anyOf-, oneOf-, not- oder bedingten Zweigs innerhalb dieser Form.

Schlüsselwörter für Komposition und Referenzen

SchlüsselwortBedeutungWird kompiliert zu JSON Schema
$refReferenz auf ein JSON-Pointer-Fragment oder einen externen SchemaLibrary-Eintrag$ref:
allOf / anyOf / oneOfJSON-Schema-KompositionDieselben Schlüsselwörter
patternPropertiesMap mit Regex-SchlüsselnDasselbe Schlüsselwort
valuesTypeKurzschreibweise für Maps mit typisierten Werten (z. B. „Objekt, dessen Werte alle Zeichenketten sind“)additionalProperties: { type: <X> }

Container-Schlüsselwörter

SchlüsselwortBedeutungWird kompiliert zu JSON Schema
itemsForm der Array-Elementeitems: (rekursive kompakte Form oder JSON Schema)
propertiesExplizite Deklaration der Kinder (selten nötig; meist implizit über die YAML-Struktur)properties:
additionalPropertiesOb nicht deklarierte Eigenschaften erlaubt sind (false bei einem Objekt in inferierter Form, wo der Compiler es hinzufügt; bei einem expliziten type: object liegt es bei Ihnen, es zu schreiben, und wo Sie es nicht tun, gilt der eigene Standardwert von JSON Schema, true)additionalProperties:

Aggrega-spezifische Schlüsselwörter

SchlüsselwortBedeutung
validateGo-Template-Prädikat pro Feld, das einen booleschen Wert zurückgibt; false hält die Validierung mit validateMessage: an
validateMessageFehlermeldung zu einem Fehlschlag von validate:
whenBedingte Anwendung eines Teilbaums; Go-Template-Prädikat, das steuert, ob die Einschränkungen des Knotens gelten
sensitiveDeklariert, dass dieses Blatt geheimes Material trägt. Wird kompiliert zu x-aggrega-sensitive: true. Siehe „Declaring a leaf sensitive (Ein Blatt als sensibel deklarieren)“ unten
$jsonschemaAusweg — eingebettetes vollständiges JSON-Schema-Unterdokument an diesem Knoten
$modeOptionale Dispatch-Annotation für mehrdeutige Fälle (selten nötig; siehe „Inferred vs explicit object form (Inferierte und explizite Objektform)“ unten)

Die von JSON Schema entlehnten Schlüsselwörter ($ref, allOf, format usw.) verwenden eine mit JSON Schema identische Syntax, sodass Autoren, die JSON Schema bereits kennen, sie sofort erkennen.

Ein Schlüsselwort, dessen Wert Daten sind, trägt diesen Wert so, wie er geschrieben ist. Eine Map oder Liste, die default, enum oder const übergeben wird, ist der Wert selbst, nie ein verschachteltes Schema: endpoint: { type: object, default: { host: db, port: 5432 } } setzt den Standardwert von endpoint auf dieses Objekt, und mode: { type: object, const: { kind: fast } } lässt genau dieses Objekt zu — ebenso wie mode: { const: { kind: fast } }, da const wie enum den Knoten für sich allein zu einem Blatt macht. Dasselbe gilt innerhalb eines $jsonschema:-Auswegs.

Wie ein Blatt in kompakter Form aufgebaut ist

Die Authoring-Einheit ist ein Blattknoten — ein Feld mit einem Einschränkungs-Dict:

field_name: { type: <type>, ...constraints... }

Gängige Muster:

port: { type: integer, default: 8080 }
port: { type: integer, min: 1, max: 65535, default: 8080 }
identifier: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$" }
log_level: { type: string, enum: [debug, info, warn, error], default: info }
name: { type: string, minLength: 1, required: true }
email: { type: string, format: email }
enabled: { type: boolean, default: false }

Jedes Blatt ist eine Zeile. Das Einschränkungs-Dict erfasst alles über die Form des Felds; die Struktur des übergeordneten Knotens erfasst die Position des Felds.

Verschachtelte Objekte

Die Objektstruktur spiegelt die YAML-Verschachtelung wider. Tiefe Verschachtelung funktioniert direkt, wobei jedes Blatt weiterhin in einer Zeile steht:

spec:
schema:
architecture: { type: string, enum: [standalone, replication], default: standalone }
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "250m" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "512Mi" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$", default: "500m" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$", default: "1Gi" }
auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true }

Der Compiler leitet die Objektstruktur aus der YAML-Hierarchie ab. Zwischenknoten (hier: primary, resources, requests, limits, auth) sind Objekttypen, die die verschachtelten Kinder enthalten. Der Compiler gibt explizite type: object- und properties:-Blöcke im aufgelösten JSON Schema aus; der Autor schreibt sie nicht.

Inferierte und explizite Objektform

Ein Objektbereich in kompakter Form kann auf zwei Arten verfasst werden:

Inferierte Form — Kinder direkt unter dem übergeordneten Schlüssel, keine type: object-Deklaration:

auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }

Der Compiler erkennt den Bereich als Objekt, weil seine Kinder Eigenschaftsdeklarationen sind. Er gibt type: object, properties: { ... } aus und injiziert zur Kompilierzeit automatisch additionalProperties: false. Die Abschlusssemantik ist Teil des Vertrags der inferierten Form: Tippfehler in von Entwicklern verfassten Feldern schlagen deutlich fehl.

Explizite Form — type: object deklariert, properties: aufgezählt:

auth:
type: object
properties:
username: { type: string, default: app_user }
password: { type: string, sensitive: true }
required: [password]
additionalProperties: true # genuinely-open map authored on purpose

Der Compiler injiziert additionalProperties: false in der expliziten Form NICHT. Autoren, die type: object deklarieren, tragen die volle Verantwortung für die Abschlussentscheidung; die explizite Form ist die Oberfläche für wirklich offene Maps (additionalProperties: true) und für Objekte, die andere JSON-Schema-Schlüsselwörter benötigen (patternProperties, propertyNames, unevaluatedProperties).

Authoring-Kriterium: Verwenden Sie die inferierte Form für gewöhnliche geschlossene Objekte (der häufige Fall in Katalogschemas). Verwenden Sie die explizite Form, wenn das Objekt wirklich offen sein soll oder wenn das Schema JSON-Schema-Schlüsselwörter benötigt, die die kompakte Form nicht direkt unterstützt.

Abschlusssemantik

Per Konvention sind Objekte der kompakten Form in inferierter Form geschlossen: Nicht deklarierte Eigenschaften erzeugen einen Validierungsfehler. Der Compiler gibt additionalProperties: false automatisch an jedem Objektbereich in inferierter Form aus. Das entspricht der Katalogdisziplin, nach der Tippfehler deutlich fehlschlagen.

Um ein Objekt zu öffnen (beliebige zusätzliche Eigenschaften zulassen), verwenden Sie die explizite Form mit additionalProperties: true:

labels:
type: object
additionalProperties: true # opt-in; allow any string-keyed values

Für das häufige Muster „Objekt, dessen Werte alle einen Typ teilen“ (z. B. eine Map von Zeichenkette → Zeichenkette für Labels) verwenden Sie valuesType::

labels: { type: object, valuesType: string }
nodeSelector: { type: object, valuesType: string }
counters: { type: object, valuesType: integer }

valuesType: <type> wird zu additionalProperties: { type: <type> } kompiliert. Es ist ein so häufiges Muster, dass es eine Kurzschreibweise mit einem einzigen Schlüsselwort verdient.

Der bloße Typname oben ist die Schreibweise für schema: und SchemaLibrary. In einem parameters:-Slot eines Aggregate schreiben Sie den Wert stattdessen als Vertrag — valuesType: { type: string }. Dasselbe gilt für die beiden anderen Schlüsselwörter, deren Wert selbst ein Vertrag ist, items: und jeden Eintrag unter properties:, weil eine Parameterdeklaration und jeder darin verschachtelte Vertrag eine einzige Form haben. Ein bloßer Typname an einer dieser drei Positionen in einem Parameter-Slot wird abgelehnt, und die Diagnose nennt, welcher verschachtelte Vertrag ihn enthielt. Siehe entities/aggregate.md für das vollständige Vokabular der Parameter-Slots.

Pflichtfelder

Pflichtfelder verwenden required: true pro Blatt:

auth:
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }
database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }

Der Compiler sammelt alle required: true-Markierungen innerhalb eines Objektbereichs und gibt sie als required: [field1, field2]-Array von JSON Schema aus. Die Markierung zählt überall dort, wo die Eigenschaft deklariert ist: in einem Bereich in inferierter Form und an einer Eigenschaft innerhalb eines expliziten properties:-Blocks.

Ein Konsument, der einen SchemaLibrary-Eintrag über $ref: in sein Schema einbindet, kann seine Anforderungen auf beide Arten benennen — ein required: [name1, name2]-Array auf Elternebene neben der Referenz oder eine required: true-Markierung an einer Eigenschaft, die er dort unter properties: deklariert. Siehe cross-document-ref.md §„required: syntax under cross-document $ref: (Syntax für Pflichtfelder bei dokumentübergreifenden Referenzen)“ für die vollständige Regel.

Arrays

Arrays verwenden type: array mit items:, das die Form der Elemente beschreibt:

tags: { type: array, items: { type: string } }
ports: { type: array, items: { type: integer, min: 1, max: 65535 } }
extraEnvVars:
type: array
items:
name: { type: string, required: true }
value: { type: string }
valueFrom: { type: object, additionalProperties: true }
allowedHosts:
type: array
min: 1 # minItems
max: 100 # maxItems
items: { type: string, format: hostname }

Für den häufigen Fall „Array typisierter Skalare“ ist die Inline-Form eine Zeile. Für Arrays von Objekten leitet items: ein verschachteltes Schema in kompakter Form ein.

Das Schlüsselwort type: — Skalar oder Array von Typen

type: akzeptiert entweder einen einzelnen Wert (type: string) oder ein Array zulässiger Typen (type: [string, integer, boolean]). Die Array-Form ist der Standardausdruck von JSON Schema 2020-12 für „dieses Feld akzeptiert einen von mehreren Typen“:

release_tier: { type: [string, integer], description: "Numeric tier or named tag" }

Wenn type: ein Array trägt, ist der Wertebereich die Vereinigung der Wertebereiche der benannten Typen. Autoren, die Schemas schreiben, die die Array-Form konsumieren, müssen nachgelagert beide Formen behandeln — das type-Feld des aufgelösten JSON Schema enthält entweder eine Zeichenkette oder ein Array, und Konsumenten, die das aufgelöste Schema durchlaufen, prüfen beide Formen.

Reservierte Schlüsselwörter in jedem Bereich in inferierter Form

Der Dispatch der inferierten Form erkennt eine kleine Menge von Schlüsselwörtern, die auf der Ebene des Vokabulars der kompakten Form eine Bedeutung tragen: description, type, default, required, die Einschränkungs-Schlüsselwörter (enum, const, min, max, pattern, format usw.) und die Aggrega-spezifischen Schlüsselwörter (validate, validateMessage, when, sensitive). Wenn eines dieser Schlüsselwörter als Feldname in einem Objektbereich in inferierter Form erscheint, liest der Compiler den umschließenden Bereich als Einschränkungsblatt statt als Objekt: Das Schlüsselwort wird als Einschränkung genommen, nicht als untergeordnete Eigenschaft, und jeder andere Schlüssel in diesem Bereich muss dann ebenfalls ein Schlüsselwort sein, sodass der erste, der keines ist, als unbekanntes Schlüsselwort abgelehnt wird.

sensitive verdient hier besondere Erwähnung, weil es ein weit plausiblerer Name für ein echtes, von einem Entwickler verfasstes Feld ist als die anderen Aggrega-spezifischen Schlüsselwörter. Ein Schema, das wirklich eine Eigenschaft namens sensitive braucht — etwa eine Komponente, deren values ein eigenes sensitive-Flag bereitstellen —, muss den umschließenden Bereich explizit deklarieren, genau wie bei einer Eigenschaft namens type oder default. Das erreicht entweder die explizite Form unten oder $mode: jsonschema am umschließenden Bereich: Unter $mode: jsonschema wird der gesamte Knoten als verfasstes JSON Schema gelesen, in dem sensitive gewöhnlicher Inhalt ist und nicht das Schlüsselwort der kompakten Form.

Für Schemas, die eine Eigenschaft benötigen, die nach einem reservierten Schlüsselwort benannt ist (z. B. ein Component-Vertrag mit einem vom Entwickler verfassten Feld description: oder einem Feld type: oder einem Feld default:), verwenden Sie für den betreffenden Bereich die explizite Form:

spec:
schema:
values:
type: object
properties:
description: { type: string } # property named "description"
type: { type: string } # property named "type"
default: { type: string } # property named "default"
required: [description, type]
additionalProperties: false

Die explizite Form umgeht den Dispatch — properties: zählt die Kinder explizit auf, sodass die Schlüsselwortkollision nicht auftritt.

Diese Einschränkung gilt in jedem Bereich in inferierter Form, rekursiv. Ein verschachteltes Objekt in inferierter Form, das eine nach einem reservierten Schlüsselwort benannte Eigenschaft enthält, wird in diesem Bereich als Einschränkungsblatt gelesen. Die Lösung ist dieselbe: Stellen Sie den betreffenden Bereich auf die explizite Form um.

Referenzen

Referenzen übernehmen $ref: von JSON Schema syntaktisch und semantisch:

resources: { $ref: "#/$defs/PodResources" }
auth: { $ref: "Datastores#/schemas/MariaDBAuth" }
secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }

$defs:-Blöcke innerhalb eines Schemas in kompakter Form deklarieren wiederverwendbare Definitionen. Jeder Eintrag ist selbst ein Schema in kompakter Form (oder JSON Schema, oder gemischt). Referenziert wird über das JSON-Pointer-Fragment #/$defs/<Name>:

Deklarieren Sie den Block innerhalb der Säule, deren Felder ihn referenzieren, neben diesen Feldern — nicht neben der Säule. Ein schema:-Block akzeptiert auf seiner eigenen obersten Ebene nur die Namen der drei Datensäulen, daher wird ein $defs:, das als Geschwister von values: geschrieben ist, beim Laden der Entität abgelehnt, unter Nennung des betreffenden Schlüssels und der Menge der Säulen, die der Block enthalten darf. Der Zeiger wird in beiden Fällen #/$defs/<Name> geschrieben.

$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources: { $ref: "#/$defs/PodResources" }

Für dokumentübergreifende Referenzen auf SchemaLibrary-Einträge siehe cross-document-ref.md. Für die Erweiterung der OCI-URI-Kurzschreibweise siehe uri-grammar.md.

Eine Referenz auf eine Definition richten, nicht auf eine Eigenschaft

Ein Zeiger, der einen $defs:-Eintrag nennt — #/$defs/PodResources —, ist die Form, zu der Sie greifen sollten. Ein Zeiger ist überall zulässig, wo JSON Schema einen erlaubt, daher wird auch ein Zeiger in eine deklarierte Eigenschaft akzeptiert und durchgesetzt, aber weniger präzise gemeldet, und den Unterschied sollten Sie kennen, bevor Sie einen schreiben.

Ein Feld, dessen Form aus einem $defs:-Eintrag stammt, wird Feld für Feld geprüft: Ein Fehler wird am Pfad des tatsächlich falschen Werts gemeldet, und jeder Fehler unter diesem Feld wird gemeldet, nicht nur der erste.

$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
primary:
resources: { $ref: "#/$defs/PodResources" }

Ein fehlerhaftes cpu wird hier an primary.resources.requests.cpu gemeldet.

Ein Feld, dessen Form aus einem Zeiger in eine deklarierte Eigenschaft stammt, wird als Teil des Dokuments als Ganzes geprüft. Die Einschränkungen gelten weiterhin, und ein Dokument, das sie verletzt, hält weiterhin an — aber der Fehler wird an dem Feld gemeldet, das den Zeiger trägt, statt an dem Wert darin, und wenn mehrere solche Felder gleichzeitig falsch sind, wird nur eines davon genannt.

primary:
resources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
secondary:
resources: { $ref: "#/properties/primary/properties/resources" }

Ein fehlerhaftes cpu unter secondary wird an secondary.resources gemeldet.

Beide Schreibweisen akzeptieren und lehnen dieselben Dokumente ab, bis auf eine Grenze bei format, die in Benannte Formate genannt ist: Über den Zeiger wird ein format innerhalb eines anyOf-, oneOf- oder not-Zweigs der Form nicht geprüft. Ansonsten unterscheidet sich, wie viel Ihnen die Meldung sagt, was vor allem in einem Editor zählt, wo die Markierung anhand dieses Pfads platziert wird. Dasselbe gilt für einen $defs:-Eintrag, dessen eigener Zeiger wieder in die Eigenschaften hinausreicht: Wer eine Definition über ihn erreicht, erbt die gröbere Meldung.

Bedingte Form über when:

JSON Schema 2020-12 drückt eine bedingte Form über if/then/else aus. Die kompakte Form bietet when: als direktere Kurzschreibweise: ein Go-Template-Prädikat, das, wenn es wahr ist, die übrigen Einschränkungen des Knotens anwendet; wenn es falsch ist, wird der Knoten so behandelt, als gäbe es seine Einschränkungen nicht.

secondary:
$ref: "#/$defs/NodePool"
when: '{{ eq $.architecture "replication" }}'
required: true
properties:
replicaCount: { type: integer, min: 2 }

Das Prädikat wird gegen die Instanzwerte des übergeordneten Elements ausgewertet. $ bezeichnet den umgebenden Objektbereich. Wenn architecture den Wert replication hat, gelten die Einschränkungen (required: true, das zusätzliche replicaCount: min: 2) zusätzlich zum referenzierten NodePool. Wenn architecture den Wert standalone hat, sind diese Einschränkungen inaktiv.

Das Prädikat hat Zugriff auf die Standardfunktionen von Go-Templates (Sprig). Der Compiler kompiliert when: zu if/then/else von JSON Schema plus einem Wrapper, der das Go-Template-Prädikat auswertet, bevor die Validierung läuft. Der Determinismus bleibt erhalten, weil das Prädikat in Bezug auf die Instanz rein ist.

Benutzerdefinierte Validierung pro Feld über validate: und validateMessage:

Manche Einschränkungen lassen sich nicht mit min / max / pattern / enum ausdrücken. Für diese bietet die kompakte Form validate: — ein Go-Template-Prädikat, das, wenn es falsch ist, die Validierung mit einem benutzerdefinierten Fehler anhält.

db_size:
type: string
pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$"
validate: '{{ regexFind "^[0-9]+" . | atoi | lt 100 }}'
validateMessage: "db_size must exceed 100 in its declared unit"

Das Prädikat läuft gegen den Wert des Felds (zugänglich als .); der umgebende Objektbereich ist $. Gibt das Prädikat false zurück, erzeugt die Validierung einen Fehler mit validateMessage: (oder einer Standardmeldung, falls keine angegeben ist).

validate: behandelt Fälle jenseits des Standardvokabulars von JSON Schema: benutzerdefinierte semantische Validierung (Prüfung des Semver-Formats, JSON-Inhalt einer Zeichenkette), feldübergreifende Regeln mit engem Bereich, bei denen die Einschränkung eines Felds von einem Geschwisterfeld abhängt, und Einschränkungen, die keinen vollständigen assertions:-Block wert sind.

validate: unterscheidet sich von when: in der Rolle: when: schaltet um, ob Einschränkungen gelten; validate: ist selbst eine Einschränkung.

Für wirklich feldübergreifende Regeln mit weitem Bereich, bei denen kein einzelnes Feld „das zu validierende“ ist, verwenden Sie den dafür vorgesehenen assertions:-Block. Siehe templates/assertions-block.md.

Ein Blatt als sensibel deklarieren — sensitive:

Ein values-, infra- oder provides-Blatt kann deklarieren, dass der Datenwert, den es beschreibt, geheimes Material trägt:

spec:
schema:
values:
origin:
type: string
required: true
sensitive: true
description: "The credential material itself."
key:
type: string
default: value
description: "The data key the material is stored under."

sensitive: true wird zum Erweiterungs-Schlüsselwort x-aggrega-sensitive: true an diesem Knoten im aufgelösten JSON Schema kompiliert, neben den anderen x-aggrega-*-Annotationen. Der Compiler liest es, um abzuleiten, welche Anbindungen in einer Bereitstellung als sensibel deklariertes Material verarbeiten, und trägt diese abgeleitete Tatsache im kompilierten Graphen.

Deklarieren Sie es am Datenwert, nicht an seinem Lokator. Die Unterscheidung ist der ganze Sinn des Schlüsselworts, und man verwechselt sie leicht. Das Material eines Zugangsnachweises ist sensibel; der Name der Ressource, die es enthält, und der Datenschlüssel innerhalb dieser Ressource sind es nicht — beide sind öffentlich, und beide werden im Klartext in jeden Konsumenten gerendert, der die Ressource referenziert. Einen Lokator zu markieren sagt etwas Unwahres über ihn aus und gibt diesen Fehler an alles nachgelagert weiter, was die Deklaration liest. Im obigen Beispiel ist origin markiert und key bewusst nicht.

Die komplementäre Aussage — was auch immer an diesen Punkt bindet, verarbeitet geheimes Material, unabhängig davon, was die Füllung über ihre eigenen Blätter deklariert — ist überhaupt keine Blattdeklaration. Es ist sensitive an einem Anbindungs-Slot; siehe entities/component.md „Attachment Slots (Anbindungs-Slots)“.

Ein ganzes Objekt als sensibel deklarieren

Das Schlüsselwort kann statt an einem Skalar an einem Objekt stehen und deckt dann alles unterhalb dieses Objekts ab — die eigenen Kinder des Objekts und alles, was weiter darunter verschachtelt ist. Es ist die Deklaration, zu der Sie greifen, wenn ein ganzer Block Material ist und das einzelne Markieren jedes Blatts das nächste Blatt, das jemand hinzufügt, unmarkiert lassen würde.

Die Kinder des Objekts müssen in einem expliziten properties:-Block stehen. Dies ist die eine Stelle, an der die inferierte Objektform nicht dient, und den Grund sollten Sie kennen, statt ihn zu umgehen:

spec:
schema:
values:
credentials:
type: object
sensitive: true
properties: # required here
username: { type: string }
password: { type: string }

Die Kinder direkt neben die Markierung zu schreiben, wie es die inferierte Objektform überall sonst erlaubt, wird zur Kompilierzeit abgelehnt — das erste Kind wird als unbekanntes Schlüsselwort gemeldet, positioniert auf dem eigenen Schlüssel des Kinds:

values:
credentials:
type: object
sensitive: true
password: # refused: unknown keyword "password"
type: string

Die Ablehnung ist korrekt und keine Begrenzung, die man umgehen müsste. Ein Knoten wird als Einschränkungsblatt gelesen, sobald er ein Schlüsselwort der kompakten Form trägt, und sensitive: ist eines — daher muss von diesem Punkt an jeder Geschwisterschlüssel ebenfalls ein Schlüsselwort sein, und password ist keines. Der properties:-Block ist das, was sagt: „Die Schlüssel darunter sind Eigenschaftsnamen, keine weiteren Schlüsselwörter“, und es ist dieselbe Unterscheidung, die Inferierte und explizite Objektform beschreibt. Die Diagnose als „die Markierung kann nicht an einem Objekt stehen“ zu lesen, ist die zu vermeidende Fehldeutung: Sie kann es, und der Block ist die Art, das zu sagen.

Ein Blatt innerhalb eines deklarierten Objekts braucht keine eigene Markierung. Eine hinzuzufügen ist harmlos und sagt nichts Neues, da die Deklaration des Objekts es bereits abdeckt.

Was das Schlüsselwort nicht tut

Der Name weckt Annahmen, die das Schlüsselwort nicht verdient, daher sei die Obergrenze klar benannt:

  • Es verschlüsselt nichts. Es ist eine Annotation an einer Deklaration, kein Vertraulichkeitsmechanismus.
  • Es validiert nichts und lehnt nichts ab, außer wo die Parameter eines CloudFormation-Templates befüllt werden. Kein Wert wird akzeptiert oder abgelehnt, weil ein Blatt als sensibel deklariert ist, und kein Build-Ergebnis ändert sich — außer dass dort, wo das valuesMapping eines CloudFormation-Recipe oder -FeatureRecipe ein als sensibel deklariertes Blatt liest, um die Parameter eines bezogenen Templates zu befüllen, jedes Literal, das dieses Mapping bindet, den Build stoppt, sodass zwei Builds, die sich nur durch die Deklaration unterscheiden, unterschiedlich enden können. Siehe A secret bound to a CloudFormation parameter would be written into the template (Ein an einen CloudFormation-Parameter gebundenes Geheimnis würde in das Template geschrieben).
  • Es garantiert nicht, dass die gerenderte Ausgabe frei von Material ist. Ob ein Artefakt Material trägt, hängt davon ab, welche Füllung ein Autor angebunden hat und was der Autor in ihre values geschrieben hat — siehe architecture/08-credential-model.md „What the compiler does and does not guarantee (Was der Compiler garantiert und was nicht)“. Ein als sensibel deklarierter Wert, den ein Autor inline angegeben hat, wird genau so gerendert wie ein nicht deklarierter, wo immer der Build ihn überhaupt rendert.
  • Es erzwingt keinen Zustellungsmechanismus. Es kann einen Inline-Wert nicht in eine Store-Referenz umwandeln, und es schränkt nicht ein, was die inject-Allowlist eines Slots erlaubt.
  • Es hält keinen Build an, außer durch diese CloudFormation-Ablehnung. Die Build-Zeit-Meldungen, die es auslöst und die unten beschrieben sind, sind Hinweise: Der Build läuft bis zum Ende und schreibt seine Artefakte. Eine Meldung fatal zu machen, ist die Entscheidung einer Organisation, ausgedrückt als Governance-Richtlinie, die an den Build angebunden ist, nicht etwas, das das Schlüsselwort von sich aus tut. Die oben genannte Ablehnung durch den CloudFormation-Provider ist die Ausnahme: Sie hält den Build an, weil ein in ein Template geschriebenes Literal für jeden lesbar ist, der den Stack lesen kann.
  • Es ändert auf den meisten Zielen kein gerendertes Byte, und auf diesen wird es das nie tun. Eine Zielplattform mit einem eigenen Sensibilitätsbegriff ist der Ort, an dem eine Deklaration landen kann; ein Ziel ohne einen solchen bietet ihr dauerhaft nichts, was sie ändern könnte. Terraform ist das einzige Ziel der Standardbibliothek mit einem solchen Primitiv: Wo die Eingabe eines vendorisierten Moduls Material aufnimmt, das ein Autor als sensibel deklariert hat, erhält die gerenderte Ausgabe eine generierte Override-Datei, die Terraforms eigenes Sensibilitätsattribut für diese Eingabe angibt — siehe providers/terraform.md „Declared-sensitive module inputs (Als sensibel deklarierte Moduleingaben)“. Überall sonst lässt das Deklarieren eines Blatts als sensibel in einem bestehenden Katalog jedes gerenderte Artefakt unverändert.

Was es an der Ausgabe des Werkzeugs ändert

Das Einzige, was eine Deklaration tatsächlich ändert, ist das, was das Werkzeug für einen Menschen zum Lesen ausgibt: seine Debug-Ausgabe und den Text einer Ablehnung, wie unten beschrieben. Auf den Debug-Oberflächen wird ein als sensibel deklarierter Wert durch den festen Text <redacted> ersetzt:

  • der Trace pro Durchlauf, den aggrega build --trace nach .trace/ schreibt;
  • der Values:-Block pro Knoten, den aggrega inspect für ein Aggregate ausgibt;
  • der Anbindungsblock pro Blatt, den aggrega inspect für ein aufgelöstes Release ausgibt.

Der Schlüssel bleibt immer erhalten und nur sein Wert wird ersetzt, sodass ein Leser weiterhin sieht, dass das Blatt verfasst ist und dass etwas zurückgehalten wurde. Ein Blatt, das der Autor nicht deklariert hat, gibt seinen Wert wortwörtlich neben einem zurückgehaltenen Geschwister aus — die Ersetzung folgt der Deklaration und nichts anderem, daher wird ein Feld namens password ohne Deklaration ausgegeben und ein deklariertes Feld namens key nicht.

Eine Deklaration erreicht jedes Blatt unter ihr, und sie erreicht alle drei Oberflächen auf dieselbe Weise. Wo die Deklaration an einem Objekt steht, wird auch jeder in diesem Objekt verschachtelte Wert zurückgehalten, in beliebiger Tiefe — die Deklaration des Objekts benennt sie, daher behauptet ihr Zurückhalten nichts, was der Autor nicht geschrieben hat. Der Abgleich erfolgt über ganze Pfadsegmente statt über Text, daher bleibt ein Geschwister, dessen Name lediglich mit einem deklarierten Namen beginnt, unberührt: dbPassword zu deklarieren hält dbPasswordHint nicht zurück.

Das Zurückhalten im Trace kann für einen einzelnen Build abgeschaltet werden, wenn der zurückgehaltene Wert genau derjenige ist, der debuggt wird: aggrega build --trace --trace-unredacted schreibt die Werte in die Trace-Dateien und versieht jede dieser Dateien mit einem Header, der das angibt. Es ist eine Entscheidung zum Aufrufzeitpunkt ohne Konfigurationseinstellung, sie betrifft nur den Trace, und sie ist bei cli/aggrega-build.md „Showing the withheld values (Die zurückgehaltenen Werte anzeigen)“ dokumentiert. Die Layouts von aggrega inspect haben ihre eigene, --unredacted, dokumentiert bei cli/aggrega-inspect.md „Showing the withheld values (Die zurückgehaltenen Werte anzeigen)“.

Die Grenzen dieses Verhaltens zählen mehr als das Verhalten selbst.

Gerenderte Artefakte werden nie geschwärzt. Alles unter dist/ wird genau so ausgegeben, wie das Rendering es erzeugt hat, denn es ist das, was bereitgestellt wird: Ein Platzhalter, der in eine Manifestdatei geschrieben wird, wäre eine defekte Bereitstellung statt einer geschützten. Die Schwärzung betrifft, was das Werkzeug ausgibt, nie, was es schreibt. Eine Deklaration als Versprechen zu lesen, dass dist/ gefahrlos veröffentlicht werden kann, ist das eine Missverständnis, das es zu vermeiden gilt — die oben genannte Obergrenze bleibt unverändert, und dist/ bleibt so sensibel wie seine Anbindung, die das meiste Material trägt.

Eines kann eine Deklaration einem gerenderten Artefakt hinzufügen, und es ist keine Schwärzung: Wo ein Ziel ein eigenes Sensibilitätsprimitiv hat, wird die Deklaration in dieses gerendert. Der Wert wird weiterhin vollständig geschrieben — nichts wird zurückgehalten oder ersetzt —, und was das Artefakt gewinnt, ist die eigene Markierung des Ziels neben ihm, sodass die Werkzeuge des Ziels den Wert so behandeln können, wie der Autor ihn deklariert hat. Terraform ist das Ziel, das heute eines anbietet, und was sein Attribut garantiert und was nicht, steht in providers/terraform.md „Declared-sensitive module inputs (Als sensibel deklarierte Moduleingaben)“. Eine solche Markierung gelangt nur dorthin, wo die Identität des gerenderten Namens aus der Deklaration selbst gewonnen wird; wo ein Template den Namen erfunden hat, fehlt die Markierung, statt angenähert zu werden, denn einen Wert zu markieren, den der Autor nicht deklariert hat, würde etwas Falsches über ihn behaupten. Wo dieses Template ein valuesMapping ist — das eines Recipe oder das des FeatureRecipe zu einem an eine Komponente angebundenen Feature —, meldet der Build dies, wie unten beschrieben.

Die Schwärzung erreicht, was eine Deklaration benennt, und dazu, was ein Template erkennbar liest. Ein deklariertes Blatt in einer values- oder infra-Säule und ein Zustellschlüssel, der Material aus einem als sensibel deklarierten provides-Schlüssel trägt, werden beide über ihren Namen erkannt und zurückgehalten. Ein von einem Template berechneter Wert landet unter einem Schlüssel, den niemand deklariert hat, daher erkennt man ihn stattdessen an der Referenz, die der Autor geschrieben hat: Im Trace wird ein locals:-Eintrag oder ein source:-Feld, dessen Template ein als sensibel deklariertes Blatt liest, zurückgehalten, ebenso ein locals:-Eintrag, der ein bereits zurückgehaltenes Geschwister liest. Das Lesen ist bewusst vorsichtig — ein ganzes Objekt zu erreichen erreicht jedes deklarierte Blatt darunter, und ein Template, das seine gesamten Daten weitergibt, erreicht sie alle —, sodass eine nicht auflösbare Referenz zurückhält, statt auszugeben.

Ein gerendertes Dokument wird als erneutes Rendering gezeigt und weist darauf hin. Der geparste Workload des Trace ist ein Dokument, das das Template des Recipe erzeugt hat: Nichts darin hält fest, aus welcher Deklaration jedes Zeichen stammt, daher gibt es darin keinen Schlüssel, an dem ersetzt werden könnte, und die Verbindung Feld für Feld wiederherzustellen hieße, den Inhalt eines Werts zu untersuchen — was der Compiler nicht tut. Was der Trace stattdessen zeigt, ist dasselbe workload:-Template, erneut ausgewertet gegen einen Kontext, dessen als sensibel deklarierte Daten bereits als Ersatztext gelesen werden, angekündigt in einem workload_note-Eintrag neben dem Dokument. Weil das Template eine Zeichenkette sieht, wo eine Zeichenkette war, behält das erneute Rendering die Form des ausgegebenen Dokuments, und der Ersatztext steht an der eigenen Position des zurückgehaltenen Datenwerts. Zwei Unterschiede bleiben, und der Hinweis nennt beide: Ein Template, das nach dem Inhalt eines Werts verzweigt, rendert gegen den Ersatztext anders, und ein Datenwert, den die Achse nicht benennt, wird unverändert durchgereicht. Es ist eine Debug-Ansicht dessen, was gerendert wurde, nie eine Kopie davon.

Die Werte eines konsumierten Knotens werden anhand der Deklarationen dieses Knotens zurückgehalten, auf beiden Oberflächen, zu denen die Kante sie trägt. Eine Ansicht einer uses-Kante gibt wieder, was eine Zielkomponente veröffentlicht hat, daher regelt das eigene Schema des Ziels sie: Ein provides-Schlüssel, den das Ziel als sensibel deklariert hat, wird im Trace des Konsumenten zurückgehalten, selbst wenn der Konsument nichts deklariert. Wo der eigene inject-Block der Kante diesen Schlüssel auf einen Zustellschlüssel der konsumierenden Komponente leitet, wird auch dieser Zustellschlüssel zurückgehalten — dieselbe Regel, der das inject-Mapping einer Anbindung folgt, mit derselben Deklaration, sodass die beiden Verdrahtungen nicht voneinander abweichen können. Die Layouts von aggrega inspect zeigen die eigenen Säulen eines Knotens und seine Anbindungen, nicht die veröffentlichten Werte eines konsumierten Knotens, daher trägt dort nichts eine knotenübergreifende Ansicht, die zurückzuhalten wäre.

Eine auf einer Verbindung geschriebene Anbindung wird anhand der Deklarationen ihres eigenen Feature zurückgehalten, auf jeder Oberfläche, die sie zeigt. Der Trace zeigt sie unter der Ansicht der uses-Kante dieser Verbindung, unter .context.uses.<alias>.features.<slot>, und aggrega inspect gibt sie unter der Zeile der Verbindung in einem aufgelösten Release aus. Auf beiden wird ein values- oder infra-Blatt, das ihr Feature als sensibel deklariert, genau so zurückgehalten wie auf demselben Feature, wenn es direkt an die Komponente angebunden ist, und im Trace wird auch ein Schlüssel des aufgelösten provides der Anbindung zurückgehalten, den das Feature als sensibel deklariert. Ihr Typ, ihre Version, ihre Labels und jedes nicht deklarierte Blatt und jeder nicht deklarierte provides-Schlüssel werden wörtlich ausgegeben, sodass ein veröffentlichter Lokator neben dem Material lesbar bleibt, das er lokalisiert. Ein Slot, der sensitive: true deklariert, an der Komponente oder an einem Socket, kennzeichnet die Anbindung als eine, die geheimes Material verarbeitet, und hält aus eigenem Antrieb kein Blatt zurück — welche Blätter zurückgehalten werden, hat das Feature zu deklarieren.

Die maschinenlesbaren Projektionen sind vertragsgemäß wörtlich und brauchen dieselbe Behandlung wie die Dateien, aus denen sie stammen. aggrega inspect --raw gibt eine Entität genau so aus, wie sie verfasst wurde, und aggrega inspect --output yaml gibt die verfasste Entität für jede Art wieder, ein Release eingeschlossen. Keine der beiden ersetzt etwas, und das ist gewollt: Dies sind die Ausgaben, die ein Skript parst und ein Diff vergleicht, daher würde eine Ausgabe, die stillschweigend einen Teil von sich zurückhielte, die Eingabe falsch darstellen, die sie wiederzugeben vorgibt, und den Round-Trip brechen, auf den ihre Konsumenten angewiesen sind. Ein Blatt als sensibel zu deklarieren reicht nicht aus, um es aus diesen Ausgaben herauszuhalten: Leiten Sie sie weiter, speichern und teilen Sie sie so, wie Sie es mit dem Aggregate und dem Release selbst tun würden.

Der kompilierte Graph ist die eine maschinenlesbare Projektion, die zurückhält, wo immer er herausgegeben wird. --ir-graph schreibt bei aggrega inspect, aggrega validate und aggrega build den Graphen, den der Lauf aufgelöst hat, als JSON neben das, was der Befehl ohnehin erzeugt, und aggrega/irGraph des Daemons beantwortet einen Editor mit demselben Graphen; in jedem Fall wird ein Wert, den ein Autor als sensibel deklariert hat, genau so ersetzt wie in den lesbaren Layouts. --unredacted neben --ir-graph gibt stattdessen diese Werte aus, ebenso das Feld unredacted in der Anfrage an den Daemon. Damit sind der aus einem Befehl gelesene Graph und der über das Protokoll des Daemons gelesene Graph dasselbe Dokument unter derselben Behandlungsregel, und eine Pipeline oder ein Client, die die verfassten Werte benötigt, muss sie anfordern.

Was eine Ablehnung über einen deklarierten Wert aussagt

Eine Ablehnung, die von einem Template ausgelöst wird, das einen von einem Autor als sensibel deklarierten Wert liest, enthält diesen Wert nicht. Wenn ein Template den Build anhält — eine Assertion, die fail aufruft, ein Ausdruck, der nicht ausgewertet werden kann, eine Ausgabe, die sich nicht als das Dokument lesen lässt, das das Template erzeugen muss — und eine seiner Referenzen einen als sensibel deklarierten Datenwert erreicht, stammt das Gemeldete aus einer zweiten Auswertung desselben Templates gegen einen Kontext, in dem jeder als sensibel deklarierte Datenwert bereits als <redacted> gelesen wird — es sei denn, das Template hielt bei einem Satz an, den es selbst ausschreibt; das ist der erste Fall unten:

assertion failed: the admin password <redacted> must be supplied as a reference
  • Ein fail, dessen Satz im Template ausgeschrieben ist, wird so gemeldet, wie er geschrieben ist. Wo der Aufruf, der den Build angehalten hat, fail mit einer einzigen Zeichenkette in Anführungszeichen ist — fail "…", ohne dass etwas hineingepipt oder in seinen Satz eingesetzt wird —, enthält die Ablehnung diesen Satz, was immer der Wert enthält und welcher Zweig auch zum Aufruf geführt hat, denn der Satz zitiert nichts, was das Template gelesen hat: Eine Assertion, die einen Ursprung in falscher Form ablehnt, zeigt ihre eigene Erklärung der Form. Ein Satz, der auf andere Weise gebildet wird — printf, ein Feld, eine Variable, ein in fail gepipter Wert —, wird gemäß den folgenden Fällen gemeldet.
  • Wo die zweite Auswertung am selben Ausdruck aus demselben Grund fehlschlägt, wird ihr Fehlschlag gemeldet. Der eigene Satz des Autors bleibt erhalten, mit <redacted> an der Stelle des Werts, und ein Wert, den das Template codiert, in Anführungszeichen gesetzt oder anderweitig umgewandelt hat, wird ebenfalls zurückgehalten, weil die Ersetzung vor der Umwandlung stattfindet.
  • Wo sie es nicht tut, nennt die Ablehnung den fehlschlagenden Ausdruck und gibt an, dass sein Text zurückgehalten wird. Das ist ein Template, dessen Verhalten davon abhing, was der Wert enthält — es nahm gegen den Ersatztext einen anderen Zweig oder schlug an anderer Stelle fehl —, daher kann nichts, was es zusammengesetzt hat, gezeigt werden. Damit eine solche Ablehnung sich selbst erklärt, schreiben Sie ihren Satz im Aufruf von fail aus, wie der erste Fall beschreibt. Die Ablehnung hält den Build trotzdem an und behält ihren Code.
  • Eine gerenderte Workload, die das Workload-Schema ablehnt, wird anhand des Schemas formuliert. Die Felder des Dokuments tragen keine Verbindung zurück zu den Daten, die sein Template gelesen hat, daher gibt dort, wo dieses Template einen als sensibel deklarierten Datenwert gelesen hat, jeder Befund, der einen Wert zitieren könnte, stattdessen die Einschränkung an, mit <redacted> an der Stelle des Werts und einem Hinweis, der den Grund nennt. Kein aus dem Wert abgeleiteter Rat wird gegeben, und ein Befund, der keinen Wert zitiert — ein fehlender Schlüssel, ein Schlüssel, den die Workload nicht zulässt —, liest sich wie immer:
.containers.main.imagePullPolicy: against /$defs/container: enum: <redacted> does not satisfy enum ["Always","Never","IfNotPresent"] (the value is withheld because the template that rendered this document reads a value declared sensitive)
  • Eine with-Eingabe eines Pipeline-Schritts, die vom deklarierten Eingabevertrag des Schritts abgelehnt wird, wird anhand des Vertrags formuliert, wo das with-Template einen als sensibel deklarierten Datenwert liest: jede fehlschlagende Position in der Eingabe und das Schema-Schlüsselwort, das sie abgelehnt hat, gefolgt von einem Hinweis, der den Grund nennt, und nichts von dem, was die Eingabe trug.
  • Eine Ablehnung, die eine source:-Koordinate nennt, wird anhand dessen formuliert, was nichts Deklariertes erzeugt hat, wo ein source:-Template diese Koordinate durch Lesen eines als sensibel deklarierten Datenwerts erzeugt hat — die Quelle ist nicht im Lockfile oder im Cache, ihr zwischengespeichertes Archiv stimmt nicht mit dem überein, was das Lockfile festhält, oder der neben der Entität festgehaltene Pin weicht vom Lockfile ab. Jede Zeile, die eine solche Ablehnung ausgibt, nennt die Koordinaten, die die Suche verwendet hat, daher nennt sie die Quelle über ihre url und die Version oder Referenz, zu der sie angefragt wurde — wo sie diese gelesen hatte —, wobei <redacted> für jede steht, die ein solches Template erzeugt hat, und gibt an, dass ihr Grund zurückgehalten wird. Sie behält ihren Code und die Abhilfe, die der Build für diesen Code angibt:
source-artifact https://example.com/fragments/app.yaml@<redacted>: the reason is withheld: the template producing this source reads a value declared sensitive, and the reason names what the template produced

Als deklariert gilt, was die Deklarationen benennen, in jedem Teil des Kontexts, den ein Template lesen kann: die eigenen values und infra der Komponente, die an sie und an jede ihrer Verbindungen angebundenen Features, ein Zustellschlüssel, der deklariertes Material trägt, ein provides-Schlüssel, den ihre Component als sensibel deklariert, jeder Eintrag einer Liste, die der Kontext trägt, wie unten beschrieben, und ein aus einem davon berechneter locals:-Eintrag. Ein Template, das keines davon liest, meldet genau so, wie es ohne jede Deklaration irgendwo melden würde, Byte für Byte, sodass nur eine Ablehnung, die von einem Template ausgelöst wird, das einen deklarierten Wert gelesen hat, anders gemeldet wird. Das Lesen ist dasselbe, das der Trace verwendet, gewonnen aus den Referenzen, die ein Template ausschreibt: Ein ganzes Objekt zu erreichen erreicht jedes deklarierte Blatt darunter, sodass Text zurückgehalten werden kann, der keinen Wert enthielt. Ein Template, das seine gesamten Daten auf einmal weitergibt — den Punkt oder $ ohne etwas danach, an eine Funktion wie toJson übergeben, ausgegeben oder an ein Template übergeben, das es über den Namen aufruft —, liest jeden deklarierten Wert darin, daher wird seine Ablehnung auf dieselbe Weise gemeldet; innerhalb eines range- oder with-Rumpfs ist der Punkt der Wert, über den dieser Rumpf iteriert oder den er benennt, und ihn weiterzugeben liest nur, was dieser Wert enthält. Nichts hier hängt von --trace-unredacted ab: Dieses Flag erreicht allein die Trace-Dateien, und eine Ablehnung liest sich mit und ohne es gleich.

Ein deklarierter Wert wird zurückgehalten, wo immer er steht, auch innerhalb einer Liste. Die Einträge einer Liste werden von verschiedenen Entitäten geregelt, und jeder Eintrag wird anhand der eigenen zurückgehalten. In der .boundary-Ansicht, die ein FeatureRecipe mit Boundary-Geltungsbereich liest, trägt jede in internal_uses_edges, outgoing_cross_boundary_uses_edges, incoming_cross_boundary_uses_edges und cross_boundary_uses_edges aufgeführte Verbindung die provides, die ihr Ziel veröffentlicht, zurückgehalten, wo die Component des Ziels den Schlüssel als sensibel deklariert, und jeder Eintrag von feature_attachments trägt die infra dieser Anbindung, zurückgehalten, wo ihr Feature das Blatt deklariert. Im Kontext eines an eine Komponente angebundenen Feature trägt jeder Eintrag von .context.used_by, was die verbindende Komponente veröffentlicht, zurückgehalten, wo die Component der verbindenden Komponente den Schlüssel deklariert. Derselbe Schlüssel auf einem Eintrag, dessen Entität nichts deklariert, wird so zitiert, wie er ist, und ein aus einem zurückgehaltenen Eintrag berechneter locals:-Eintrag wird mit ihm zurückgehalten. Über eine Liste zu iterieren oder einen ihrer Einträge über index zu erreichen liest die ganze Liste, daher gilt es als Lesen dessen, was jeder Eintrag trägt:

error calling fail: target secret_ref "<redacted>" must start with ref-

Das erreicht den Text einer Ablehnung, die der Build auslöst. Was einem Provider darüber mitgeteilt wird, welche seiner Eingaben aus einem deklarierten Wert stammen — die Werte, die ein valuesMapping erzeugt hat, ein gerendertes workload:-Dokument, jeder artifacts:-Eintrag, jedes Feld eines omits:-Eintrags —, zählt keinen Wert, der aus dem Inneren einer Liste gelesen wurde, daher erreicht die eigene Behandlung eines deklarierten Werts durch einen Provider, einschließlich der oben beschriebenen CloudFormation-Ablehnung eines gebundenen Literals, einen solchen nicht.

Manche Ablehnungen liegen außerhalb davon. Text, den ein Plugin schreibt — die eigene Ablehnung, die ein Provider oder ein Pipeline-Schritt formuliert —, ist der Satz aus dem Plugin, unverändert so weitergegeben, wie das Plugin ihn geschrieben hat. Ein Template, das außerhalb der Assertions des Builds und seines Renderings ausgewertet wird — Parameterinterpolation und Parameterprüfungen in einem Aggregate, die when:- und validate:-Templates eines Schemas und die Auflösung einer source:-Koordinate, die ihren Pin festhält —, meldet seinen Fehlschlag so, wie er fehlgeschlagen ist.

Die Build-Meldung für einen als Literal übertragenen Wert

Ein Build gibt eine Meldung pro Zustellschlüssel aus, der als sensibel deklariertes Material als literalen Wert trägt. Sie wird ausgelöst, wenn der inject-Block einer Anbindung einen provides-Schlüssel, den das Feature der Anbindung als sensibel deklariert hat, auf einen Zustellschlüssel der konsumierenden Komponente leitet und der Wert tatsächlich zugestellt wird:

warning: node "db" (provider "helm"): attachment "user_password" delivers a value
declared sensitive to env delivery key "MARIADB_PASSWORD" as a literal; where the
target supports it, fill the slot with an attachment that delivers a reference instead

Drei Dinge daran sind beabsichtigt.

Sie meldet, wie ein Wert übertragen wird, nicht, dass etwas falsch ist. Ein Literal zuzustellen ist häufig das Einzige, was ein Ziel akzeptiert, und eine ganze Familie von Anbindungen existiert genau dafür. Die Meldung sagt einem Autor, welcher Wert diesen Weg nimmt und wo, sodass die Wahl sichtbar statt implizit ist; sie behauptet nicht, dass die Wahl ein Fehler ist.

Sie ist eine Warnung und nie ein Abbruch. Der Build ist erfolgreich und schreibt seine Artefakte unverändert. Eine Organisation, die will, dass ein als Literal zugestellter Zugangsnachweis den Build scheitern lässt, drückt das als Governance-Richtlinie über den Build aus, denn dort gehört eine Ablehnung hin — eine Regel, die manche Bereitstellungen brechen müssen, ist kein Standardverhalten des Compilers.

Sie wird anhand der Verdrahtung entschieden, nie anhand des Werts. Die Meldung liest die Sensibilität, die ein Schema deklariert hat, und dazu die Zustellung, die der Autor geschrieben hat. Kein Wert wird untersucht, daher wird ein Feld nie anhand seines Namens oder seines Inhalts für einen Zugangsnachweis gehalten, und ein nicht deklarierter Wert, der zufällig ein Passwort enthält, löst nichts aus.

Zwei Fälle bleiben bewusst still. Ein Zustellschlüssel, dessen referenzierter provides-Schlüssel nichts veröffentlicht, stellt kein Literal zu und meldet nichts — die Meldung folgt einer Zustellung, die stattgefunden hat. Und ein Slot, dessen inject-Allowlist leer ist, überlässt die Zustellung dem Recipe, sodass der Autor keinen Zustellschlüssel geschrieben hat, der zu melden wäre, und nichts hat, worauf er reagieren könnte.

Die Meldung ist eine eigene Klasse, über ihren eigenen Code identifiziert, und --no-unsupported-field-warnings bringt sie nicht zum Schweigen: Dieses Flag deckt die Hinweise zur Wiedergabetreue eines Ziels ab, die eine andere Beurteilung sind und aus anderen Gründen unterdrückt werden. Sie erreicht auch den Editor, wo sie als Problem am Aggregate erscheint, sobald der Language Server mit eingeschaltetem --build-on-inspect (oder dem Konfigurationsschlüssel serve.build_on_inspect) läuft. Diese Einstellung ist standardmäßig ausgeschaltet, aus Konsistenz mit aggrega inspect: Der Terminalbefehl erreicht beim Untersuchen eines Graphen nie die Rendering-Phase, daher löst auch er keine solche Meldung aus, und eine Untersuchung im Editor, die ebenfalls keine auslöst, zeigt Ihnen dasselbe wie das Terminal. Die Einstellung einzuschalten ist die Art, wie Sie den Editor um die zusätzliche Schicht bitten, und dabei wird nichts auf die Festplatte geschrieben — die Phase läuft, und ihre Artefakte werden verworfen. Sie fügt die Meldungen hinzu, die ein Build beim Rendern auslöst, und keine der Prüfungen, bei denen ein Build anhält. Jedes veröffentlichte Problem nennt die Schicht, die es ausgelöst hat, sodass ein Editor diese Meldung von denen getrennt halten kann, die die Auflösungs- und die Analysephase melden.

Die Build-Meldung für einen Wert, den ein Mapping ohne Markierung rendert

Ein Build gibt eine Meldung pro als sensibel deklariertem values-Blatt aus, dessen Markierung ein Rendering nicht tragen kann, solange der Autor noch den Hebel dafür in der Hand hat. Sie wird bei einem Rendering aus einer source: ausgelöst, deren Werte die Ausgabe eines valuesMapping sind — dem eines Recipe, über ein Blatt, das seine Component deklariert, oder dem des FeatureRecipe eines an eine Komponente angebundenen Feature, über ein Blatt, das dieses Feature deklariert. Die Ausgabeschlüssel des Mappings sind seine eigene Erfindung, daher benennt keine Deklaration einen von ihnen, und das Ziel erhält für das Blatt keine Markierung pro Schlüssel:

warning: node "api" (provider "terraform"): attachment "token": "values.token" is declared
sensitive, but FeatureRecipe "terraform/api-token" maps its values through a valuesMapping
whose output keys no declaration names, so the target receives no per-key sensitivity
marking for it; ...

Die Zeile nennt das Blatt an seiner verfassten Koordinate und das Recipe oder FeatureRecipe, dessen Mapping die Verknüpfung steuert, denn die Deklaration und das Mapping werden in zwei verschiedenen Entitäten geschrieben; die Zeile einer Anbindung beginnt mit dem Namen, unter dem sie angebunden ist, sodass zwei Anbindungen eines Feature an einer Komponente unterschieden werden. Das Mapping zu entfernen ist der Hebel: Ohne eines sind die Werte, die ein Quell-Rendering erhält, nach den deklarierten Blattpfaden geschlüsselt, und die Markierung reist mit ihnen. Ein reines Artefakt-Rendering und ein reines Arbeitslast-Rendering bleiben still, weil sie ihrem Ziel überhaupt keine Werte-Map übergeben, und ebenso ein an eine Boundary angebundenes Feature, das gegen eine leere values-Säule rendert — die oben genannte Obergrenze ist dort dauerhaft, und eine Warnung würde nichts nennen, was zu tun wäre. Wie die Meldung für einen als Literal übertragenen Wert ist sie eine Warnung und nie ein Abbruch, sie ändert kein gerendertes Byte, sie ist eine eigene Klasse mit eigenem Code, sensitivity-not-conveyed, und --no-unsupported-field-warnings bringt sie nicht zum Schweigen. Warnungen und Linter-Ausgabe beschreibt ihre vollständige Form.

Wo die Deklaration gelesen wird und wo nicht

Das Schlüsselwort wird an dem Knoten gelesen, an dem es steht, und das Lesen folgt dann jedem Weg, auf dem eine Deklaration diesen Datenwert erreichen kann: verschachtelten Eigenschafts-Maps, jedem Kompositionszweig und dem Ziel eines $ref. Ein Zweig und ein Referenzziel werden beide auf die Eigenschaft komponiert, die sie trägt, daher wird eine über einen von beiden gefundene Deklaration für diese Eigenschaft gesammelt; nur ein Abstieg über properties verlängert den Pfad.

Eine Markierung wird gelesen, ob sie neben einem dieser Schlüsselwörter steht oder innerhalb dessen, was das Schlüsselwort erreicht, daher brauchen zwei Formen keine bewusste Platzierung:

  • Neben einem $ref oder innerhalb des Ziels der Referenz. Eine Markierung am verweisenden Blatt deklariert dieses Blatt. Eine Markierung im referenzierten Schema wird ebenfalls für das verweisende Blatt gesammelt, am Pfad dieses Blatts plus der Kette darunter — nie an einem Pfad innerhalb der Definition, wo kein verfasster Wert lebt.
  • Neben einem Kompositionsschlüsselwort (allOf / anyOf / oneOf) oder innerhalb der eigenen properties eines Zweigs. Ein Zweig wird auf das Objekt komponiert, das ihn trägt, daher wird in jeden Zweig abgestiegen — die bedingten Zweige eines als JSON Schema verfassten Knotens eingeschlossen —, und eine Deklaration in einem davon wird am eigenen Pfad der komponierenden Eigenschaft plus ihrer Kette gesammelt.

Eine Form braucht die Markierung dagegen bewusst platziert:

  • Am Array-Blatt selbst, nicht an seinem items-Elementtyp. Ein Array, dessen Elemente Material tragen, wird am Array als sensibel deklariert, weil ein Elementtyp keine Eigenschafts-Map ist und nicht in ihn abgestiegen wird.

parameters: ist ein anderes Vokabular

sensitive gehört nicht zum typisierten Vertragsvokabular von parameters:. Ein Aggregate, das es an einem Parametereintrag deklariert, wird beim Laden des Aggregate abgelehnt, mit einer Diagnose der Dokumenthülle, die unexpected property: "sensitive" meldet, positioniert auf dem betreffenden Schlüssel selbst — dieselbe Behandlung, die jeder Schlüssel außerhalb dieses Vokabulars erhält, da der Parametervertrag ein geschlossenes Objekt ist.

Die Asymmetrie ist beabsichtigt: Die Sensibilitätsachse deckt die drei Datensäulen ab, die eine Katalogentität deklariert, und ein Parameter ist eine Eingabe des Umgebungsvertrags statt eines Säulenblatts. Das Hochziehen von Zugangsnachweis-Material über einen Parameter ist in architecture/08-credential-model.md „Legacy charts that demand a formatted string (Legacy-Charts, die eine formatierte Zeichenkette verlangen)“ dokumentiert, wo der Kompromiss genannt wird, den dieser Weg eingeht.

Komposition mit allOf, anyOf, oneOf

Kompositionsschlüsselwörter funktionieren wie in JSON Schema:

# Inherit and extend
secondary:
allOf:
- { $ref: "#/$defs/NodePool" }
- replicaCount: { type: integer, min: 2 }
# Disjunction (one of several shapes)
auth:
oneOf:
- existingSecret: { type: string, required: true }
- rootPassword: { type: string, required: true }
username: { type: string, default: app_user }
password: { type: string, required: true }

Der Compiler gibt dieselben Kompositionsschlüsselwörter im aufgelösten JSON Schema aus. Die komponierenden Einträge können jeweils kompakte Form, JSON Schema oder $ref:-Referenzen sein. Mischen innerhalb einer Komposition wird unterstützt.

Der Ausweg — $jsonschema:

Für Fälle jenseits des Vokabulars der kompakten Form ($dynamicRef, unevaluatedProperties, tiefe not:-Komposition, rekursive Typen) kann jeder Knoten auf vollständiges JSON Schema ausweichen:

values:
architecture: { type: string, enum: [standalone, replication] }
some_complex_field:
$jsonschema: |
type: object
unevaluatedProperties: false
allOf:
- $ref: "#/$defs/Foo"
- not:
required: [conflicting_field]
patternProperties:
"^x-": { type: string }
$defs:
Foo:
type: object
properties:
name: { type: string }

Der $jsonschema:-Block enthält JSON-Schema-YAML; der Compiler behandelt ihn als transparente Durchreichung — der Inhalt geht direkt an der Position dieses Knotens in das aufgelöste JSON-Schema-Dokument. Validierung, Fehlerberichte und Werkzeuge arbeiten alle auf dem aufgelösten Dokument; der Ausweg ist rein eine Erleichterung beim Verfassen.

Ein not:-Zweig kann eine description: tragen, die angibt, warum die Form, die er ausschließt, abgelehnt wird. Ein Wert, der diesem Zweig entspricht, wird dann mit der Beschreibung als Grund abgelehnt, ausgegeben in einer Zeile, anstelle der generischen Formulierung „not allowed here (hier nicht zulässig)“ — schreiben Sie sie daher als den Satz, den der Autor des abgelehnten Werts lesen soll. Verwendet wird nur eine Beschreibung, die am not:-Zweig selbst steht; eine an einem $defs-Eintrag, auf den der Zweig nur verweist, nicht.

Jeder Knoten innerhalb des Blocks wird als JSON Schema gelesen, und ein dort geschriebenes Schlüsselwort der kompakten Form behält seine kompakte Bedeutung (min: 3 an einer Zeichenkette ist weiterhin eine Mindestlänge). Ein $ref im Block wird so aufgelöst wie einer außerhalb: #/$defs/Foo benennt einen Eintrag des $defs: der Säule, daher deklariert das Beispiel Foo dort, und eine Referenz, die einen Eintrag benennt, den niemand deklariert hat, wird beim Laden der Entität abgelehnt. $dynamicRef wird gegen einen $dynamicAnchor aufgelöst, sodass sich eine rekursive Form schreiben lässt; ein Wert, der tief in der Rekursion fehlschlägt, wird an dem Feld gemeldet, das ihn enthält — tree.children, für ein fehlerhaftes name zwei Ebenen tief in einem Baum, dessen children-Elemente { $dynamicRef: "#node" } sind.

Für unevaluatedProperties und unevaluatedItems gilt eine Grenze. An einem Knoten geschrieben, der auch eine Referenz, ein Kompositionsschlüsselwort (allOf, anyOf, oneOf), eine Bedingung oder ein abhängiges Schema trägt, wird jedes der beiden geladen, aber nicht durchgesetzt — und unevaluatedItems wird auch neben contains nicht durchgesetzt. Im obigen Beispiel steht unevaluatedProperties: false neben allOf, daher wird { name: n, extra: 1 } akzeptiert, obwohl weder Foo noch patternProperties extra deklariert.

Der $jsonschema:-Ausweg gilt pro Knoten, nicht pro Dokument. Ein Schema kann die kompakte Form für die einfachen Teile, den JSON-Schema-Ausweg für das eine komplexe Feld und $ref: für gemeinsam genutzte Formen verwenden — alles in einem Dokument.

Kompakte Form und JSON Schema in einem Dokument mischen

Kompakte Form und JSON Schema lassen sich an jeder Grenze zwischen Knoten frei mischen. Die Zuordnungsregel richtet sich nach der Form des Inhalts:

  • Ein Knoten, der $jsonschema: enthält, wird als JSON Schema behandelt (der Ausweg).
  • Ein Knoten, der Schlüsselwörter der obersten Ebene im JSON-Schema-Stil enthält (type:, properties:, additionalProperties:, if: usw.), wird als JSON Schema behandelt (die explizite Form).
  • Ein Knoten, der nur Einträge Eigenschaftsname → Kind-Schema enthält (keine von JSON Schema reservierten Schlüsselwörter), wird als kompakte Form behandelt (inferierte Form).
  • Ein Knoten mit nur $ref: ist eine Referenz-Durchreichung.
  • Ein Knoten mit allOf: / anyOf: / oneOf: ist eine Komposition; jeder Eintrag wird unabhängig zugeordnet.

Für Blätter in kompakter Form ist das Standardmuster field_name: { type: ..., constraints... } — eine YAML-Map, die ein bekanntes Vokabular der kompakten Form enthält. Die Zuordnung erkennt Einschränkungs-Dicts an ihren Schlüsseln.

Für den seltenen mehrdeutigen Fall (z. B. ein Schema in kompakter Form mit einem Feld, das buchstäblich type heißt und das die Zuordnung der inferierten Form als das JSON-Schema-Schlüsselwort interpretieren würde) ist die explizite Form die kanonische Lösung — siehe „Reserved keywords at every inferred-form scope (Reservierte Schlüsselwörter in jedem Bereich in inferierter Form)“ oben.

Einen Vertrag aus einer Datei importieren — $import:

Ein Vertrag muss nicht innerhalb der Entität stehen, die ihn deklariert. $import: nennt eine Datei, aus der er gelesen wird:

spec:
schema:
$import: ./contracts/api-server.schema.yaml

Das gesamte spec.schema stammt dann aus dieser Datei, die genau wie der Block verfasst wird, den sie ersetzt — Säulen oben, kompakte Form oder JSON-Schema-YAML darunter:

contracts/api-server.schema.yaml
values:
greeting: { type: string, enum: [hello, howdy], default: hello }
infra:
image_tag: { type: string, default: "1.0" }
provides:
host: { type: string }

Eine einzelne Säule kann für sich importiert werden, während ihre Geschwister inline daneben verfasst werden:

spec:
schema:
values:
$import: ./contracts/values.yaml
infra:
image_tag: { type: string, default: "1.0" }

Dieselbe Form funktioniert bei valueSchema: und infraSchema: eines usesSchema:-Sockets.

Die Regeln, die dafür gelten:

  • $import: ist der einzige Schlüssel an der Position, an der er erscheint. Ein daneben geschriebenes Geschwister wird abgelehnt, statt dass einer der beiden verworfen wird.
  • Ein relativer Pfad wird gegen das Verzeichnis gelesen, das die Entitätsdatei enthält, die ihn deklariert hat, nie gegen das Verzeichnis, aus dem ein Build läuft — dieselbe Basis, die valuesMapping:, workload: und artifacts: verwenden. Er muss innerhalb dieses Verzeichnisses bleiben, denn jede Datei, die eine Veröffentlichung der Entität trägt, wird von dort genommen: Ein Pfad, der aus ihm hinausführt, oder ein absoluter Pfad benennt eine Datei, die nicht mit der Entität reisen würde, und wird abgelehnt — siehe A path names content outside the entity’s own directory (Ein Pfad benennt Inhalte außerhalb des eigenen Verzeichnisses der Entität). Ein Schema, das mehrere Entitäten teilen, gehört in eine SchemaLibrary, referenziert mit $ref:.
  • Die importierte Datei reist mit der Entität. Eine veröffentlichte Entität trägt jede Datei, die ihr Schema importiert, jede Datei einer Kette eingeschlossen, sodass eine aus einer Registry gezogene Kopie denselben Vertrag liest und die dagegen verfassten Werte validiert — siehe aggrega push.
  • Die importierte Datei trägt Schemainhalt, kein Entitätsdokument. Eine Datei, deren Inhalt keine YAML-Map ist, wird unter Nennung der Datei abgelehnt.
  • Eine importierte Datei kann selbst ein einzelnes $import: sein, das rekursiv aufgelöst wird; eine Kette, die zu einer bereits gelesenen Datei zurückkehrt, wird unter Nennung der Kette abgelehnt.

Der Import wird gelesen, wenn die Entität geladen wird, daher sieht jede Oberfläche, die diese Entität liest, denselben Vertrag: aggrega validate, ein Build, aggrega push, aggrega inspect und der Editor. Eine Datei, die nicht gelesen werden kann, oder Inhalt, der kein Schema ist, wird an dieser Stelle abgelehnt, statt den Vertrag nicht durchgesetzt zu lassen — und ein Push lehnt ihn ab, bevor irgendetwas veröffentlicht wird.

$import: und $ref: sind nicht austauschbar. $import: nennt eine Datei und ersetzt ganzen Inhalt; $ref: nennt einen SchemaLibrary-Eintrag über seine Identität und komponiert an jedem Knoten. Ein $import:-Wert, der eine Bibliotheksidentität oder einen Registry-Host trägt, wird mit einem Hinweis auf $ref: abgelehnt. Siehe cross-document-ref.md.

Aggrega-Erweiterungsnamensraum — x-aggrega-*

Die kompakte Form erkennt jedes Schlüsselwort mit dem Präfix x-aggrega- als Aggrega-spezifische Erweiterung. Der Namensraum ist offen: Neue Annotationen gelangen ohne Vokabularänderungen pro Schlüsselwort in den Katalog. Autoren, die x-aggrega-selector, x-aggrega-narrowed-from oder künftige Annotationen schreiben, bringen ihren Inhalt im richtigen Bereich des aufgelösten JSON Schema unter, ohne Ablehnung zur Kompilierzeit.

Das Namensraum-Präfix ist wichtig: Ein Tippfehler wie x-agrega-source (ein g fehlt) wird NICHT als Erweiterungsschlüsselwort erkannt und würde von der Semantik geschlossener Objekte in Bereichen in inferierter Form abgelehnt. Der Präfixbereich wirkt als Netz zur Erkennung von Tippfehlern für die Annotationsoberfläche des Katalogs.

Bestimmte x-aggrega-*-Annotationen gibt der Compiler an bekannten Stellen der Pipeline aus:

  • x-aggrega-selector: — ausgegeben von der Synthese von usesSchema: und featuresSchema:, um die Selektor-Zeichenkette zu tragen, die kompatible Provider-Components auswählt.
  • x-aggrega-sensitive: — ausgegeben von einem Blatt, das sensitive: true deklariert. Siehe Ein Blatt als sensibel deklarieren oben.

Katalogautoren, die eigene Erweiterungsschlüsselwörter schreiben, verwenden denselben Namensraum; nachgelagerte Werkzeuge, die das kompilierte JSON Schema konsumieren, lesen x-aggrega-*-Schlüssel, ohne mit dem eigenen Schlüsselwortraum von JSON Schema zu kollidieren.

Ausgearbeitetes Beispiel — MariaDB-Component-Schema

Ein repräsentatives Component-Schema in kompakter Form für einen MariaDB-Datenspeicher, das durchgehend die inferierte Form, gemischte Blatteinschränkungen, Referenzen, bedingte Form und ein ausgearbeitetes oneOf für den Authentifizierungsblock zeigt:

spec:
schema:
values:
architecture:
type: string
enum: [standalone, replication]
default: standalone
description: |
Topology mode. `standalone` runs a single primary; `replication` runs a primary
plus N secondary replicas governed by the secondary block.
primary:
replicaCount: { type: integer, min: 1, max: 9, default: 1 }
resources: { $ref: "#/$defs/PodResources" }
persistence: { $ref: "#/$defs/PersistenceSpec" }
secondary:
when: '{{ eq $.architecture "replication" }}'
properties:
replicaCount: { type: integer, min: 2, max: 8, default: 2 }
resources: { $ref: "#/$defs/PodResources" }
persistence: { $ref: "#/$defs/PersistenceSpec" }
auth:
oneOf:
- existingSecret: { type: string, required: true }
- rootPassword: { type: string, sensitive: true, required: true }
username: { type: string, default: app_user }
password: { type: string, sensitive: true, required: true }
database: { type: string, pattern: "^[a-zA-Z][a-zA-Z0-9_]*$", required: true }
metrics:
enabled: { type: boolean, default: false }
serviceMonitor:
enabled: { type: boolean, default: false }
namespace: { type: string }
labels: { type: object, valuesType: string }
$defs:
PodResources:
requests:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
limits:
cpu: { type: string, pattern: "^[0-9]+(m|\\.[0-9]+)?$" }
memory: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi)$" }
PersistenceSpec:
size: { type: string, pattern: "^[1-9][0-9]*(Mi|Gi|Ti)$", required: true }
storageClass: { type: string }

Als JSON-Schema-YAML geschrieben, schreibt derselbe Vertrag für jedes Objekt type: object, properties: und additionalProperties: false aus und führt jedes Pflichtfeld erneut im required: seines übergeordneten Elements auf, sodass er erheblich länger wird. Der Gewinn an Kompaktheit summiert sich bei größeren Component-Verträgen und ist bedeutend genug, um die kompakte Form zur standardmäßigen Oberfläche zum Verfassen von schema:, parameters: und SchemaLibrary-Einträgen zu machen.

Querverweise

  • Zur Semantik der Auflösung dokumentübergreifender $ref: (die required:-Syntax neben einer dokumentübergreifenden Referenz; Kettenerweiterung von Bibliothek zu Bibliothek; Konsument schränkt Bibliothek ein): cross-document-ref.md.
  • Zur Grammatik für das Verfassen des assertions:-Blocks (feldübergreifende Regeln, die validate: in kompakter Form nicht ausdrücken kann): templates/assertions-block.md.
  • Zur Menge der Datensäulen, die die Schemas in kompakter Form beherbergen (values:, infra:, provides:, uses:, features:, locals:, parameters:): data-pillars.md.
  • Zu den Erweiterungsregeln der OCI-URI-Kurzschreibweise (Standarddomäne, Registry-Segment, Versions-Fallback, Herausgebererweiterung): uri-grammar.md.
  • Zum Verfassen der SchemaLibrary-Entität (wo im Katalog die per $ref: referenzierbaren Schemas liegen): ../entities/schemalibrary.md.