Schéma du catalogue d’Aggrega (Feature)
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/feature-v1beta1.schema.json
Une fonctionnalité opérationnelle modulaire qui se lie dynamiquement aux composants.
Consultez la référence de rédaction de la Feature pour des conseils rédigés sur l’écriture des entités Feature ; 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 “Feature” | oui | Constante : "Feature" |
metadata | object | oui | |
spec | object | oui | Le contrat de validation, de ciblage et d’interopérabilité d’une Feature du catalogue : les piliers de forme libre (values, infra, provides) rédigés via schema, les piliers de forme fixe (sockets de dépendance usesSchema, emplacements de rattachement featuresSchema), le ciblage des composants (appliesTo et appliesToAnyOf) et les contrôles d’interopérabilité. |
Les propriétés supplémentaires ne sont pas autorisées.
feature.metadata
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
name | string | oui | Au moins 1 caractère. |
version | string | oui | Versionnage sémantique strict de la fonctionnalité (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 | non | Labels de duck typing pour la Feature. Le label réservé ‘feature.aggrega.ai/kind’ avec la valeur ‘secret’ marque celle-ci comme une Feature d’identifiants pour l’auteur et pour l’outillage qui la met en évidence. Une Feature d’identifiants et une Feature ordinaire sont rattachées de la même manière, sous la même surface de rattachement ; ce que produit un rattachement est décidé par la FeatureRecipe vers laquelle le Manifest mappe son type, et non par le label. |
annotations | map de string | non | Caractéristiques intrinsèques et immuables de la fonctionnalité, é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.
feature.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.
feature.metadata.labels
Labels de duck typing pour la Feature. Le label réservé ‘feature.aggrega.ai/kind’ avec la valeur ‘secret’ marque celle-ci comme une Feature d’identifiants pour l’auteur et pour l’outillage qui la met en évidence. Une Feature d’identifiants et une Feature ordinaire sont rattachées de la même manière, sous la même surface de rattachement ; ce que produit un rattachement est décidé par la FeatureRecipe vers laquelle le Manifest mappe son type, et non par le label.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
feature.aggrega.ai/kind | string (enum) | non | Label de nature de la Feature. La valeur ‘secret’ marque celle-ci comme une Feature d’identifiants. Valeurs autorisées : "secret" |
feature.spec
Le contrat de validation, de ciblage et d’interopérabilité d’une Feature du catalogue : les piliers de forme libre (values, infra, provides) rédigés via schema, les piliers de forme fixe (sockets de dépendance usesSchema, emplacements de rattachement featuresSchema), le ciblage des composants (appliesTo et appliesToAnyOf) et les contrôles d’interopérabilité.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
extends | string | non | Référence à une Feature de base dont cette Feature hérite. Elle nomme la base par son metadata.name plutôt que par la coordonnée de registre sous laquelle la Feature est publiée, et accepte les trois mêmes formes de version que toute référence de catalogue : nue (core/queue) pour la version disponible la plus élevée, exacte (core/queue:1.0.0) ou une plage avec accent circonflexe (core/queue:^1.0.0). Ce qui est hérité dépasse les métadonnées : les metadata.labels et metadata.annotations de la base, ses sélecteurs appliesTo et appliesToAnyOf, son bloc interoperability, son usesSchema et son featuresSchema sont tous fusionnés vers le bas, et ses déclarations JSON Schema 2020-12 sur schema sont fusionnées automatiquement. La valeur propre de l’enfant l’emporte sur une clé partagée, et les champs d’identité ne sont jamais hérités. |
featuresSchema | map de object | non | Définitions déclaratives des emplacements de rattachement : les points de liaison nommés auxquels cette Feature attend qu’une autre 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. Un emplacement est un point de liaison, pas un socket de dépendance : usesSchema déclare la surface de topologie distincte. |
appliesTo | string | non | Chaîne de sélecteur de labels de style Kubernetes qui cible des Components. Les exigences séparées par des virgules doivent toutes être satisfaites (AND). Formes prises en charge : key=value, key!=value, key in (v1, v2), key notin (v1, v2), clé nue (label présent), !key (label absent). Exemple : “tier in (critical, production), !legacy”. Un sélecteur vide ou absent ne déclare aucune contrainte. Le sélecteur est lu par rapport à ces formes chaque fois qu’un rattachement de cette Feature est évalué, et une exigence hors de ces formes arrête le build en la nommant : une exigence vide (une virgule en tête, en fin ou doublée), ou une clé contenant des espaces ou l’un des caractères = ! ( ) et la virgule — ainsi “!tier=frontend” est refusé, et tier!=frontend est la manière d’exclure une valeur. Une valeur est le texte qui suit son opérateur, quels que soient les caractères qu’il contient. Le motif de ce champ ne refuse que quelques formes mal construites, avant qu’aucun rattachement ne soit évalué. Motif : ^(?:[^()]*[()][\s\S]*|[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?(?:,[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?)*)$. |
appliesToAnyOf | string ou map de string[] | non | Une liste de sélecteurs ; la Feature s’applique si N’IMPORTE QUEL élément correspond (logique OR). Chaque élément est soit une chaîne de sélecteur de labels (même grammaire que appliesTo ; les exigences à l’intérieur de la chaîne se combinent en AND), soit une map clé-valeur plate dont chaque paire doit correspondre (égalité uniquement). |
interoperability | object | non | Contrôles avancés de sûreté opérationnelle et d’interopérabilité. |
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 et les mécanismes d’injection qu’il autorise. 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 | object | 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 rattachement de Feature 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 cette Feature expose aux consommateurs via le pipe de topologie). Accepte trois 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 Feature sont évaluées après la résolution et l’analyse statique, avant le rendu, et expriment des invariants architecturaux du contrat. 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é. |
Les propriétés supplémentaires ne sont pas autorisées.
feature.spec.interoperability
Contrôles avancés de sûreté opérationnelle et d’interopérabilité.
| Propriété | Type | Obligatoire | Description |
|---|---|---|---|
conflictsWith | string[] | non | Noms des Features aux côtés desquelles cette Feature ne peut pas atteindre un composant, chacun écrit de la manière dont le type d’un rattachement nomme une Feature. Le build s’interrompt avant le rendu lorsqu’un composant finit par porter cette Feature et une Feature nommée ici — que chacune ait été rattachée sur le composant, sur un sous-système ou une frontière qui le contient, sur une entrée de composant de la Release, ou par expansion pilotée par les annotations. Une seule déclaration suffit : l’arrêt n’exige pas que l’autre Feature liste celle-ci. Les noms sont comparés sans aucune version, de sorte qu’une entrée correspond à toutes les versions de la Feature qu’elle nomme. Deux Features rattachées à des frontières sœurs qui ne partagent aucun composant ne se rencontrent jamais et ne provoquent pas d’arrêt. |
Les propriétés supplémentaires ne sont pas autorisées.