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

SchemaLibrary

Une SchemaLibrary est une entité de catalogue qui contient des définitions JSON Schema 2020-12 réutilisables ainsi que des helpers paramétrés facultatifs. Les Components et les Features qui partagent des formes de schéma — URL, durées, structures de sondes courantes, limites de ressources récurrentes — déclarent ces formes une seule fois dans une bibliothèque et y font référence via des URI $ref canoniques. L’entité bibliothèque est de niveau 3 : facultative, pour les catalogues qui ont besoin d’une réutilisation de schémas inter-Component. Les catalogues sans contenu de schéma répété sont livrés sans aucune SchemaLibrary.

Le rôle de la SchemaLibrary

Les architectes de plateforme rédigent des SchemaLibraries pour centraliser les formes de schéma qui reviennent dans tout le catalogue. Une bibliothèque n’est pas une brique déployable ; c’est un espace de noms de définitions. Les auteurs de Component / Feature font référence aux entrées de bibliothèque par leur URI $ref canonique, typée une fois et validée partout où la référence se résout.

La séparation entre « bibliothèque » et « consommateur » est intentionnelle. Les Components déclarent le contrat qu’une instance remplit (ses values, infra et provides, ses sockets, ses slots d’identifiants). Les Features encodent des rattachements comportementaux. Les SchemaLibraries n’encodent que du contenu de schéma — les règles structurelles qu’une valeur doit satisfaire. Garder les trois rôles distincts permet à chaque type d’entité d’évoluer à son propre rythme ; les auteurs qui n’ont pas besoin de définitions de schéma partagées ne rencontrent jamais l’entité bibliothèque.

Enveloppe de l’entité

Une entité SchemaLibrary porte l’enveloppe standard du catalogue. apiVersion: aggrega.ai/v1beta1 et kind: SchemaLibrary marquent le type d’entité ; metadata.name est un identifiant en PascalCase ; metadata.version suit strictement le versionnage sémantique. Le contenu de la bibliothèque se trouve sous spec : spec.schemas est obligatoire (la bibliothèque doit déclarer au moins une entrée), et spec.templates est facultatif (présent uniquement quand la bibliothèque utilise des helpers paramétrés).

apiVersion: aggrega.ai/v1beta1
kind: SchemaLibrary
metadata:
name: WebPrimitives
version: 1.0.0
spec:
schemas:
URL:
type: string
pattern: "^https?://"
HTTPMethod:
type: string
enum: [GET, POST, PUT, PATCH, DELETE]

Rédiger des entrées de schéma

Les entrées de schéma se rédigent sous l’une de trois formes. La forme compacte est la surface par défaut pour les formes courtes et courantes — type, pattern, enum, min, max et contraintes similaires sur une ligne. Le YAML JSON Schema 2020-12 est l’option de rédaction de même rang pour les entrées qui ont besoin de toute la surface de JSON Schema (mots-clés de composition, forme conditionnelle, $defs complexes). Mélanger les deux au sein d’une même entrée est pris en charge via le dispatch par nœud selon la forme du contenu du compilateur de forme compacte ; la porte de sortie $jsonschema: intègre du contenu JSON Schema complet à n’importe quel nœud lorsque la forme compacte ne peut pas exprimer l’intention.

Un format dans une entrée vérifie ce qu’il vérifie dans n’importe quel schéma : il nomme l’un de email, uri, hostname, ipv4, ipv6, uuid, date-time et date, et une valeur qu’un consommateur fournit pour le champ est refusée à moins qu’elle n’ait ce format — voir vocabulary/compact-form-authoring.md. Une entrée qui nomme tout autre format — password compris — est refusée au chargement de la bibliothèque, de sorte qu’un aggrega validate de tout le catalogue la refuse, que quelque chose y fasse déjà référence ou non, en nommant la bibliothèque, l’entrée et le nom et en listant ceux qui sont pris en charge, et un build ou un pull dont la Release atteint la bibliothèque s’arrête dessus. Une entrée qui fait référence à une autre bibliothèque est jugée là où un pilier d’un Component ou d’une Feature la consomme. Un champ qui porte des données secrètes déclare sensitive: true plutôt qu’un format.

Templates et $instantiate:

Les bibliothèques dont la structure répétée est importante déclarent des helpers paramétrés sous spec.templates. Un template porte une map $params: (déclarations de paramètres typés et nommés) ainsi qu’un corps (forme compacte ou contenu JSON Schema qui fait référence aux paramètres sous forme de jetons scalaires $<paramName>). Les entrées de schéma instancient des templates via des liaisons $instantiate: + $args: ; le moteur de substitution remplace les espaces réservés des paramètres par des valeurs scalaires littérales et produit le corps de l’entrée résolue.

spec:
schemas:
LivenessProbe:
$instantiate: ProbeTemplate
$args:
port: 8080
path: /healthz
ReadinessProbe:
$instantiate: ProbeTemplate
$args:
port: 8081
path: /ready
templates:
ProbeTemplate:
$params:
port:
type: integer
path:
type: string
type: object
properties:
port:
type: integer
const: $port
path:
type: string
const: $path

La substitution ne porte que sur des scalaires littéraux. Le moteur de substitution n’interprète pas la syntaxe des templates Go, n’évalue pas de conditions et n’exécute pas de boucles. Les auteurs qui ont besoin de helpers plus expressifs composent des Components ou des Features qui consomment les entrées de la bibliothèque avec leurs propres variations.

Conventions de nommage

Les noms de bibliothèque, les clés d’entrées de schéma et les noms de templates suivent le PascalCase. Le JSON Schema de l’enveloppe de l’entité impose la convention à trois endroits par des contraintes de motif :

  • metadata.name correspond à ^[A-Z][A-Za-z0-9]*$.
  • Les clés de la map spec.schemas correspondent au même motif via propertyNames.
  • Les clés de la map spec.templates correspondent au même motif via propertyNames.

Une SchemaLibrary dont une clé de spec.schemas ou de spec.templates n’est pas en PascalCase échoue à la validation de l’enveloppe au chargement du workspace. L’application au niveau de l’enveloppe est essentielle : les clés d’entrées de schéma apparaissent dans les URI $id canoniques (#/schemas/<name>) ; les noms de templates font référence à des URI canoniques au moment de l’instanciation. Intercepter les clés qui ne sont pas en PascalCase au chargement les empêche de se propager dans l’écosystème du catalogue.

Les noms de paramètres dans la map $params: d’un template sont locaux au template — ils n’apparaissent pas dans les URI $id canoniques et ne sont pas contraints par un motif au niveau de l’enveloppe. Les auteurs suivent la convention de nommage qui convient aux paramètres du template ; port, path, intervalSec et des noms de paramètres similaires en minuscules sont typiques.

L’uniformité de nommage aux niveaux bibliothèque, schéma et template rend les identifiants de référence faciles à parcourir : WebPrimitives#/schemas/URL se lit d’un coup d’œil.

Pour la sémantique de résolution de $ref: entre documents — comment $ref: se résout au-delà des limites des SchemaLibrary, la distinction de syntaxe required: pour les consommateurs porteurs de $ref:, l’expansion des chaînes de bibliothèque à bibliothèque et le comportement où le consommateur restreint la bibliothèque — voir vocabulary/cross-document-ref.md.

Faire référence aux entrées de bibliothèque

Les auteurs de Component / Feature font référence à une entrée de bibliothèque par son identité — la forme à nom nu <Library>#/schemas/<name> :

# Inside a Component schema:
spec:
schema:
values:
healthCheck:
$ref: "WebPrimitives#/schemas/URL"

Le nom de la bibliothèque se résout par rapport au catalogue résolu ; le fragment #/schemas/<name> sélectionne l’entrée. Une référence ne porte aucun hôte de registre ; un auteur peut indiquer une version minimale facultative sous la forme <Library>:<version>#/schemas/<name> (le séparateur de version est :, comme dans les mappages recipe/feature et l’épinglage du lockfile), mais la version résolue est fournie par le lockfile propre à chaque Release, qui épingle chaque bibliothèque consommée par nom + version + digest du contenu. Une référence qui porte un hôte de registre — une forme oci://<host>/… — est refusée à la compilation avec un diagnostic qui oriente l’auteur vers la forme d’identité, de sorte qu’un emplacement physique de registre n’entre jamais dans la source rédigée. L’endroit d’où les octets de la bibliothèque sont servis (un répertoire de catalogue local, le cache de contenu ou un registre distant) relève du résolveur, lié au moment de la résolution ; déplacer un registre est une modification de la configuration du résolveur, pas de la source.

Mots-clés JSON Schema interdits

Les mots-clés $dynamicAnchor et $dynamicRef de JSON Schema 2020-12 sont interdits dans les entrées de SchemaLibrary. Le parser de SchemaLibrary analyse à la fois les entrées de schéma et les corps de templates au chargement du workspace ; le linter de publication applique une garde redondante au moment de la publication ; le moteur d’instanciation réanalyse le corps résolu après la substitution des paramètres, de sorte qu’un template qui introduit en douce des mots-clés interdits via des valeurs de paramètres échoue quand même. Les trois analyses ferment ensemble la voie d’introduction statique ($dynamicAnchor littéral dans une entrée de schéma ou un corps de template), la voie d’introduction paramétrique (une valeur $args: contenant $dynamicRef) et la voie de contournement par des outils externes (la garde au moment de la publication intercepte tout ce qui a échappé au parser).

Lorsque le refus se déclenche, l’erreur cite le mot-clé fautif et le chemin du fichier. Les auteurs voient l’erreur au moment de la rédaction plutôt qu’à la première instanciation ; les corps de templates ne sont pas exemptés de l’analyse au chargement.

La sémantique des références dynamiques se couple à l’évaluation à l’exécution d’une manière qui rompt le contrat de déterminisme à la compilation du compilateur. Les auteurs qui ont besoin d’un comportement à références dynamiques restructurent le schéma pour utiliser la résolution statique de $ref ; la vérification ne prévoit aucune exemption.

Placement dans les tiers

SchemaLibrary est de niveau 3 dans le modèle de documentation par niveaux des entités — facultative pour les catalogues qui ont besoin d’une réutilisation de schémas inter-Component. Les catalogues sans contenu de schéma répété sont livrés sans aucune entité SchemaLibrary ; le marquage de niveau signale « avancé ; à ignorer si inutile » pour la navigation dans la documentation, et non une capacité. Le compilateur traite SchemaLibrary de manière uniforme avec les autres types d’entités de catalogue : même validation de l’enveloppe au chargement du workspace, même pipeline JSON Schema 2020-12 pour le contenu de chaque entrée, même pipeline de publication OCI au moment de la sortie d’une version.

Au sein du niveau 3, le mécanisme de helpers paramétriques spec.templates est lui-même facultatif. Les bibliothèques dont la structure répétée est importante (un template Probe paramétré par port + chemin ; un template CORS paramétré par les origines autorisées ; un template TLS paramétré par les chemins du certificat + de la clé) tirent profit de la réutilisation via templates ; les bibliothèques aux entrées diverses et ponctuelles omettent entièrement le bloc de templates et rédigent chaque entrée en ligne sous spec.schemas.