Schéma du catalogue d’Aggrega (Component)
Référence générée. Ne pas modifier à la main — régénérer à partir du JSON Schema publié.
Identifiant du schéma : https://aggrega.ai/schemas/component-v1beta1.schema.json
La définition abstraite d’une brique de base atomique.
Consultez la référence de rédaction du Component pour des conseils rédigés sur l’écriture des entités Component ; cette page documente le schéma structurel que décrit cette référence.
Type de premier niveau : object
Propriétés
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | oui | Constante : "aggrega.ai/v1beta1" |
kind | const “Component” | oui | Constante : "Component" |
metadata | object | oui | |
spec | object | oui | Définitions de validation et de schéma régissant la charge utile opaque des valeurs du développeur. |
Les propriétés supplémentaires ne sont pas autorisées.
component.metadata
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
name | string | oui | Au moins 1 caractère. |
version | string | oui | Versionnage sémantique strict de l’interface (par ex. 1.0.0). Motif : ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
description | string | non | Ce qu’est cette entité et à quoi elle sert, écrit pour quelqu’un qui décide s’il va l’utiliser. Commencez par une phrase qui nomme la chose, puis ajoutez ce dont un lecteur a besoin pour la choisir et l’utiliser correctement — ce qu’elle attend de la Release qui la déploie, et tout ce que son comportement a de surprenant. Un court paragraphe est la longueur habituelle. |
maintainers | object[] | non | Liste des mainteneurs responsables de cette entité. |
license | string | non | Identifiant SPDX de la licence du logiciel que décrit cette entité, par exemple MIT ou AGPL-3.0. Il consigne les conditions de ce logiciel, pas celles de ce fichier. |
repository | string | non | L’URL du dépôt Git où se trouvent les fichiers source. |
home | string | non | L’URL de la page d’accueil, du wiki ou de la documentation de cette entité. |
keywords | string[] | non | Une liste de mots-clés descriptifs pour la découvrabilité dans l’interface utilisateur. |
labels | object | oui | Labels de duck typing pour déclarer des caractéristiques. Doivent inclure la clé réservée ‘component.aggrega.ai/type’. |
annotations | map de string | non | Caractéristiques intrinsèques et immuables du composant, écrites par l’architecte de plateforme dans le Domaine 2. Se propagent en cascade jusqu’au compartiment .context.annotations.catalog. |
Les propriétés supplémentaires ne sont pas autorisées.
component.metadata.maintainers[]
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
name | string | oui | |
email | string | non | |
url | string | non |
Les propriétés supplémentaires ne sont pas autorisées.
component.metadata.labels
Labels de duck typing pour déclarer des caractéristiques. Doivent inclure la clé réservée ‘component.aggrega.ai/type’.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
component.aggrega.ai/type | string (enum) | oui | L’axe réservé qui nomme le type de chose qu’est ce composant. Aggrega définit cette clé et les valeurs qu’elle accepte, l’ensemble est donc fermé ; pour classer les composants selon un axe qui vous est propre, ajoutez votre propre clé de label à côté de celle-ci. Valeurs autorisées : "server", "worker", "task", "function", "stateful-server", "resource" |
component.spec
Définitions de validation et de schéma régissant la charge utile opaque des valeurs du développeur.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
extends | string | non | URI d’un Component de base que ce Component étend. L’extension compose la structure : les labels et annotations de métadonnées de la base, ses emplacements de rattachement (featuresSchema), sa liste d’autorisation d’auto-injection (inject) et ses sockets de topologie (usesSchema) sont hérités, et ce Component peut les compléter ou remplacer une entrée héritée clé par clé. Les piliers de données de la base ne sont PAS composés — le bloc schema de la base est hérité exactement tel que la base l’a rédigé, de sorte qu’un Component qui étend écrit schema: inherited et ne rédige aucun contenu de pilier propre. |
featuresSchema | map de object | non | Définitions déclaratives des emplacements de rattachement : les points de liaison nommés auxquels cette entité attend qu’une Feature soit rattachée. Un emplacement restreint le remplissage qui peut s’y lier (selector) et la manière dont le matériau du remplissage peut être livré (inject) ; la Feature propre au remplissage possède son contrat values et infra. Déclarer un emplacement ne ferme jamais le bloc de rattachement — un auteur peut rattacher une Feature sous un nom qu’aucun emplacement ne déclare, de sorte qu’une même entité sert à la fois un rattachement qui remplit un emplacement et des informations d’identification partagées à une portée plus large. Un emplacement est un point de liaison, pas un socket de dépendance : usesSchema déclare la surface de topologie distincte. |
inject | string[] | non | Mécanismes de livraison d’auto-injection admis par la liste d’autorisation (par ex. [‘env’, ‘file’, ‘arg’]). Lorsqu’il est présent, les développeurs peuvent utiliser le bloc inject: au niveau du composant dans l’Aggregate pour injecter leurs propres values ou clés provides directement dans le pipe de livraison. S’il est omis, l’auto-injection au niveau du composant est interdite (modèle Black-Box — la Recipe gère tout le câblage interne). Même sémantique que usesSchema[].inject, mais régit les values propres du composant plutôt que la topologie entre composants. Tout nom de mécanisme peut être listé sauf all, qu’aucun bloc inject ne peut nommer. |
usesSchema | map de object | non | Les sockets de dépendance que cette entité déclare, indexés par nom de socket ; chaque connexion tracée à travers un socket est vérifiée par rapport à la déclaration de ce socket — son sélecteur, les mécanismes d’injection qu’il autorise et ses contrats par connexion. Clés : une ou plusieurs lettres, chiffres, traits de soulignement ou traits d’union. Un point n’est pas autorisé. Motif : ^[a-zA-Z0-9_-]+$. |
schema | any | non | Contenu JSON Schema 2020-12 couvrant les piliers de forme libre : values (le domaine du Développeur — paramètres de forme applicative que le Développeur configure pour chaque instance de Component dans l’Aggregate) ; infra (le domaine de l’Opérateur — réglages de dimensionnement physique fournis par la Release) ; et provides (clés de contexte en aval que ce Component expose aux consommateurs via le pipe de topologie). Accepte quatre modes de rédaction par aiguillage selon la forme du contenu : (1) contenu inline (une map YAML portant la forme compacte, du JSON Schema YAML ou un mélange des deux) ; (2) remplacement par fichier via {$import: |
assertions | map de string | non | Validation inter-champs au moment du build. Chaque entrée est une assertion nommée : la clé est un identifiant de règle stable qui apparaît dans les messages d’erreur ; la valeur est une chaîne de template Go avec la sémantique d’arrêt {{ fail "message" }}. Plusieurs assertions nommées par entité sont évaluées par instance dans l’ordre déclaré par l’auteur ; la première assertion en échec interrompt le build. Les assertions de Component sont évaluées après la résolution et l’analyse statique, avant le rendu, et expriment des invariants architecturaux du contrat qui valent quelle que soit la Recipe qui se lie. Contexte du template : .values / .infra / .uses / .features / .metadata. L’évaluateur utilise missingkey=error : les références à des clés non définies provoquent un arrêt avec un diagnostic no-such-key. Comme la simple référence provoque l’arrêt avant que tout repli puisse s’exécuter, un simple default ne fournit pas de repli pour un champ optionnel sur cette surface — protégez la référence avec hasKey, ou utilisez l’assistant optional, qui effectue directement la vérification de présence. Lire la clé via index n’en fournit pas non plus : index provoque un arrêt sur une clé de map que la map ne contient pas, en nommant la clé. L’héritage est additif : un Component déclarant extends est évalué par rapport aux assertions dont il hérite ainsi qu’aux siennes, les règles héritées en premier, et une chaîne de n’importe quelle profondeur s’accumule depuis la racine de la chaîne vers le bas — ainsi, lorsque plus d’une règle échouerait, c’est celle déclarée le plus haut dans la chaîne qui est signalée. Réutiliser un nom hérité pour déclarer une règle différente est rejeté lorsque la chaîne extends est résolue par rapport au catalogue, en nommant les deux Components et le nom partagé — cela apparaît donc dès que le Component de base est présent, et non à partir du seul document qui étend ; un Component qui étend ajoute des règles et n’en remplace jamais aucune. Redéclarer une règle héritée octet pour octet sous son propre nom est accepté comme l’opération sans effet qu’elle est. Rien ne vérifie si deux règles peuvent valoir simultanément : une paire mutuellement insatisfiable est une erreur de rédaction qui apparaît comme un échec d’assertion ordinaire lorsqu’une instance déclenche celle qui se déclenche en premier, jamais comme un avertissement préalable. |
Les propriétés supplémentaires ne sont pas autorisées.
Définitions
extending-component-must-declare-schema-inherited
S’applique lorsque spec.extends est présent. Un Component qui étend reçoit les values / infra / provides de sa base exactement tels que la base les a rédigés, il déclare donc spec.schema: inherited et ne rédige aucun contenu de pilier. Les deux autres issues sont des erreurs, et ce sont des fautes différentes : omettre entièrement spec.schema, ce qui empêcherait un lecteur de distinguer un bloc de piliers hérité d’un bloc oublié ; et rédiger du contenu de pilier sous spec.schema, ce qui demanderait un second contrat, divergent, sur un Component dont le contrat est celui de sa base.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
schema | const “inherited” | oui | Le marqueur d’héritage, et la seule valeur que prend spec.schema sur un Component qui déclare extends. Il indique d’où viennent les piliers ; le contenu des piliers lui-même est celui du Component de base. Constante : "inherited" |
non-extending-component-authors-its-own-schema
S’applique lorsque spec.extends est absent. Un Component qui n’étend aucune base rédige son propre contenu values / infra / provides sous spec.schema, de sorte que le champ porte du contenu rédigé plutôt que le marqueur inherited : le marqueur indique que les piliers viennent d’une base, et ce Component n’en a aucune.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
schema | object | non | Contenu de pilier rédigé — une map, dans l’un quelconque des trois modes de rédaction de contenu que documente spec.schema. |