Surface de validation
Aggrega valide le contenu rédigé à travers quatre couches de schéma distinctes. Chaque couche couvre une portée différente, s’exécute à un point différent du pipeline de compilation et produit des erreurs de forme différente. Les auteurs qui rencontrent une erreur de validation ont intérêt à savoir quelle couche a rejeté l’entrée — le même champ peut être régi par plusieurs couches, et la couche qui s’est déclenchée détermine quoi corriger et où.
Cette page documente les quatre couches, leur place dans le pipeline, la convention de forme d’erreur que suit chaque couche, et la manière dont les couches interagissent lorsque plusieurs s’appliquent au même champ.
Les quatre couches
Couche 1 — Enveloppe JSON Schema
Portée. La forme structurelle de chaque YAML du catalogue : apiVersion, kind, metadata.{name, version, description, maintainers, license, ...}, le bloc spec: de premier niveau et les champs obligatoires par entité que le schéma déclare. Chaque type d’entité (Aggregate, Component, Feature, Recipe, FeatureRecipe, Manifest, Plugin, Release, SchemaLibrary, MappingLibrary, WorkloadLibrary, ArtifactLibrary) possède son propre JSON Schema, documenté dans la Référence des schémas. Workload y en possède un aussi, et c’est le seul type de cet ensemble qu’un auteur écrit à l’intérieur d’une autre entité — le bloc workload: d’une Recipe ou d’une FeatureRecipe, ou une entrée d’une WorkloadLibrary — plutôt que comme un fichier de catalogue à part entière ; le même contrôle d’enveloppe le régit partout où il est écrit, et aggrega validate accepte directement un fichier Workload comme cible à entité unique.
Exécution de la validation. À la résolution (résolveur / chargement), par fichier. Chaque document est vérifié par rapport au JSON Schema de son type lors de son chargement ; une clé en dehors des champs que le schéma déclare y est refusée, avant que toute autre validation ne s’exécute.
Forme de l’erreur. Une non-conformité au schéma est signalée comme un échec de l’enveloppe du document. Son en-tête porte la catégorie du document fautif — [CATALOG_ERROR E0215] pour une entité du catalogue, [DEVELOPER_ERROR E0215] pour un Aggregate, [OPS_ERROR E0215] pour une Release — et le message nomme le type, le fichier, la ligne et la colonne, le chemin du champ et la contrainte violée :
[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 schemaLes omissions de champs obligatoires et les incompatibilités de type apparaissent sous la même forme — spec.capability: missing required property: capability, metadata.version: type: 1 has type "integer", want "string".
Couche 2 — Schémas des piliers (schema: / featuresSchema / usesSchema)
Portée. Les piliers de données que porte une entité — values, infra, parameters, ainsi que le bloc de rattachement features: dont featuresSchema déclare les slots et le bloc uses: régi par usesSchema. Les entités du domaine 2 (Component, Feature) intègrent des déclarations JSON Schema 2020-12 dans leur enveloppe YAML (spec.schema en ligne — sous forme compacte ou complète — ou un $ref: vers une entrée partagée d’une SchemaLibrary) ; les entités du domaine 3 (Recipe, FeatureRecipe) consomment les schémas résolus pendant leur propre passe de validation.
Exécution de la validation. À la résolution, une fois l’enveloppe JSON Schema validée. Le compilateur compose le schema: rédigé de l’entité avec des bases générées automatiquement, dérivées des déclarations usesSchema et featuresSchema ; le schéma composé valide les blocs values: / infra: / features: / uses: fournis par le développeur sur chaque instance de composant de l’Aggregate.
Forme de l’erreur. Les violations de contraintes apparaissent sous forme de messages qui nomment l’entité, le chemin à l’intérieur du pilier et la règle qui a rejeté la valeur — par exemple un développeur qui fixe un port à 80 face à une règle du schéma exigeant >=1024.
Une entrée usesSchema ou featuresSchema redéclarée ne produit aucun échec de composition. Ces deux surfaces se superposent par nom : l’entrée d’un enfant remplace entièrement celle de la base, schéma et sélecteur ensemble, de sorte qu’il n’y a aucun conflit à signaler entre une entrée de la base et une entrée de l’enfant.
Couche 3 — Capacité du Provider en mode synthétisé
Portée. Régie par le contrôle de capacité en mode synthétisé du fournisseur lié :
- La prise en charge du mode synthétisé (
workload:) dépend de la capacité du fournisseur lié, et non de la présence deworkloadSchema: une Recipeworkload:liée à un fournisseur qui ne peut pas synthétiser est rejetée ici. Le catalogue de la bibliothèque standard déclareworkloadSchemasur les fournisseurs capables de synthèse par convention — dans lespec.provider.workloadSchemadu Plugin de rendu de fournisseur — comme contrat de traduction documenté. Ce corpsworkloadSchemaest lui-même compilé en JSON Schema 2020-12 lors du chargement du Plugin, un contrôle structurel d’acceptation qui rejette un schéma mal formé au chargement plutôt qu’au rendu.
Exécution de la validation. Au rendu de base, une fois le valuesMapping propre de la Recipe résolu. La couche 3 subordonne la répartition en mode synthétisé à la capacité du fournisseur.
Forme de l’erreur. Un refus de capacité est attribué au domaine de rédaction du catalogue, de sorte que son rapport s’ouvre sur un en-tête entre crochets portant cette catégorie et l’instance en faute. Le message s’ouvre sur la phrase fixe qui énonce la condition, puis nomme le nœud, le fournisseur et les types que ce fournisseur prend en charge :
[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 synthesizedL’en-tête [CATALOG_ERROR] signale que l’entité du catalogue est fautive, et non l’Aggregate du développeur. Dans un terminal, l’en-tête porte aussi le code court de la condition — E0265 pour celle-ci, que la table de toutes les conditions résout — et le message passe sur sa propre ligne en retrait ; la forme sur une ligne ci-dessus est celle qui parvient à un journal. La phrase d’ouverture est fixe pour chaque condition, c’est donc la partie sur laquelle faire correspondre lorsque vous travaillez à partir du texte ; tout ce qui suit varie selon le nœud fautif.
Un garde-fou associé protège la répartition vers les fournisseurs elle-même : lorsque plus d’un Plugin de rendu de fournisseur sert la même cible, l’espace de travail lève l’ambiguïté au moyen d’une liaison de fournisseur dans .aggrega-config.yaml, choisie lors de aggrega pull et enregistrée dans le fichier de verrouillage. Sans liaison et avec exactement un Plugin candidat, ce candidat est utilisé ; sans liaison et avec plus d’un candidat, le build s’arrête explicitement en nommant les plugins candidats. L’ambiguïté est levée par espace de travail, au point d’utilisation, et non par une règle d’unicité à l’échelle du catalogue.
Validation du contenu de Workload par fournisseur. Le
spec.provider.workloadSchemad’un Plugin de rendu de fournisseur documente la manière dont le fournisseur traduit un Workload et marque le fournisseur comme capable d’en synthétiser un ; il ne valide rien. Chaque corps de Workload est validé par rapport au schéma Workload de la plateforme, quel que soit le fournisseur.
Couche 4 — Validation des valeurs des liaisons d’annotation
Portée. Les valeurs d’annotation rédigées sur les frontières de la Release / composants de frontière ou sur les sous-systèmes / instances de composant de l’Aggregate, lorsqu’une liaison du Manifest sous mappings.features.annotations.<key> déclare un routage par des listes de chemins pointés maps.infra et/ou maps.values. Chaque chemin déclaré parcourt le spec.schema.<pillar> de la Feature cible jusqu’à une propriété feuille ; la contribution de la valeur d’annotation à cette feuille est validée par rapport au type déclaré par le schéma de la Feature. La validation passe par la propre déclaration JSON Schema 2020-12 de la Feature — les liaisons ne déclarent que le routage, pas des fragments de validation.
Exécution de la validation. La sous-phase d’expansion des annotations de la résolution, après la validation des cibles de liaison du Manifest (le contrôle au chargement du catalogue qui confirme que chaque chemin déclaré existe dans le schéma de la Feature référencée) et parallèlement à la validation de schéma de la couche 2 sur les rattachements explicites. Pour chaque annotation effective par composant : analyser la valeur comme un scalaire, une map structurée ou un null explicite ; la router par sous-clé à travers la déclaration maps de la liaison, groupée par pilier, avec l’application côté-contre-pilier (le côté Aggregate déclenche maps.values ; le côté Release déclenche maps.infra) ; valider la valeur d’exécution par feuille par rapport au type déclaré par le schéma de la Feature au pilier routé. Plusieurs erreurs de sous-clé sont collectées et toutes émises avant l’arrêt.
Forme de l’erreur. Les erreurs de validation de schéma à cette couche suivent la forme de la couche 2 — entité, chemin (clé d’annotation plus routage de la sous-clé), détail de la contrainte. Les violations de la partition côté-contre-pilier et les échecs de routage ambigu sont attribués au document dans lequel la valeur d’annotation a été rédigée, de sorte qu’une faute portée par un Aggregate ouvre un en-tête [DEVELOPER_ERROR] et une faute portée par une Release ouvre un en-tête [OPS_ERROR], et toutes deux nomment la clé d’annotation, le pilier routé, le côté de rédaction et l’emplacement source.
Une seule convention de formatage des erreurs pour toutes les couches
Les quatre couches partagent une convention observable : chaque échec de validation attribuable à Aggrega porte une forme chemin-plus-justification qui nomme le champ fautif et la contrainte qui l’a rejeté.
- Les erreurs de la couche 1 (enveloppe) et de la couche 2 (schémas des piliers) s’ouvrent sur le même en-tête entre crochets — la catégorie du document fautif et le code court de la condition, comme
[CATALOG_ERROR E0215]pour une non-conformité de l’enveloppe dans une entité du catalogue et[DEVELOPER_ERROR E0168]pour une valeur d’un Aggregate qu’un schéma de pilier refuse — suivi du chemin du champ et de la règle du schéma violée. - Les erreurs de la couche 3 (source Provider / Workload) sont par définition attribuables aux entités du catalogue — la paire Recipe + Provider a rédigé le schéma qui a rejeté l’entrée du développeur. Elles sont attribuées au domaine de rédaction du catalogue, et l’attribution vous parvient dans l’en-tête entre crochets du diagnostic plutôt que sous forme d’un mot tapé dans le message : un rapport bloquant s’ouvre sur
[CATALOG_ERROR E0nnn], où la catégorie nomme le domaine et le code court nomme la condition. Faites correspondre sur le code court, qui est fixe une fois émis. - Les erreurs de la couche 4 (validation des valeurs des liaisons d’annotation) suivent la forme de la couche 2 — le schéma de Feature validant réside dans le
spec.schemade la Feature référencée, et les valeurs d’exécution passent par le routagemapsde la liaison du Manifest dans ce schéma pour la vérification de type par feuille.
Pour l’inventaire complet des sentinelles préfixées Aggrega et des surfaces qui les produisent, voir errors/error-translation.md. Pour le catalogue par erreur (les règles de forme de Recipe [CATALOG_ERROR], condition par condition), voir errors/fatal-halts.md.
Interaction des couches lorsque des champs se chevauchent
Le même champ rédigé peut être régi par plus d’une couche. Le containers.<name>.ports.<port> d’un Workload est vérifié par la couche 1 comme partie de la forme structurelle du schéma Workload ; la couche 2 ne l’atteint pas, le contenu d’un Workload étant une structure interne à la Recipe plutôt qu’un pilier de Component ; et le workloadSchema d’un fournisseur ne vérifie rien — ainsi une contrainte comme le refus d’un port inférieur à 1024 relève du schéma du Component ou d’une assertion, là où la couche qui se déclenche la nomme.
Récapitulatif de la place dans le pipeline
| Couche | Portée | S’exécute à | Préfixe d’erreur |
|---|---|---|---|
| 1 — Enveloppe JSON Schema | Forme structurelle (apiVersion, kind, metadata, spec de premier niveau) | Résolution (chargement) | la catégorie du document avec E0215 — [CATALOG_ERROR E0215] pour une entité du catalogue |
2 — Schémas des piliers (schema: / featuresSchema / usesSchema) | Validation des données par pilier (values, infra, secrets, uses) | Résolution (après l’enveloppe) | la catégorie du document de rédaction avec le code court de la condition — [DEVELOPER_ERROR E0168] pour une valeur d’un Aggregate |
| 3 — Contrôle de capacité du Provider | Prise en charge du mode synthétisé (capacité du fournisseur) | Rendu de base | [CATALOG_ERROR] |
| 4 — Validation des valeurs des liaisons d’annotation | Contributions des valeurs d’annotation routées dans le spec.schema de la Feature cible via les chemins maps de la liaison du Manifest | La sous-phase d’expansion des annotations de la résolution, parallèlement à la couche 2 | erreur de validation de schéma ; les surfaces côté-contre-pilier / de routage ambigu ouvrent le domaine propre du document de rédaction — [DEVELOPER_ERROR] depuis un Aggregate, [OPS_ERROR] depuis une Release |
Références croisées
errors/error-translation.md— inventaire des sentinelles préfixées Aggrega et des surfaces qui les produisent.errors/fatal-halts.md— catalogue par erreur de chaque arrêt fatal émis par le compilateur.vocabulary/data-pillars.md— les piliers de données (values,infra,parameters,locals,features:,uses:etprovides) que valide la couche 2.entities/component.md— surface de rédaction du Component pourschema:/featuresSchema/usesSchema.entities/plugin.md— surface de rédaction du Plugin de rendu de fournisseur pourspec.provider.workloadSchema.entities/manifest.md— surface de liaisonfeatures.annotationsdu Manifest (couche 4).providers/well-known-annotations.md— analyse des valeurs d’annotation, routage par sous-clé des valeurs structurées, exclusion par null par sous-clé et composition entre les côtés que valide la couche 4.