Aggrega-Schema für die Entwicklerabsicht (Aggregate)
Generierte Referenz. Nicht von Hand bearbeiten — aus dem veröffentlichten JSON Schema neu generieren.
Schema-ID: https://aggrega.ai/schemas/aggregate-v1beta1.schema.json
Die rekursive, parametrisierte AI-Architektur. Dient sowohl als Root eines Builds als auch als wiederverwendbares Modul.
Siehe die Authoring-Referenz zum Aggregate für Anleitungen in Prosaform zum Verfassen von Aggregate-Entitäten; diese Seite dokumentiert das strukturelle Schema, das diese Referenz beschreibt.
Typ der obersten Ebene: object
Eigenschaften
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | ja | Konstante: "aggrega.ai/v1beta1" |
kind | const “Aggregate” | ja | Konstante: "Aggregate" |
metadata | object | ja | |
defs | string[] | nein | Optionaler Block für Standard-YAML-Anker (& und *), um das Aggregate DRY zu halten, während für den Compiler ein flaches O(1)-Wörterbuch erhalten bleibt. Spiegelt den entsprechenden Block im Manifest. |
spec | object | ja | Die Oberfläche der Entwicklerabsicht: der globale Parametervertrag, Importe verschachtelter Aggregate, die öffentliche API der exportierten Komponenten, Gruppierungen in Subsysteme und die Komponenteninstanzen, aus denen das Modul besteht. |
Zusätzliche Eigenschaften sind nicht zulässig.
aggregate.metadata
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
name | string | ja | Mindestens 1 Zeichen lang. |
version | string | ja | Strikte semantische Versionierung des Aggregat-Moduls. Muster: ^(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 | nein | |
maintainers | object[] | nein | Liste der Maintainer, die für diese Entität verantwortlich sind. |
license | string | nein | SPDX-Bezeichner für die Lizenz der Software, die diese Entität beschreibt, etwa MIT oder AGPL-3.0. Er hält die Bedingungen dieser Software fest, nicht die Bedingungen dieser Datei. |
repository | string | nein | Die URL des Git-Repositorys, in dem die Quelldateien liegen. |
home | string | nein | Die URL der Homepage, des Wikis oder der Dokumentation dieser Entität. |
keywords | string[] | nein | Eine Liste beschreibender Schlüsselwörter für die Auffindbarkeit in der Benutzeroberfläche. |
labels | Map von string | nein | Duck-Typing-Labels auf Modulebene für die Suche im Katalog, die Auswertung von Policies und das Filtern in Studio/IDE. Diese Labels beschreiben die Identität des Aggregate als wiederverwendbares Modul (z. B. aggregate.aggrega.ai/tier: infrastructure, aggregate.aggrega.ai/compliance: pci-dss). Sie kaskadieren NICHT zu untergeordneten Komponentenknoten — Komponenten-Labels stammen ausschließlich aus der Katalogentität Component in Domäne 2. |
Zusätzliche Eigenschaften sind nicht zulässig.
aggregate.metadata.maintainers[]
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
name | string | ja | |
email | string | nein | |
url | string | nein |
Zusätzliche Eigenschaften sind nicht zulässig.
aggregate.spec
Die Oberfläche der Entwicklerabsicht: der globale Parametervertrag, Importe verschachtelter Aggregate, die öffentliche API der exportierten Komponenten, Gruppierungen in Subsysteme und die Komponenteninstanzen, aus denen das Modul besteht.
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
parameters | Map von object | nein | Globaler Umgebungsvertrag. Jeder Eintrag ist ein typisiertes Vertragsobjekt, das die Vokabular-Teilmenge der Kompaktform verwendet (type, description, default, enum, min/max, minLength/maxLength, pattern, format, validate, validateMessage, required, items, valuesType, properties). Verschachtelte Struktur wird über das Unterfeld properties: der typisierten Form ausgedrückt. Das Release kann den Vertrag inline (parameters: {…}) oder durch den Import einer einzelnen Quelldatei (parameters: {$import: |
aggregates | Map von object | nein | Verschachtelte Aggregate, die als importierte Module dienen. Schlüssel: ein oder mehrere Buchstaben, Ziffern, Unterstriche oder Bindestriche. Ein Punkt ist nicht zulässig. Muster: ^[a-zA-Z0-9_-]+$. |
exportedComponents | Map von string | nein | Die öffentliche API-Schnittstelle. Ordnet einen exponierten öffentlichen Namen einer internen Komponenten-ID zu. Übergeordnete Aggregates, die dieses Modul importieren, referenzieren Komponenten über diese öffentlichen Namen. |
subsystems | Map von subsystem | nein | Benannte logische Gruppierungen der Komponenten eines Aggregate in Subsysteme. Schließen sich mit Komponenten auf oberster Ebene gegenseitig aus — beide zu deklarieren wird abgelehnt. Ein Subsystem, das der Autor default nennt, ist ein gewöhnliches deklariertes Subsystem, verschieden vom synthetisierten default, das der Compiler für ein Aggregate nur mit Komponenten erzeugt. Schlüssel: ein oder mehrere Buchstaben, Ziffern, Unterstriche oder Bindestriche. Ein Punkt ist nicht zulässig. Muster: ^[a-zA-Z0-9_-]+$. |
components | Map von component_instance | nein | Die Map der logischen atomaren Komponenten, aus denen dieses Aggregate besteht, direkt auf oberster Ebene verfasst. Komponenten auf oberster Ebene und Subsysteme schließen sich gegenseitig aus — beide zu deklarieren wird abgelehnt. Werden Komponenten hier verfasst (ohne Subsysteme), fasst der Compiler sie beim Laden in einem synthetisierten Subsystem default zusammen, und die IR kennzeichnet dieses Subsystem als synthetisiert. Schlüssel: ein oder mehrere Buchstaben, Ziffern, Unterstriche oder Bindestriche. Ein Punkt ist nicht zulässig. Muster: ^[a-zA-Z0-9_-]+$. |
Zusätzliche Eigenschaften sind nicht zulässig.
Definitionen
inject_delivery
Ein einzelner Zustellmechanismus, verfasst als Array von Einträgen. Jeder Eintrag trägt ein ‘in’ (lokaler Bezeichner — Name einer Umgebungsvariablen, Dateipfad, Argument-Flag oder benutzerdefinierter mechanismusspezifischer Schlüssel) sowie genau eines von ‘from’ (ein aufzulösender provides-Schlüssel) oder ‘value’ (ein Literal-String, optional mit Go-Template-Ausdrücken, die bei der Auflösung der Selbstinjektion ausgewertet werden). ‘from’ wird gegen die provides des Ziels im Kontext uses[].inject aufgelöst, gegen die provides, die das FeatureRecipe der Anbindung veröffentlicht, im Kontext features.
Typ: object[]
inject_block
Agnostisches Injektions-Routing. Ordnet lokale Variablen provides-Schlüsseln des Ziels zu (uses[].inject), den provides-Schlüsseln, die das FeatureRecipe einer Anbindung veröffentlicht (features.
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
env | inject_delivery | nein | Ein einzelner Zustellmechanismus, verfasst als Array von Einträgen. Jeder Eintrag trägt ein ‘in’ (lokaler Bezeichner — Name einer Umgebungsvariablen, Dateipfad, Argument-Flag oder benutzerdefinierter mechanismusspezifischer Schlüssel) sowie genau eines von ‘from’ (ein aufzulösender provides-Schlüssel) oder ‘value’ (ein Literal-String, optional mit Go-Template-Ausdrücken, die bei der Auflösung der Selbstinjektion ausgewertet werden). ‘from’ wird gegen die provides des Ziels im Kontext uses[].inject aufgelöst, gegen die provides, die das FeatureRecipe der Anbindung veröffentlicht, im Kontext features. |
file | inject_delivery | nein | Ein einzelner Zustellmechanismus, verfasst als Array von Einträgen. Jeder Eintrag trägt ein ‘in’ (lokaler Bezeichner — Name einer Umgebungsvariablen, Dateipfad, Argument-Flag oder benutzerdefinierter mechanismusspezifischer Schlüssel) sowie genau eines von ‘from’ (ein aufzulösender provides-Schlüssel) oder ‘value’ (ein Literal-String, optional mit Go-Template-Ausdrücken, die bei der Auflösung der Selbstinjektion ausgewertet werden). ‘from’ wird gegen die provides des Ziels im Kontext uses[].inject aufgelöst, gegen die provides, die das FeatureRecipe der Anbindung veröffentlicht, im Kontext features. |
arg | inject_delivery | nein | Ein einzelner Zustellmechanismus, verfasst als Array von Einträgen. Jeder Eintrag trägt ein ‘in’ (lokaler Bezeichner — Name einer Umgebungsvariablen, Dateipfad, Argument-Flag oder benutzerdefinierter mechanismusspezifischer Schlüssel) sowie genau eines von ‘from’ (ein aufzulösender provides-Schlüssel) oder ‘value’ (ein Literal-String, optional mit Go-Template-Ausdrücken, die bei der Auflösung der Selbstinjektion ausgewertet werden). ‘from’ wird gegen die provides des Ziels im Kontext uses[].inject aufgelöst, gegen die provides, die das FeatureRecipe der Anbindung veröffentlicht, im Kontext features. |
component_uses_block
Die Verbindungen, die eine Komponente zu den Komponenten zieht, von denen sie abhängt, nach Socket geschlüsselt. Jeder Socket listet seine Ziele auf oder benennt jede Verbindung unter einem Alias. Eine unter einem Alias benannte Verbindung kann die verbindungsspezifischen Werte des Entwicklers tragen und die Anbindungen, die die vom Socket deklarierten Slots füllen.
Schlüssel: ein oder mehrere Buchstaben, Ziffern, Unterstriche oder Bindestriche. Ein Punkt ist nicht zulässig. Muster: ^[a-zA-Z0-9_-]+$.
Werte sind string[] or map of object.
Kein anderer Schlüssel ist zulässig.
feature_uses_block
Die Verbindungen, die ein angebundenes Feature zieht, geschlüsselt nach einem Socket, den das Feature in seinem usesSchema deklariert. Jeder Socket listet seine Ziele auf oder benennt jede Verbindung unter einem Alias. Eine von einem Feature gezogene Verbindung trägt keine eigenen Anbindungen: Zugangsdaten, die es benötigt, füllen einen Slot, den das Feature in seinem eigenen featuresSchema deklariert, und werden neben dem Feature angebunden.
Schlüssel: ein oder mehrere Buchstaben, Ziffern, Unterstriche oder Bindestriche. Ein Punkt ist nicht zulässig. Muster: ^[a-zA-Z0-9_-]+$.
Werte sind string[] or map of object.
Kein anderer Schlüssel ist zulässig.
connection_attachment
Eine Anbindung, die eine Verbindung trägt: das Feature, das einen vom Socket der Verbindung deklarierten Slot füllt, mit der Konfiguration des Entwicklers dafür.
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
type | string | ja | Die URI der Feature-Schnittstelle, die diese Anbindung anfordert (z. B. core/referenced-secret:1.0.0). |
description | string | nein | Optionale Dokumentation, die erklärt, warum diese Verbindung die Anbindung trägt. |
values | object | nein | Vom Entwickler angegebene Konfiguration für das Feature, validiert durch dessen Schemadeklaration. |
Zusätzliche Eigenschaften sind nicht zulässig.
subsystem
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
description | string | nein | Optionale Dokumentation, die den Zweck dieses Subsystems und die logische Gruppierung beschreibt, die es darstellt. |
annotations | Map von string oder object oder null | nein | Vom Entwickler verfasste Annotationen an diesem Subsystem. Werte sind Strings, strukturierte Objekte (eine Map von Unterschlüssel zu Wert, pro Unterschlüssel mit einem geerbten strukturierten Wert zusammengeführt) oder null; ein explizites null auf einem von einem übergeordneten Subsystem geerbten Schlüssel entfernt die geerbte Bindung aus diesem Subsystem (annotationsgesteuerter Verzicht auf ein Feature). Hier deklarierte Annotationen werden von verschachtelten Subsystemen und von enthaltenen Komponenten geerbt; die nähere Ebene gewinnt pro Schlüssel. Kaskadiert hinunter in den Bucket .context.annotations.aggregate an jedem abgeleiteten IR-Knoten. |
features | Map von object | nein | Übergreifende Funktionen, die an alle Komponenten dieses Subsystems angebunden werden. Dasselbe Schema wie Funktionen auf Komponentenebene (type, values, uses, inject). Bei der Finalisierung des Graphen in jede Komponente abgeflacht und in der Ausführungsreihenfolge nach den Funktionen auf Komponentenebene eingeordnet. Schlüssel: ein oder mehrere Buchstaben, Ziffern, Unterstriche oder Bindestriche. Ein Punkt ist nicht zulässig. Muster: ^[a-zA-Z0-9_-]+$. |
subsystems | Map von subsystem | nein | Schlüssel: ein oder mehrere Buchstaben, Ziffern, Unterstriche oder Bindestriche. Ein Punkt ist nicht zulässig. Muster: ^[a-zA-Z0-9_-]+$. |
components | Map von component_instance | nein | Schlüssel: ein oder mehrere Buchstaben, Ziffern, Unterstriche oder Bindestriche. Ein Punkt ist nicht zulässig. Muster: ^[a-zA-Z0-9_-]+$. |
Zusätzliche Eigenschaften sind nicht zulässig.
component_instance
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
type | string | ja | Die angeforderte abstrakte Component, als Referenz: ihr metadata.name plus eine optionale :version (z. B. core/api-server:1.0.0), niemals ein Dateipfad. Aufgelöst über das dreistufige Modell der Entitätsauflösung (Katalogverzeichnisse des Workspace → Cache → Registry): Eine lokal verfasste Component wird unter catalog/ im Root des Workspace oder in einem unter workspace.catalog_dirs aufgeführten Verzeichnis abgelegt, und ein als relativer Dateipfad geschriebener type bricht den Build als Entität ab, die kein Katalog enthält. |
active | boolean oder string | nein | Ob diese Komponente in der kompilierten Topologie vorhanden ist. Ein boolean oder ein String-Template über .parameters, das zu einem boolean aufgelöst werden muss. Wird es zu false aufgelöst, wird die Komponente aus der Topologie entfernt, kaskadierend auf ihre uses-Kanten und ihre Anbindungen. Wird der Wert aus einem Parameter abgeleitet, kann ein Release die Präsenz der Komponente umschalten, indem es diesen Parameter erfüllt. Standardmäßig true, wenn weggelassen. Standardwert: true |
description | string | nein | Optionale Dokumentation, die die Rolle dieser Komponenteninstanz in der Anwendung beschreibt. Wird bis in den IR-Graphen mitgeführt. |
annotations | Map von string oder object oder null | nein | Vom Entwickler verfasste Annotationen an dieser Komponente. Werte sind Strings, strukturierte Objekte (eine Map von Unterschlüssel zu Wert, pro Unterschlüssel mit einem geerbten strukturierten Wert zusammengeführt) oder null; ein explizites null auf einem von einem übergeordneten Subsystem geerbten Schlüssel entfernt die geerbte Bindung aus dieser Komponente (annotationsgesteuerter Verzicht auf ein Feature). Annotationen auf Component-Ebene überschreiben geerbte Annotationen auf Subsystemebene pro Schlüssel; Geschwisterkomponenten im selben Subsystem behalten ihre eigenen Annotations-Maps unabhängig voneinander. |
values | object | nein | Opake kognitive Eigenschaften, die an die Component übergeben und durch ihr Schema validiert werden. |
uses | component_uses_block | nein | Die Verbindungen, die eine Komponente zu den Komponenten zieht, von denen sie abhängt, nach Socket geschlüsselt. Jeder Socket listet seine Ziele auf oder benennt jede Verbindung unter einem Alias. Eine unter einem Alias benannte Verbindung kann die verbindungsspezifischen Werte des Entwicklers tragen und die Anbindungen, die die vom Socket deklarierten Slots füllen. |
inject | inject_block | nein | Selbstinjektion auf Component-Ebene. Injiziert die eigenen Werte der Komponente (über ‘value:’) oder ihre eigenen provides-Schlüssel (über ‘from:’) direkt in die Zustell-Pipe (.context.inject). Nur zulässig, wenn die Katalogentität Component ‘spec.inject’ mit den entsprechenden Mechanismen deklariert. Ein inject-Schlüssel, der mit einem in uses[].inject deklarierten Schlüssel kollidiert, bricht den Build als doppelter Zustellschlüssel über inject-Quellen hinweg ab. |
features | Map von object | nein | Die an diese Komponente angebundenen Features, geschlüsselt nach dem Instanznamen, den der Autor jeder Anbindung gibt. Dies ist die einzige Anbindungsoberfläche: Ein operatives Feature, ein Zugangsdaten-Feature (eines mit dem Label feature.aggrega.ai/kind: secret) und ein Identitäts-Feature werden alle hier angebunden, unter demselben Schlüsselwort und in derselben Form. Was sie unterscheidet, ist, was die Anbindung erzeugt, nicht, wie sie deklariert wird. Eine Anbindung, deren Instanzname mit einem Slot übereinstimmt, den die Component in featuresSchema deklariert, füllt diesen Slot; jeder andere Instanzname ist eine freie Anbindung. Schlüssel: ein oder mehrere Buchstaben, Ziffern, Unterstriche oder Bindestriche. Ein Punkt ist nicht zulässig. Muster: ^[a-zA-Z0-9_-]+$. |
Zusätzliche Eigenschaften sind nicht zulässig.