SchemaLibrary
Eine SchemaLibrary ist eine Katalogentität, die wiederverwendbare Definitionen in JSON Schema 2020-12 sowie optionale parametrisierte Helfer enthält. Components und Features, die Schemaformen teilen — URLs, Dauern, gemeinsame Probe-Strukturen, wiederkehrende Ressourcenlimits —, deklarieren diese Formen einmal in einer Bibliothek und verweisen über kanonische $ref-URIs darauf. Die Bibliotheksentität ist Stufe 3: optional für Kataloge, die Component-übergreifende Schemawiederverwendung benötigen. Kataloge ohne wiederholte Schemainhalte werden ohne jede SchemaLibrary ausgeliefert.
Die Rolle der SchemaLibrary
Plattformarchitekten schreiben SchemaLibraries, um Schemaformen zu zentralisieren, die im gesamten Katalog wiederkehren. Eine Bibliothek ist kein bereitstellbarer Baustein; sie ist ein Namensraum für Definitionen. Autoren von Component / Feature verweisen auf Bibliothekseinträge über ihre kanonische $ref-URI, einmal typisiert und überall validiert, wo die Referenz aufgelöst wird.
Die Trennung zwischen „Bibliothek“ und „Konsument“ ist beabsichtigt. Components deklarieren den Vertrag, den eine Instanz ausfüllt (ihre values, infra und provides, ihre Sockets, ihre Slots für Anmeldedaten). Features kodieren Verhaltensanbindungen. SchemaLibraries kodieren nur Schemainhalte — die strukturellen Regeln, die ein Wert erfüllen muss. Die drei Rollen getrennt zu halten, lässt jede Entitätsart sich in ihrem eigenen Takt weiterentwickeln; Autoren, die keine gemeinsamen Schemadefinitionen benötigen, begegnen der Bibliotheksentität nie.
Entitätshülle
Eine SchemaLibrary-Entität trägt den Standard-Envelope des Katalogs. apiVersion: aggrega.ai/v1beta1 und kind: SchemaLibrary kennzeichnen die Entitätsart; metadata.name ist ein PascalCase-Bezeichner; metadata.version folgt strikt der semantischen Versionierung. Der Inhalt der Bibliothek liegt unter spec: spec.schemas ist erforderlich (die Bibliothek muss mindestens einen Eintrag deklarieren), und spec.templates ist optional (nur vorhanden, wenn die Bibliothek parametrisierte Helfer verwendet).
apiVersion: aggrega.ai/v1beta1kind: SchemaLibrarymetadata: name: WebPrimitives version: 1.0.0spec: schemas: URL: type: string pattern: "^https?://" HTTPMethod: type: string enum: [GET, POST, PUT, PATCH, DELETE]Schemaeinträge verfassen
Schemaeinträge werden in einer von drei Formen verfasst. Die Kompaktform ist die Standardoberfläche für kurze, gängige Formen — type, pattern, enum, min, max und ähnliche einzeilige Einschränkungen. YAML in JSON Schema 2020-12 ist die gleichrangige Authoring-Option für Einträge, die die volle Oberfläche von JSON Schema benötigen (Kompositions-Schlüsselwörter, bedingte Form, komplexe $defs). Beide innerhalb eines einzelnen Eintrags zu mischen, wird über den knotenweisen Dispatch nach Inhaltsform des Kompaktform-Compilers unterstützt; der Ausweg $jsonschema: bettet an jedem Knoten vollständige Inhalte in JSON Schema ein, wenn die Kompaktform die Absicht nicht ausdrücken kann.
Ein format in einem Eintrag prüft, was es in jedem Schema prüft: Es benennt eines von email, uri, hostname, ipv4, ipv6, uuid, date-time und date, und ein Wert, den ein Konsument für das Feld liefert, wird abgelehnt, sofern er nicht dieses Format hat — siehe vocabulary/compact-form-authoring.md. Ein Eintrag, der ein anderes Format benennt — password eingeschlossen —, wird beim Laden der Bibliothek abgelehnt, sodass ein katalogweites aggrega validate ihn ablehnt, unabhängig davon, ob bereits etwas auf ihn verweist, wobei Bibliothek, Eintrag und Name genannt und die unterstützten Formate aufgelistet werden, und ein Build oder Pull, dessen Release die Bibliothek erreicht, hält daran an. Ein Eintrag, der auf eine andere Bibliothek verweist, wird dort beurteilt, wo eine Säule einer Component oder eines Feature ihn konsumiert. Ein Feld, das geheimes Material enthält, deklariert sensitive: true statt eines Formats.
Templates und $instantiate:
Bibliotheken mit umfangreicher wiederholter Struktur deklarieren parametrisierte Helfer unter spec.templates. Ein Template trägt eine $params:-Map (benannte, typisierte Parameterdeklarationen) sowie einen Body (Kompaktform oder Inhalt in JSON Schema, der die Parameter als skalare Token $<paramName> referenziert). Schemaeinträge instanziieren Templates über $instantiate: + $args:-Bindungen; die Substitutions-Engine ersetzt die Parameter-Platzhalter durch literale Skalarwerte und erzeugt den Body des aufgelösten Eintrags.
spec: schemas: LivenessProbe: $instantiate: ProbeTemplate $args: port: 8080 path: /healthz ReadinessProbe: $instantiate: ProbeTemplate $args: port: 8081 path: /ready templates: ProbeTemplate: $params: port: type: integer path: type: string type: object properties: port: type: integer const: $port path: type: string const: $pathDie Substitution betrifft nur literale Skalare. Die Substitutions-Engine interpretiert keine Go-Template-Syntax, wertet keine Bedingungen aus und führt keine Schleifen aus. Autoren, die ausdrucksstärkere Helfer benötigen, setzen Components oder Features zusammen, die die Bibliothekseinträge mit eigener Variation konsumieren.
Namenskonventionen
Bibliotheksnamen, Schlüssel von Schemaeinträgen und Template-Namen folgen PascalCase. Das JSON Schema des Entitäts-Envelope setzt die Konvention an drei Stellen über Muster-Einschränkungen durch:
metadata.nameentspricht^[A-Z][A-Za-z0-9]*$.- Schlüssel der Map
spec.schemasentsprechen überpropertyNamesdemselben Muster. - Schlüssel der Map
spec.templatesentsprechen überpropertyNamesdemselben Muster.
Eine SchemaLibrary mit einem Nicht-PascalCase-Schlüssel in spec.schemas oder spec.templates besteht die Envelope-Validierung beim Laden des Workspace nicht. Die Durchsetzung auf Envelope-Ebene ist tragend: Schlüssel von Schemaeinträgen erscheinen in kanonischen $id-URIs (#/schemas/<name>); Template-Namen verweisen bei der Instanziierung in kanonische URIs. Nicht-PascalCase-Schlüssel beim Laden abzufangen, verhindert, dass sie sich durch das Katalog-Ökosystem verbreiten.
Parameternamen innerhalb der $params:-Map eines Templates sind Template-lokal — sie erscheinen nicht in kanonischen $id-URIs und unterliegen auf Envelope-Ebene keiner Muster-Einschränkung. Autoren folgen der Namenskonvention, die zu den Parametern des Templates passt; port, path, intervalSec und ähnliche kleingeschriebene Parameternamen sind typisch.
Die einheitliche Benennung auf Bibliotheks-, Schema- und Template-Ebene macht Referenzbezeichner gut lesbar: WebPrimitives#/schemas/URL erschließt sich auf einen Blick.
Zur Semantik der dokumentübergreifenden $ref:-Auflösung — wie $ref: über SchemaLibrary-Grenzen hinweg aufgelöst wird, die Syntaxunterscheidung bei required: für Konsumenten mit $ref:, die Kettenexpansion von Bibliothek zu Bibliothek und das Verhalten, bei dem der Konsument die Bibliothek einschränkt — siehe vocabulary/cross-document-ref.md.
Auf Bibliothekseinträge verweisen
Autoren von Component / Feature verweisen auf einen Bibliothekseintrag über seine Identität — die Form mit bloßem Namen <Library>#/schemas/<name>:
# Inside a Component schema:spec: schema: values: healthCheck: $ref: "WebPrimitives#/schemas/URL"Der Bibliotheksname wird gegen den aufgelösten Katalog aufgelöst; das Fragment #/schemas/<name> wählt den Eintrag aus. Eine Referenz trägt keinen Registry-Host; ein Autor kann eine optionale Mindestversion als <Library>:<version>#/schemas/<name> angeben (das Versionstrennzeichen ist :, passend zu den recipe/feature-Zuordnungen und dem Lockfile-Pin), doch die aufgelöste Version liefert das Lockfile pro Release, das jede konsumierte Bibliothek nach Name + Version + Inhalts-Digest festlegt. Eine Referenz, die einen Registry-Host trägt — eine Form oci://<host>/… —, wird beim Kompilieren mit einer Diagnose abgelehnt, die den Autor zur Identitätsform lenkt, sodass ein physischer Registry-Ort nie in den verfassten Quelltext gelangt. Von wo die Bytes der Bibliothek ausgeliefert werden (ein lokales Katalogverzeichnis, der Inhalts-Cache oder eine entfernte Registry), ist Sache des Resolvers und wird zur Auflösungszeit gebunden; das Verlagern einer Registry ist eine Änderung der Resolver-Konfiguration, keine Änderung des Quelltexts.
Verbotene Schlüsselwörter von JSON Schema
Die Schlüsselwörter $dynamicAnchor und $dynamicRef von JSON Schema 2020-12 sind in SchemaLibrary-Einträgen verboten. Der SchemaLibrary-Parser durchsucht beim Laden des Workspace sowohl Schemaeinträge als auch Template-Bodies; der Veröffentlichungs-Linter wendet zur Veröffentlichungszeit eine redundante Schutzprüfung an; die Instanziierungs-Engine durchsucht den aufgelösten Body nach der Parametersubstitution erneut, sodass ein Template, das verbotene Schlüsselwörter über Parameterwerte einschleust, dennoch fehlschlägt. Die drei Prüfungen zusammen schließen den Weg der statischen Einführung (literales $dynamicAnchor in einem Schemaeintrag oder Template-Body), den Weg der parametrischen Einführung (ein $args:-Wert, der $dynamicRef enthält) und den Umgehungsweg über externe Werkzeuge (die Schutzprüfung zur Veröffentlichungszeit fängt alles ab, was den Parser übersprungen hat).
Wenn die Ablehnung greift, nennt der Fehler das betreffende Schlüsselwort und den Dateipfad. Autoren sehen den Fehler bereits beim Verfassen statt bei der ersten Instanziierung; Template-Bodies sind von der Prüfung beim Laden nicht ausgenommen.
Die Semantik dynamischer Referenzen koppelt sich auf eine Weise an die Auswertung zur Laufzeit, die den Determinismusvertrag des Compilers zur Kompilierzeit bricht. Autoren, die Verhalten mit dynamischen Referenzen benötigen, strukturieren das Schema so um, dass es die statische $ref-Auflösung verwendet; die Prüfung kennt keine Ausnahme.
Einordnung in die Tiers
SchemaLibrary ist Stufe 3 im Dokumentationsmodell der Entitätsstufen — optional für Kataloge, die Component-übergreifende Schemawiederverwendung benötigen. Kataloge ohne wiederholte Schemainhalte werden ohne jede SchemaLibrary-Entität ausgeliefert; die Stufenkennzeichnung signalisiert für die Navigation in der Dokumentation „fortgeschritten; überspringen, wenn nicht benötigt“, nicht eine Fähigkeit. Der Compiler behandelt SchemaLibrary einheitlich mit den anderen Katalogentitätsarten: dieselbe Envelope-Validierung beim Laden des Workspace, dieselbe Pipeline für JSON Schema 2020-12 für den Inhalt jedes Eintrags, dieselbe OCI-Veröffentlichungspipeline zum Veröffentlichungszeitpunkt.
Innerhalb von Stufe 3 ist der Mechanismus der parametrischen Helfer spec.templates selbst optional. Bibliotheken mit umfangreicher wiederholter Struktur (ein Probe-Template, parametrisiert über Port + Pfad; ein CORS-Template, parametrisiert über erlaubte Origins; ein TLS-Template, parametrisiert über Zertifikats- + Schlüsselpfade) profitieren von der Wiederverwendung über templates; Bibliotheken mit vielfältigen Einzeleinträgen lassen den Templates-Block ganz weg und verfassen jeden Eintrag inline unter spec.schemas.