OSIRIS-JSON-Dokumente validieren
Die Validierung von OSIRIS JSON ist nicht mehr nur ein impliziter Teil der Spezifikation. Sie verfugt jetzt uber ein dokumentiertes Modell, eine kanonische Abgrenzung der Engine und einen CLI-Vertrag, der fur echte Werkzeuge ausgelegt ist.
Die aktuellen Validierungsrichtlinien verteilen sich auf drei im Februar 2026 veroffentlichte Entwurfsdokumente: die Leitlinien zu den Validierungsstufen, den internen Leitfaden fur Toolbox Core und den Leitfaden fur Toolbox CLI. Zusammen definieren sie, wie OSIRIS-Dokumente konsistent uber lokale Entwicklung, Editor-Integrationen und CI-Pipelines hinweg validiert werden sollen.
Validierung ist mehr als ein Schema
Eine der klarsten Entscheidungen im Validierungsmodell von OSIRIS ist, dass JSON Schema allein nicht ausreicht.
Das Projekt definiert Validierung als eine dreistufige Pipeline:
- Ebene 1: Strukturell die Validierung pruft, ob ein Dokument dem OSIRIS-Schema entspricht
- Ebene 2: Semantisch die Validierung pruft die Graphintegritat, etwa verwaiste Referenzen, doppelte IDs und unzulassige Gruppenhierarchien
- Ebene 3: Domanenspezifisch die Validierung erganzt optionale Best-Practice-Leitlinien, die die Interoperabilitat verbessern, ohne neu zu definieren, was als gultiges OSIRIS zahlt
Diese Trennung ist wichtig. Ein Dokument kann strukturell korrekt sein und trotzdem unsicher in der Nutzung, wenn seiner Topologie nicht vertraut werden kann. OSIRIS behandelt das als unterschiedliche Probleme und gibt Werkzeugen eine klarere Moglichkeit, sie zu melden.
Eine gemeinsame Engine, keine konkurrierenden Validatoren
Die Validierungsarchitektur ist um eine einzige Regel herum aufgebaut: Referenzwerkzeuge sollen nicht ihre eigene Version der Wahrheit erfinden.
@osirisjson/core ist als kanonische Validierungs-Engine fur das Okosystem definiert. Diese Komponente verantwortet die dreistufige Pipeline, das Diagnosemodell, das Schema-Routing und die Profillogik. Von der CLI und den Editor-Integrationen wird erwartet, dass sie die Validierung an diese gemeinsame Engine delegieren, statt Regeln unabhangig neu zu implementieren.
Das ist eine starke architektonische Entscheidung, und es ist die richtige. Sie bedeutet, dass dasselbe Dokument zum selben Ergebnis fuhren sollte, egal ob es in CI gepruft, in einem Editor untersucht oder von einem hoheren Werkzeug verarbeitet wird, das auf der OSIRIS-Toolbox aufbaut.
Diagnosen sind der Vertrag
Eine weitere wichtige Designentscheidung ist, dass OSIRIS Diagnosen als strukturierte Schnittstelle behandelt und nicht als lose Textausgabe.
Validierungsbefunde bauen auf stabilen V-*-Codes, Schweregraden, Meldungen und JSON-Pointer-Pfaden auf. In der Praxis bedeutet das:
- Der Code ist die stabile Tatsache
- Der Schweregrad ist Richtlinie, geformt durch das aktive Profil
- Die Meldung kann sich zur besseren Verstandlichkeit weiterentwickeln, ohne Werkzeuge zu brechen
Das ist der Unterschied zwischen einer Validierung, die nur sichtbar ist, und einer Validierung, die tatsachlich automatisiert werden kann. CLI-Pipelines, Hover-Hinweise in Editoren, maschinenlesbare Berichte und kunftige Quick Fixes hangen alle von dieser Trennung ab.
Fur lokale Arbeit und CI gebaut
Der CLI-Leitfaden ist besonders pragmatisch. Die Validierung ist darauf ausgelegt, deterministisch, offline-first und shell-freundlich zu sein.
Der dokumentierte Vertrag erwartet:
stdin-Unterstutzung fur die Zusammensetzung von Pipelines- maschinenlesbare JSON-Ausgabe fur CI und Automatisierung
- stabile Exit-Codes, die Validierungsfehler von betrieblichen Fehlern trennen
- Offline-Auflosung von Schemas mit gebundelten oder zwischengespeicherten Schemas statt Live-Abrufen uber das Netzwerk
Die Profile sind ebenso praxisnah:
basickonzentriert sich nur auf strukturelle Prufungendefaultfuhrt strukturelle und semantische Validierung fur die tagliche Arbeit ausstrictfugt ausgewahlte Domanenprufungen fur Producer-Releases und CI-Gates hinzu
Damit bekommt OSIRIS ein Validierungsmodell, das von Editor-Feedback bis zu Batch-Validierung skalieren kann, ohne die Bedeutung der zugrunde liegenden Regeln zu verandern.
Warum das jetzt wichtig ist
Ohne ein gemeinsames Validierungsmodell beginnt ein offener Standard fast sofort auseinanderzulaufen. Jedes Werkzeug endet mit anderen Annahmen, anderen Schweregraden, anderem Parserverhalten und schliesslich anderen Definitionen davon, was “gultig” bedeutet.
Diese Leitlinien zu Validierung und Toolbox sind wichtig, weil sie versuchen, diese Drift zu stoppen, bevor sie beginnt. Sie machen Validierung reproduzierbar, vermittelbar und im gesamten Okosystem portabel. Genauso wichtig ist, dass sie Datenschutz und Vorhersehbarkeit im Blick behalten, indem sie lokales Validierungsverhalten verlangen und Netzwerkabhangigkeit wahrend der Prufungen vermeiden.
Die Validierungsleitlinien lesen
Die aktuellen Dokumente zu Validierung und Toolbox sind als Entwurf veroffentlicht: