Validierungsoberfläche
Aggrega validiert verfassten Inhalt über vier unterschiedliche Schema-Ebenen hinweg. Jede Ebene deckt einen anderen Bereich ab, läuft an einer anderen Stelle der Kompilierungspipeline und erzeugt Fehler in einer anderen Form. Autoren, die auf einen Validierungsfehler stoßen, profitieren davon zu wissen, welche Ebene die Eingabe abgelehnt hat — dasselbe Feld kann von mehr als einer Ebene geregelt werden, und die Ebene, die ausgelöst hat, bestimmt, was wo zu korrigieren ist.
Diese Seite dokumentiert die vier Ebenen, ihre Platzierung in der Pipeline, die Konvention zur Fehlerform, der jede Ebene folgt, und wie Ebenen zusammenwirken, wenn mehr als eine auf dasselbe Feld zutrifft.
Die vier Ebenen
Ebene 1 — Hülle nach JSON Schema
Geltungsbereich. Die strukturelle Form jeder Katalog-YAML: apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, der spec:-Block auf oberster Ebene und die Pflichtfelder pro Entität, die das Schema deklariert. Jede Entitätsart (Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) hat ihr eigenes JSON Schema, dokumentiert in der Schemareferenz. Auch Workload hat dort eines, und es ist die einzige Art dieser Menge, die ein Autor innerhalb einer anderen Entität schreibt — im workload:-Block eines Recipe oder eines FeatureRecipe oder in einem Eintrag einer WorkloadLibrary — statt als eigene Katalogdatei; dieselbe Hüllenprüfung gilt für sie, wo immer sie geschrieben wird, und aggrega validate akzeptiert eine Workload-Datei direkt als Ziel mit einer einzelnen Entität.
Ausführung der Validierung. Bei der Auflösung (Resolver / Laden), pro Datei. Jedes Dokument wird beim Laden gegen das JSON Schema seiner Art geprüft; ein Schlüssel außerhalb der Felder, die das Schema deklariert, wird dort abgelehnt, bevor eine weitere Validierung läuft.
Fehlerform. Eine Abweichung vom Schema wird als Fehler der Dokumenthülle gemeldet. Ihr Kopf trägt die Kategorie des fehlerhaften Dokuments — [CATALOG_ERROR E0215] für eine Katalogentität, [DEVELOPER_ERROR E0215] für ein Aggregate, [OPS_ERROR E0215] für ein Release — und die Meldung nennt die Art, die Datei, Zeile und Spalte, den Feldpfad und die verletzte Einschränkung:
[CATALOG_ERROR E0215] <path> document envelope validation failed (Recipe, at <path>); 11:3: spec.foo: unexpected property: "foo". correct the document to match its kind's schemaFehlende Pflichtfelder und Typabweichungen erscheinen in derselben Form — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".
Ebene 2 — Säulenschemas (schema: / featuresSchema / usesSchema)
Geltungsbereich. Die Datensäulen, die eine Entität trägt — values, infra, parameters, dazu der Anhangsblock features:, dessen Slots featuresSchema deklariert, und der Block uses:, den usesSchema regelt. Entitäten der Domäne 2 (Component, Feature) betten Deklarationen in JSON Schema 2020-12 in ihre YAML-Hülle ein (spec.schema inline — in kompakter oder vollständiger Form — oder ein $ref: auf einen gemeinsamen Eintrag einer SchemaLibrary); Entitäten der Domäne 3 (Recipe, FeatureRecipe) verwenden die aufgelösten Schemas während ihres eigenen Validierungsdurchlaufs.
Ausführung der Validierung. Bei der Auflösung, nachdem die Hülle nach JSON Schema bestanden ist. Der Compiler setzt das verfasste schema: der Entität mit automatisch erzeugten Basen zusammen, die aus den Deklarationen usesSchema und featuresSchema abgeleitet sind; das zusammengesetzte Schema validiert die vom Entwickler gelieferten Blöcke values: / infra: / features: / uses: auf jeder Komponenteninstanz im Aggregate.
Fehlerform. Verletzungen von Einschränkungen erscheinen als Meldungen, die die Entität, den Pfad innerhalb der Säule und die Regel nennen, die den Wert abgelehnt hat — zum Beispiel ein Entwickler, der einen Port auf 80 setzt, während eine Schemaregel >=1024 verlangt.
Ein erneut deklarierter Eintrag in usesSchema oder featuresSchema erzeugt keinen Kompositionsfehler. Diese beiden Oberflächen überlagern sich nach Namen: Der Eintrag eines Kindes ersetzt den der Basis vollständig, Schema und Selektor zusammen, sodass es keinen Konflikt zwischen einem Eintrag der Basis und einem des Kindes zu melden gibt.
Ebene 3 — Provider-Fähigkeit für den synthetisierten Modus
Geltungsbereich. Geregelt durch die Fähigkeitsprüfung des gebundenen Provider für den synthetisierten Modus:
- Die Unterstützung des synthetisierten Modus (
workload:) hängt von der Fähigkeit des gebundenen Provider ab, nicht vom Vorhandensein vonworkloadSchema: Einworkload:-Recipe, das an einen Provider gebunden ist, der nicht synthetisieren kann, wird hier abgelehnt. Der Katalog der Standardbibliothek deklariertworkloadSchemaper Konvention auf synthesefähigen Providern — imspec.provider.workloadSchemades Provider-Rendering-Plugin — als den dokumentierten Übersetzungsvertrag. DieserworkloadSchema-Inhalt wird seinerseits beim Laden des Plugin zu JSON Schema 2020-12 kompiliert, eine strukturelle Annahmeprüfung, die ein fehlerhaftes Schema beim Laden statt beim Rendern ablehnt.
Ausführung der Validierung. Beim Basis-Rendering, nachdem das eigene valuesMapping des Recipe aufgelöst ist. Ebene 3 macht die Zuteilung im synthetisierten Modus von der Fähigkeit des Provider abhängig.
Fehlerform. Eine Ablehnung mangels Fähigkeit wird der Domäne des Katalog-Authoring zugeschrieben, daher beginnt ihr Bericht mit einem Kopf in eckigen Klammern, der diese Kategorie und die fehlerhafte Instanz trägt. Die Meldung beginnt mit dem festen Satz, der die Bedingung nennt, und nennt dann den Knoten, den Provider und die Arten, die dieser Provider unterstützt:
[CATALOG_ERROR] instance <node-id>: provider does not support the node's input kind (node "<node-id>"). provider "<provider-name>" does not support synthesized recipes (this provider supports: <kinds>); declare one of the supported input kinds, or target a provider that supports synthesizedDer Kopf [CATALOG_ERROR] zeigt an, dass die Katalogentität fehlerhaft ist, nicht das Aggregate des Entwicklers. In einem Terminal trägt der Kopf außerdem den Kurzcode der Bedingung — E0265 für diese, den die Tabelle aller Bedingungen auflöst — und die Meldung rückt in eine eigene eingerückte Zeile; die einzeilige Form oben ist diejenige, die ein Log erreicht. Der einleitende Satz ist pro Bedingung fest, daher ist er der Teil, auf den Sie abgleichen, wenn Sie von Text ausgehen; alles danach variiert mit dem fehlerhaften Knoten.
Eine verwandte Schutzvorkehrung sichert die Zuteilung an Provider selbst: Wenn mehr als ein Provider-Rendering-Plugin dasselbe Ziel bedient, löst der Workspace die Mehrdeutigkeit über eine Provider-Bindung in .aggrega-config.yaml auf, die bei aggrega pull gewählt und in der Lock-Datei festgehalten wird. Ohne Bindung und mit genau einem Kandidaten-Plugin wird dieser Kandidat verwendet; ohne Bindung und mit mehr als einem Kandidaten hält der Build deutlich an und nennt die Kandidaten-Plugins. Mehrdeutigkeit wird pro Workspace am Ort der Verwendung aufgelöst, nicht durch eine katalogweite Eindeutigkeitsregel.
Workload-Inhaltsvalidierung pro Provider. Das
spec.provider.workloadSchemaeines Provider-Rendering-Plugin dokumentiert, wie der Provider eine Workload übersetzt, und kennzeichnet den Provider als fähig, eine zu synthetisieren; es validiert nichts. Jeder Workload-Inhalt wird gegen das Workload-Schema der Plattform validiert, unabhängig vom Provider.
Ebene 4 — Wertvalidierung von Annotationsbindungen
Geltungsbereich. Annotationswerte, die auf Release-Boundaries / Boundary-Komponenten oder auf Subsystemen / Komponenteninstanzen des Aggregate verfasst sind, wenn eine Manifest-Bindung unter mappings.features.annotations.<key> eine Weiterleitung über Listen punktierter Pfade in maps.infra und/oder maps.values deklariert. Jeder deklarierte Pfad navigiert das spec.schema.<pillar> des Ziel-Feature bis zu einer Blatteigenschaft; der Beitrag des Annotationswerts an diesem Blatt wird gegen den deklarierten Typ des Feature-Schemas validiert. Die Validierung erfolgt über die eigene Deklaration in JSON Schema 2020-12 des Feature — Bindungen deklarieren nur die Weiterleitung, keine Validierungsfragmente.
Ausführung der Validierung. Die Unterphase der Annotationsexpansion innerhalb der Auflösung, nach der Validierung der Bindungsziele des Manifest (der Prüfung beim Laden des Katalogs, die bestätigt, dass jeder deklarierte Pfad im referenzierten Feature-Schema existiert) und neben der Schemavalidierung der Ebene 2 für explizite Anhänge. Für jede effektive Annotation pro Komponente: Der Wert wird als Skalar, als strukturierte Map oder als explizites null geparst; er wird pro Unterschlüssel durch die nach Säulen gruppierte maps-Deklaration der Bindung weitergeleitet, mit Durchsetzung von Seite gegenüber Säule (die Aggregate-Seite löst maps.values aus; die Release-Seite löst maps.infra aus); der Laufzeitwert pro Blatt wird gegen den deklarierten Typ des Feature-Schemas an der weitergeleiteten Säule validiert. Mehrere Unterschlüsselfehler werden gesammelt und alle ausgegeben, bevor angehalten wird.
Fehlerform. Schemavalidierungsfehler auf dieser Ebene folgen der Form der Ebene 2 — Entität, Pfad (Annotationsschlüssel plus Weiterleitung des Unterschlüssels), Detail der Einschränkung. Verletzungen der Aufteilung von Seite gegenüber Säule und Fehler mehrdeutiger Weiterleitung werden dem Dokument zugeschrieben, in dem der Annotationswert verfasst wurde, sodass ein Fehler in einem Aggregate einen Kopf [DEVELOPER_ERROR] und einer in einem Release einen Kopf [OPS_ERROR] öffnet, und beide nennen den Annotationsschlüssel, die weitergeleitete Säule, die verfassende Seite und den Quellort.
Eine Konvention zur Fehlerformatierung über alle Ebenen
Die vier Ebenen teilen eine beobachtbare Konvention: Jeder Aggrega zuzuschreibende Validierungsfehler trägt eine Form aus Pfad und Begründung, die das fehlerhafte Feld und die Einschränkung nennt, die es abgelehnt hat.
- Fehler der Ebene 1 (Hülle) und der Ebene 2 (Säulenschemas) beginnen mit demselben Kopf in eckigen Klammern — der Kategorie des fehlerhaften Dokuments und dem Kurzcode der Bedingung, etwa
[CATALOG_ERROR E0215]für eine Hüllenabweichung in einer Katalogentität und[DEVELOPER_ERROR E0168]für einen Aggregate-Wert, den ein Säulenschema ablehnt — gefolgt vom Feldpfad und der verletzten Schemaregel. - Fehler der Ebene 3 (Provider-Quelle / Workload) sind per Definition Katalogentitäten zuzuschreiben — das Paar Recipe + Provider hat das Schema verfasst, das die Eingabe des Entwicklers abgelehnt hat. Sie werden der Domäne des Katalog-Authoring zugeschrieben, und die Zuschreibung erreicht Sie im Kopf in eckigen Klammern der Diagnose statt als ein in die Meldung getipptes Wort: Ein anhaltender Bericht beginnt mit
[CATALOG_ERROR E0nnn], wobei die Kategorie die Domäne und der Kurzcode die Bedingung nennt. Gleichen Sie auf den Kurzcode ab, der nach seiner Vergabe fest ist. - Fehler der Ebene 4 (Wertvalidierung von Annotationsbindungen) folgen der Form der Ebene 2 — das validierende Feature-Schema befindet sich im
spec.schemades referenzierten Feature, und Laufzeitwerte fließen über diemaps-Weiterleitung der Manifest-Bindung in dieses Schema zur Typprüfung pro Blatt.
Für das vollständige Inventar der Sentinels mit Aggrega-Präfix und der Oberflächen, die sie erzeugen, siehe errors/error-translation.md. Für den Katalog pro Fehler (die Formregeln für Recipe bei [CATALOG_ERROR], Bedingung für Bedingung), siehe errors/fatal-halts.md.
Zusammenspiel der Ebenen, wenn sich Felder überschneiden
Dasselbe verfasste Feld kann von mehr als einer Ebene geregelt werden. Das containers.<name>.ports.<port> einer Workload wird von Ebene 1 als Teil der strukturellen Form des Workload-Schemas geprüft; Ebene 2 erreicht es nicht, da Workload-Inhalt eine Recipe-interne Struktur und keine Component-Säule ist; und das workloadSchema eines Provider prüft nichts — daher gehört eine Einschränkung wie die Ablehnung eines Ports unter 1024 in das Schema der Component oder in eine Assertion, wo die auslösende Ebene sie nennt.
Übersicht der Platzierung in der Pipeline
| Ebene | Geltungsbereich | Läuft bei | Fehlerpräfix |
|---|---|---|---|
| 1 — JSON-Schema-Hülle | Strukturelle Form (apiVersion, kind, metadata, spec auf oberster Ebene) | Auflösung (Laden) | die Kategorie des Dokuments mit E0215 — [CATALOG_ERROR E0215] für eine Katalogentität |
2 — Säulenschemas (schema: / featuresSchema / usesSchema) | Datenvalidierung pro Säule (values, infra, secrets, uses) | Auflösung (nach der Hülle) | die Kategorie des verfassenden Dokuments mit dem Kurzcode der Bedingung — [DEVELOPER_ERROR E0168] für einen Aggregate-Wert |
| 3 — Provider-Fähigkeitsprüfung | Unterstützung des synthetisierten Modus (Provider-Fähigkeit) | Basis-Rendering | [CATALOG_ERROR] |
| 4 — Wertvalidierung von Annotationsbindungen | Beiträge von Annotationswerten, die über die maps-Pfade der Manifest-Bindung in das spec.schema des Ziel-Feature weitergeleitet werden | Die Unterphase der Annotationsexpansion innerhalb der Auflösung, neben Ebene 2 | Schemavalidierungsfehler; Oberflächen für Seite gegenüber Säule / mehrdeutige Weiterleitung öffnen die eigene Domäne des verfassenden Dokuments — [DEVELOPER_ERROR] aus einem Aggregate, [OPS_ERROR] aus einem Release |
Querverweise
errors/error-translation.md— Inventar der Sentinels mit Aggrega-Präfix und der Oberflächen, die sie erzeugen.errors/fatal-halts.md— Katalog pro Fehler mit jedem fatalen Abbruch, den der Compiler ausgibt.vocabulary/data-pillars.md— die Datensäulen (values,infra,parameters,locals,features:,uses:undprovides), die Ebene 2 validiert.entities/component.md— Authoring-Oberfläche der Component fürschema:/featuresSchema/usesSchema.entities/plugin.md— Authoring-Oberfläche des Provider-Rendering-Plugin fürspec.provider.workloadSchema.entities/manifest.md— Bindungsoberflächefeatures.annotationsdes Manifest (Ebene 4).providers/well-known-annotations.md— Parsen von Annotationswerten, Weiterleitung von Unterschlüsseln strukturierter Werte, Opt-out per null pro Unterschlüssel und seitenübergreifende Komposition, die Ebene 4 validiert.