Aggrega-Schema für den Katalog (Component)
Generierte Referenz. Nicht von Hand bearbeiten — aus dem veröffentlichten JSON Schema neu generieren.
Schema-ID: https://aggrega.ai/schemas/component-v1beta1.schema.json
Die abstrakte Definition eines atomaren Bausteins.
Siehe die Authoring-Referenz zur Component für Anleitungen in Prosaform zum Verfassen von Component-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 “Component” | ja | Konstante: "Component" |
metadata | object | ja | |
spec | object | ja | Validierungs- und Schemadefinitionen, die die opaken Werte-Nutzdaten des Entwicklers regeln. |
Zusätzliche Eigenschaften sind nicht zulässig.
component.metadata
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
name | string | ja | Mindestens 1 Zeichen lang. |
version | string | ja | Strikte semantische Versionierung der Schnittstelle (z. B. 1.0.0). 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 | Was diese Entität ist und wofür sie gedacht ist, geschrieben für jemanden, der entscheidet, ob er sie verwendet. Beginnen Sie mit einem Satz, der die Sache benennt, und ergänzen Sie dann, was ein Leser braucht, um sie auszuwählen und richtig zu verwenden — was sie von dem Release erwartet, das sie bereitstellt, und alles Überraschende an ihrem Verhalten. Ein kurzer Absatz ist die übliche Länge. |
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 | object | ja | Duck-Typing-Labels zur Deklaration von Merkmalen. Müssen den reservierten Schlüssel ‘component.aggrega.ai/type’ enthalten. |
annotations | Map von string | nein | Unveränderliche, intrinsische Merkmale der Komponente, verfasst vom Plattformarchitekten in Domäne 2. Kaskadiert hinunter in den Bucket .context.annotations.catalog. |
Zusätzliche Eigenschaften sind nicht zulässig.
component.metadata.maintainers[]
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
name | string | ja | |
email | string | nein | |
url | string | nein |
Zusätzliche Eigenschaften sind nicht zulässig.
component.metadata.labels
Duck-Typing-Labels zur Deklaration von Merkmalen. Müssen den reservierten Schlüssel ‘component.aggrega.ai/type’ enthalten.
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
component.aggrega.ai/type | string (enum) | ja | Die reservierte Achse, die benennt, welche Art von Ding diese Komponente ist. Aggrega definiert diesen Schlüssel und die Werte, die er akzeptiert, daher ist die Menge geschlossen; um Komponenten auf einer eigenen Achse zu klassifizieren, fügen Sie neben diesem einen eigenen Label-Schlüssel hinzu. Zulässige Werte: "server", "worker", "task", "function", "stateful-server", "resource" |
component.spec
Validierungs- und Schemadefinitionen, die die opaken Werte-Nutzdaten des Entwicklers regeln.
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
extends | string | nein | URI einer Basis-Component, die diese Component erweitert. Das Erweitern setzt Struktur zusammen: die Metadaten-Labels und -Annotationen der Basis, ihre Anbindungs-Slots (featuresSchema), ihre Allowlist für die Selbstinjektion (inject) und ihre Topologie-Sockets (usesSchema) werden geerbt, und diese Component kann sie ergänzen oder einen geerbten Eintrag Schlüssel für Schlüssel ersetzen. Die Datensäulen der Basis werden NICHT zusammengesetzt — der Block schema der Basis wird genau so geerbt, wie die Basis ihn verfasst hat, daher schreibt eine erweiternde Component schema: inherited und verfasst keinen eigenen Säuleninhalt. |
featuresSchema | Map von object | nein | Deklarative Definitionen von Anbindungs-Slots: die benannten Bindungspunkte, an denen diese Entität erwartet, dass ein Feature angebunden wird. Ein Slot schränkt ein, welche Füllung ihn binden darf (selector) und wie das Material der Füllung zugestellt werden darf (inject); das eigene Feature der Füllung besitzt seinen Vertrag für values und infra. Das Deklarieren eines Slots schließt den Anbindungsblock nie — ein Autor kann ein Feature unter einem Namen anbinden, den kein Slot deklariert, sodass eine Entität sowohl eine Anbindung bedient, die einen Slot füllt, als auch Zugangsdaten, die in einem weiteren Gültigkeitsbereich geteilt werden. Ein Slot ist ein Bindungspunkt, kein Abhängigkeits-Socket: usesSchema deklariert die separate Topologie-Oberfläche. |
inject | string[] | nein | Per Allowlist zugelassene Zustellmechanismen der Selbstinjektion (z. B. [‘env’, ‘file’, ‘arg’]). Wenn vorhanden, können Entwickler den Block inject: auf Komponentenebene im Aggregate verwenden, um ihre eigenen values oder Schlüssel aus provides direkt in die Zustell-Pipe zu injizieren. Wenn weggelassen, ist die Selbstinjektion auf Komponentenebene verboten (Black-Box-Muster — das Recipe übernimmt die gesamte interne Verdrahtung). Gleiche Semantik wie usesSchema[].inject, regelt aber die eigenen values der Komponente statt der komponentenübergreifenden Topologie. Jeder Mechanismusname darf aufgeführt werden außer all, den kein inject-Block nennen kann. |
usesSchema | Map von object | nein | Die Abhängigkeits-Sockets, die diese Entität deklariert, nach Socket-Namen geschlüsselt; jede durch einen Socket gezogene Verbindung wird gegen die Deklaration dieses Sockets geprüft — seinen Selektor, die Injektionsmechanismen, die er zulässt, und seine Verträge pro Verbindung. Schlüssel: ein oder mehrere Buchstaben, Ziffern, Unterstriche oder Bindestriche. Ein Punkt ist nicht zulässig. Muster: ^[a-zA-Z0-9_-]+$. |
schema | any | nein | Inhalt im Format JSON Schema 2020-12, der die frei geformten Säulen abdeckt: values (die Domäne des Entwicklers — anwendungsbezogene Parameter, die der Entwickler pro Component-Instanz im Aggregate konfiguriert); infra (die Domäne des Betreibers — physische Dimensionierungsregler, die das Release liefert); und provides (nachgelagerte Kontextschlüssel, die diese Component Konsumenten über die Topologie-Pipe zur Verfügung stellt). Akzeptiert vier Authoring-Modi per Dispatch nach Inhaltsform: (1) Inline-Inhalt (eine YAML-Map mit Kompaktform, JSON Schema YAML oder gemischt); (2) Dateiersetzung über {$import: |
assertions | Map von string | nein | Feldübergreifende Validierung zur Build-Zeit. Jeder Eintrag ist eine benannte Assertion: Der Schlüssel ist ein stabiler Regelbezeichner, der in Fehlermeldungen erscheint; der Wert ist ein Go-Template-String mit der Abbruchsemantik {{ fail "message" }}. Mehrere benannte Assertions pro Entität werden pro Instanz in der vom Autor deklarierten Reihenfolge ausgewertet; die erste fehlschlagende Assertion bricht den Build ab. Component-Assertions werden nach der Auflösung und der statischen Analyse, vor dem Rendern ausgewertet und drücken architektonische Invarianten des Vertrags aus, die unabhängig davon gelten, welches Recipe bindet. Template-Kontext: .values / .infra / .uses / .features / .metadata. Der Auswerter verwendet missingkey=error: Referenzen auf nicht definierte Schlüssel brechen mit einer no-such-key-Diagnose ab. Da die bloße Referenz abbricht, bevor ein Fallback ausgeführt werden kann, liefert ein einfaches default auf dieser Oberfläche keinen Fallback für ein optionales Feld — sichern Sie die Referenz mit hasKey ab, oder verwenden Sie den Helfer optional, der die Anwesenheitsprüfung direkt durchführt. Auch das Lesen des Schlüssels über index liefert keinen: index bricht bei einem Map-Schlüssel ab, den die Map nicht enthält, und nennt den Schlüssel. Die Vererbung ist additiv: Eine Component, die extends deklariert, wird gegen die Assertions ausgewertet, die sie erbt, sowie gegen ihre eigenen, die geerbten Regeln zuerst, und eine Kette beliebiger Tiefe akkumuliert von der Wurzel der Kette abwärts — wenn also mehr als eine Regel fehlschlagen würde, wird diejenige gemeldet, die am weitesten oben in der Kette deklariert ist. Die Wiederverwendung eines geerbten Namens zur Deklaration einer anderen Regel wird abgelehnt, wenn die extends-Kette gegen den Katalog aufgelöst wird, wobei beide Components und der gemeinsame Name genannt werden — sie tritt also zutage, sobald die Basis-Component vorhanden ist, nicht allein aus dem erweiternden Dokument; eine erweiternde Component fügt Regeln hinzu und ersetzt nie eine. Eine geerbte Regel byteweise identisch unter ihrem eigenen Namen erneut anzugeben, wird als die wirkungslose Operation akzeptiert, die sie ist. Nichts prüft, ob zwei Regeln gleichzeitig gelten können: Ein gegenseitig unerfüllbares Paar ist ein Authoring-Fehler, der als gewöhnlicher Assertion-Fehlschlag zutage tritt, wenn eine Instanz diejenige auslöst, die zuerst greift, nie als Warnung im Voraus. |
Zusätzliche Eigenschaften sind nicht zulässig.
Definitionen
extending-component-must-declare-schema-inherited
Gilt, wenn spec.extends vorhanden ist. Eine erweiternde Component erhält values / infra / provides ihrer Basis genau so, wie die Basis sie verfasst hat, daher deklariert sie spec.schema: inherited und verfasst keinen Säuleninhalt. Beide anderen Ergebnisse sind Fehler, und es sind unterschiedliche Fehler: spec.schema ganz wegzulassen, wodurch ein Leser einen geerbten Säulenblock nicht von einem vergessenen unterscheiden könnte; und Säuleninhalt unter spec.schema zu verfassen, was einen zweiten, abweichenden Vertrag für eine Component verlangen würde, deren Vertrag der ihrer Basis ist.
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
schema | const “inherited” | ja | Die Vererbungsmarkierung und der einzige Wert, den spec.schema bei einer Component annimmt, die extends deklariert. Sie benennt, woher die Säulen stammen; der Säuleninhalt selbst ist der der Basis-Component. Konstante: "inherited" |
non-extending-component-authors-its-own-schema
Gilt, wenn spec.extends fehlt. Eine Component, die keine Basis erweitert, verfasst ihren eigenen Inhalt für values / infra / provides unter spec.schema, daher enthält das Feld verfassten Inhalt statt der Markierung inherited: Die Markierung besagt, dass die Säulen von einer Basis stammen, und diese Component hat keine.
| Eigenschaft | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
schema | object | nein | Verfasster Säuleninhalt — eine Map, in einem der drei Modi für das Verfassen von Inhalt, die spec.schema dokumentiert. |