Schéma de l’intention du développeur d’Aggrega (Aggregate)
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/aggregate-v1beta1.schema.json
L’architecture AI récursive et paramétrée. Sert à la fois de racine d’un build et de module réutilisable.
Consultez la référence de rédaction de l’Aggregate pour des conseils rédigés sur l’écriture des entités Aggregate ; 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 “Aggregate” | oui | Constante : "Aggregate" |
metadata | object | oui | |
defs | string[] | non | Bloc facultatif pour les ancres YAML standard (& et *), afin de garder l’Aggregate DRY tout en conservant pour le compilateur un dictionnaire plat en O(1). Reflète le bloc équivalent du Manifest. |
spec | object | oui | La surface de l’intention du développeur : le contrat global des paramètres, les imports d’agrégats imbriqués, l’API publique des composants exportés, les regroupements en sous-systèmes et les instances de composant qui constituent le module. |
Les propriétés supplémentaires ne sont pas autorisées.
aggregate.metadata
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
name | string | oui | Au moins 1 caractère. |
version | string | oui | Versionnage sémantique strict du module agrégat. 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 | |
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 | map de string | non | Labels de duck typing au niveau du module pour la découverte dans le catalogue, l’évaluation des politiques et le filtrage dans Studio/IDE. Ces labels décrivent l’identité de l’Aggregate en tant que module réutilisable (par ex. aggregate.aggrega.ai/tier: infrastructure, aggregate.aggrega.ai/compliance: pci-dss). Ils ne se propagent PAS en cascade aux nœuds de composants enfants — les labels des composants proviennent exclusivement de l’entité de catalogue Component dans le Domaine 2. |
Les propriétés supplémentaires ne sont pas autorisées.
aggregate.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.
aggregate.spec
La surface de l’intention du développeur : le contrat global des paramètres, les imports d’agrégats imbriqués, l’API publique des composants exportés, les regroupements en sous-systèmes et les instances de composant qui constituent le module.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
parameters | map de object | non | Contrat global d’environnement. Chaque entrée est un objet de contrat typé qui utilise le sous-ensemble du vocabulaire en forme compacte (type, description, default, enum, min/max, minLength/maxLength, pattern, format, validate, validateMessage, required, items, valuesType, properties). La structure imbriquée s’exprime via le sous-champ properties: de la forme typée. La Release peut y répondre inline (parameters: {…}) ou par l’import d’un seul fichier source (parameters: {$import: |
aggregates | map de object | non | Agrégats imbriqués servant de modules importés. 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_-]+$. |
exportedComponents | map de string | non | L’interface d’API publique. Associe un nom public exposé à un ID de composant interne. Les Aggregates parents qui importent ce module référencent les composants par ces noms publics. |
subsystems | map de subsystem | non | Regroupements logiques nommés des composants d’un Aggregate en sous-systèmes. Mutuellement exclusifs avec les composants de premier niveau — déclarer les deux est refusé. Un sous-système que l’auteur nomme default est un sous-système déclaré ordinaire, distinct du default synthétisé que le compilateur crée pour un Aggregate qui n’a que des composants. 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_-]+$. |
components | map de component_instance | non | La map des composants logiques atomiques qui constituent cet Aggregate, écrits directement au premier niveau. Les composants de premier niveau et les sous-systèmes sont mutuellement exclusifs — déclarer les deux est refusé. Lorsque des composants sont écrits ici (sans sous-systèmes), le compilateur les replie au chargement dans un sous-système default synthétisé, et l’IR marque ce sous-système comme synthétisé. 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_-]+$. |
Les propriétés supplémentaires ne sont pas autorisées.
Définitions
inject_delivery
Un mécanisme de livraison unique, écrit sous forme de tableau d’entrées. Chaque entrée porte un ‘in’ (identifiant local — nom de variable d’environnement, chemin de fichier, flag d’argument ou clé personnalisée propre au mécanisme) plus exactement un parmi ‘from’ (une clé provides à résoudre) ou ‘value’ (une chaîne littérale, contenant éventuellement des expressions de template Go évaluées lors de la résolution de l’auto-injection). ‘from’ se résout par rapport aux provides de la cible dans le contexte uses[].inject, par rapport aux provides que publie la FeatureRecipe du rattachement dans le contexte features.
Type : object[]
inject_block
Routage agnostique de l’injection. Associe des variables locales à des clés provides de la cible (uses[].inject), aux clés provides que publie la FeatureRecipe d’un rattachement (features.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
env | inject_delivery | non | Un mécanisme de livraison unique, écrit sous forme de tableau d’entrées. Chaque entrée porte un ‘in’ (identifiant local — nom de variable d’environnement, chemin de fichier, flag d’argument ou clé personnalisée propre au mécanisme) plus exactement un parmi ‘from’ (une clé provides à résoudre) ou ‘value’ (une chaîne littérale, contenant éventuellement des expressions de template Go évaluées lors de la résolution de l’auto-injection). ‘from’ se résout par rapport aux provides de la cible dans le contexte uses[].inject, par rapport aux provides que publie la FeatureRecipe du rattachement dans le contexte features. |
file | inject_delivery | non | Un mécanisme de livraison unique, écrit sous forme de tableau d’entrées. Chaque entrée porte un ‘in’ (identifiant local — nom de variable d’environnement, chemin de fichier, flag d’argument ou clé personnalisée propre au mécanisme) plus exactement un parmi ‘from’ (une clé provides à résoudre) ou ‘value’ (une chaîne littérale, contenant éventuellement des expressions de template Go évaluées lors de la résolution de l’auto-injection). ‘from’ se résout par rapport aux provides de la cible dans le contexte uses[].inject, par rapport aux provides que publie la FeatureRecipe du rattachement dans le contexte features. |
arg | inject_delivery | non | Un mécanisme de livraison unique, écrit sous forme de tableau d’entrées. Chaque entrée porte un ‘in’ (identifiant local — nom de variable d’environnement, chemin de fichier, flag d’argument ou clé personnalisée propre au mécanisme) plus exactement un parmi ‘from’ (une clé provides à résoudre) ou ‘value’ (une chaîne littérale, contenant éventuellement des expressions de template Go évaluées lors de la résolution de l’auto-injection). ‘from’ se résout par rapport aux provides de la cible dans le contexte uses[].inject, par rapport aux provides que publie la FeatureRecipe du rattachement dans le contexte features. |
component_uses_block
Les connexions qu’un composant établit vers les composants dont il dépend, indexées par socket. Chaque socket liste ses cibles, ou nomme chaque connexion sous un alias. Une connexion nommée sous un alias peut porter les valeurs par connexion du développeur et les rattachements qui remplissent les emplacements que le socket déclare.
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_-]+$.
Les valeurs sont string[] or map of object.
Aucune autre clé n’est autorisée.
feature_uses_block
Les connexions qu’établit une Feature rattachée, indexées par un socket que la Feature déclare dans son usesSchema. Chaque socket liste ses cibles, ou nomme chaque connexion sous un alias. Une connexion établie par une Feature ne porte aucun rattachement propre : les informations d’identification dont elle a besoin remplissent un emplacement que la Feature déclare dans son propre featuresSchema et sont rattachées à côté de la Feature.
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_-]+$.
Les valeurs sont string[] or map of object.
Aucune autre clé n’est autorisée.
connection_attachment
Un rattachement que porte une connexion : la Feature qui remplit un emplacement déclaré par le socket de la connexion, avec la configuration du développeur pour celle-ci.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
type | string | oui | L’URI de l’interface de Feature que demande ce rattachement (par ex. core/referenced-secret:1.0.0). |
description | string | non | Documentation facultative expliquant pourquoi cette connexion porte le rattachement. |
values | object | non | Configuration fournie par le développeur pour la Feature, validée par sa déclaration de schéma. |
Les propriétés supplémentaires ne sont pas autorisées.
subsystem
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
description | string | non | Documentation facultative décrivant l’objectif de ce sous-système et le regroupement logique qu’il représente. |
annotations | map de string ou object ou null | non | Annotations écrites par le développeur sur ce sous-système. Les valeurs sont des chaînes, des objets structurés (une map de sous-clé vers valeur, fusionnée par sous-clé avec une valeur structurée héritée) ou null ; un null explicite sur une clé héritée d’un sous-système parent retire de ce sous-système la liaison héritée (renonciation à une Feature pilotée par annotation). Les annotations déclarées ici sont héritées par les sous-systèmes imbriqués et par les composants contenus ; le niveau le plus proche l’emporte clé par clé. Se propagent en cascade jusqu’au compartiment .context.annotations.aggregate de chaque nœud IR dérivé. |
features | map de object | non | Fonctionnalités transversales rattachées à tous les composants de ce sous-système. Même schéma que les fonctionnalités au niveau du composant (type, values, uses, inject). Aplaties dans chaque composant lors de la finalisation du graphe, placées après les fonctionnalités au niveau du composant dans l’ordre d’exécution. 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_-]+$. |
subsystems | map de subsystem | non | 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_-]+$. |
components | map de component_instance | non | 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_-]+$. |
Les propriétés supplémentaires ne sont pas autorisées.
component_instance
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
type | string | oui | Le Component abstrait demandé, sous forme de référence : son metadata.name plus un :version facultatif (par ex. core/api-server:1.0.0), jamais un chemin de fichier. Résolu via le modèle de résolution des entités à trois niveaux (répertoires de catalogue de l’espace de travail → cache → registry) : un Component écrit localement est placé sous catalog/ à la racine de l’espace de travail ou dans un répertoire listé sous workspace.catalog_dirs, et un type écrit comme chemin de fichier relatif interrompt le build en tant qu’entité qu’aucun catalogue ne contient. |
active | boolean ou string | non | Indique si ce composant est présent dans la topologie compilée. Un boolean, ou un template de chaîne sur .parameters qui doit se résoudre en boolean. Lorsqu’il se résout en false, le composant est retiré de la topologie, en cascade sur ses arêtes uses et ses rattachements. Tirer la valeur d’un paramètre permet à une Release d’activer ou de désactiver la présence du composant en renseignant ce paramètre. Vaut true lorsqu’il est omis. Par défaut : true |
description | string | non | Documentation facultative décrivant le rôle de cette instance de composant dans l’application. Transmise jusqu’au graphe IR. |
annotations | map de string ou object ou null | non | Annotations écrites par le développeur sur ce composant. Les valeurs sont des chaînes, des objets structurés (une map de sous-clé vers valeur, fusionnée par sous-clé avec une valeur structurée héritée) ou null ; un null explicite sur une clé héritée d’un sous-système parent retire de ce composant la liaison héritée (renonciation à une Feature pilotée par annotation). Les annotations au niveau Component remplacent, clé par clé, les annotations héritées au niveau du sous-système ; les composants frères d’un même sous-système conservent indépendamment leurs propres maps d’annotations. |
values | object | non | Propriétés cognitives opaques transmises au Component, validées par son schéma. |
uses | component_uses_block | non | Les connexions qu’un composant établit vers les composants dont il dépend, indexées par socket. Chaque socket liste ses cibles, ou nomme chaque connexion sous un alias. Une connexion nommée sous un alias peut porter les valeurs par connexion du développeur et les rattachements qui remplissent les emplacements que le socket déclare. |
inject | inject_block | non | Auto-injection au niveau Component. Injecte les valeurs propres du composant (via ‘value:’) ou ses propres clés provides (via ‘from:’) directement dans le pipe de livraison (.context.inject). Autorisé uniquement si l’entité de catalogue Component déclare ‘spec.inject’ avec les mécanismes correspondants. Une clé inject qui entre en collision avec une clé déclarée dans uses[].inject interrompt le build en tant que clé de livraison en double entre sources d’inject. |
features | map de object | non | Les Features rattachées à ce composant, indexées par le nom d’instance que l’auteur donne à chaque rattachement. C’est l’unique surface de rattachement : une Feature opérationnelle, une Feature d’identifiants (une Feature portant le label feature.aggrega.ai/kind: secret) et une Feature d’identité sont toutes rattachées ici, sous le même mot-clé et avec la même forme. Ce qui les distingue est ce que produit le rattachement, pas la manière dont il est déclaré. Un rattachement dont le nom d’instance correspond à un emplacement que le Component déclare dans featuresSchema remplit cet emplacement ; tout autre nom d’instance est un rattachement libre. 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_-]+$. |
Les propriétés supplémentaires ne sont pas autorisées.