OSIRIS JSON Architekturleitlinien

OSIRIS JSON verfügt jetzt über ein eigenes Architekturdokument für Beitragende, die rund um den Standard entwickeln.

Veröffentlicht am 4. Februar 2026, definieren die OSIRIS JSON Architecture Development Guidelines, wie sich das Ökosystem über das Spezifikations-Repository, Toolbox-Pakete, Producers und Editor-Integrationen hinweg entwickeln soll. Dies ist keine zweite Spezifikation. Es ist der operative Bauplan, um Implementierungen beim Wachstum des Projekts aufeinander abgestimmt zu halten.

Warum dieses Dokument wichtig ist

Offene Standards fragmentieren oft dann, wenn jedes Werkzeug, jede Erweiterung oder jeder Producer beginnt, das Format eigenständig zu interpretieren. Die Architekturleitlinien sollen genau dieses Ergebnis frühzeitig verhindern.

Das Dokument macht zwei Positionen ausdrücklich klar:

• Die OSIRIS-Spezifikation und das Schema bleiben die einzige verbindliche Quelle für das Format
• @osirisjson/core ist die kanonische Implementierung für Validierungsverhalten und Diagnoseformatierung

Das ist wichtig, weil dasselbe OSIRIS-Dokument sich in CI, in der CLI und innerhalb von Editor-Integrationen konsistent verhalten sollte. Das Projekt zieht eine klare Grenze gegen duplizierte Validatoren, inkompatible Forks der Regellogik und Repository-Wildwuchs, der als Flexibilität getarnt ist.

Die zentrale architektonische Richtung

Die Leitlinien formalisieren eine klare Trennung der Verantwortlichkeiten im gesamten Ökosystem:

• osiris definiert die kanonische Spezifikation, das Schema, Beispiele und Entwicklungsleitlinien
• osiris-toolbox beherbergt die gemeinsamen TypeScript-Pakete, darunter @osirisjson/core, @osirisjson/sdk und @osirisjson/cli
• osiris-producers enthält anbieterspezifische Producers und das Go Producer SDK
• osiris-editor-integrations nutzt die gemeinsame Validierungs-Engine, anstatt sie neu zu implementieren

Eine der wichtigsten Regeln im Dokument ist die “forbidden direction”-Regel für Abhängigkeiten. Validierungslogik fließt nach unten in den gemeinsamen Core; sie wird nicht nach oben in Editoren, Producers oder Kommando-Wrapper kopiert. Genau dieses Design hält das Ökosystem portabel und verhindert Split-Brain-Verhalten zwischen Werkzeugen.

Mehr als nur Repository-Struktur

Die Architekturleitlinien sind auch der Ort, an dem OSIRIS definiert, wie sich das System unter realem Implementierungsdruck verhalten soll.

Sie beschreiben:

• Eine dreistufige Validierungspipeline: strukturelle, semantische und domänenspezifische Prüfungen
• Ein stabiles Diagnosemodell, das auf Codes, Schweregraden, Meldungen und Dokumentpfaden basiert
• Deterministische Identitätsrichtlinien, damit Ressourcen, Gruppen und Verbindungen über Exporte hinweg diff-freundlich bleiben
• JSON-Dateikonventionen, die darauf abzielen, unnötige Änderungen zu reduzieren und Editor-Werkzeuge zu verbessern
• Sicherheits- und Redaktionsanforderungen, einschließlich eines strikten Verbots von Zugangsdaten und Geheimnissen innerhalb von OSIRIS-Dokumenten

Hier erklärt das Projekt auch eine pragmatische Plattformaufteilung: Die kanonische Toolbox wird in TypeScript gebaut und über NPM verteilt, um maximale Wiederverwendung über CLI und Editor-Integrationen hinweg zu ermöglichen, während First-Party-Producers in Go empfohlen werden, weil Erfassung, Transport, Parallelität und anbieterspezifische Datensammlung andere Laufzeitanforderungen haben.

Was Beitragende daraus mitnehmen sollten

Die Hauptaussage des Architekturdokuments ist einfach: OSIRIS ist als Ökosystem entworfen, nicht nur als Schema-Datei.

Wenn an einem Producer, einer Validierungsregel, einer CLI-Funktion oder einer Editor-Integration gearbeitet wird, machen die Leitlinien klar, wohin diese Arbeit gehört, welche Verträge stabil sind und welche Abkürzungen nicht akzeptabel sind. Das macht das Dokument besonders wichtig für frühe Beitragende, weil es Grenzen festlegt, bevor versehentliche Duplizierung zu Projektschulden wird.

Die Leitlinien lesen

Die Architekturleitlinien sind derzeit als draft-Dokument veröffentlicht, erstellt am 4. Februar 2026 und überarbeitet am 11. Februar 2026:

• Die OSIRIS Architecture Development Guidelines lesen
• Die OSIRIS JSON v1.0 Spezifikation lesen
• Die Implementierungsleitlinien lesen
• Das Validierungskapitel lesen
• Das Kapitel zu Versionierung und Kompatibilität lesen
• Das Projekt-Repository ansehen

Banner icon author Reyda Dönmez