OSIRIS JSON-Validierung

Die OSIRIS-Validierung ist darauf ausgelegt, local-first, deterministisch und sowohl in interaktiven Workflows als auch in CI-Pipelines nutzbar zu sein.

Der kanonische Validierungspfad ist das Paket OSIRIS CLI:

Package name: @osirisjson/cli
Canonical engine behind the CLI: @osirisjson/core
Primary command: validate

Was der validator prüft

Die OSIRIS-Validierung ist bewusst schichtweise aufgebaut:

Level 1: Structural Validiert die Konformität mit JSON Schema: Pflichtfelder, Feldtypen, enums, Formate und die Struktur auf oberster Ebene.
Level 2: Semantic Validiert die interne Graph-Konsistenz: doppelte IDs, fehlerhafte Referenzen, ungültige Gruppenhierarchien und ähnliche Integritätsprobleme.
Level 3: Domain Führt optionale Best-Practice-Prüfungen aus, die Interoperabilität und Qualität verbessern, ohne neu zu definieren, was als gültiges OSIRIS-JSON-Dokument gilt.

Validierungsprofile

Die CLI ist auf drei Profile ausgelegt:

basic Führt nur Level 1 aus. Verwenden Sie es für schnelle strukturelle Prüfungen.
default Führt Level 1 + Level 2 aus. Dies ist das vorgesehene Validierungsprofil für den Alltag.
strict Führt Level 1 + Level 2 + ausgewählte Regeln aus Level 3 aus. Dies ist das empfohlene Profil für CI und Release-Gates.

NPM-Installation

Ohne globale Installation ausführen

npx @osirisjson/cli validate ./example.json

Dies ist die empfohlene Methode, um den validator in CI auszuführen oder wenn Sie keine globale Installation möchten.

Global installieren

npm install -g @osirisjson/cli
osirisjson validate ./example.json

Als Projektabhängigkeit hinzufügen

npm install --save-dev @osirisjson/cli
npx @osirisjson/cli validate ./example.json

Validierungsbefehle

Eine Datei validieren

npx @osirisjson/cli validate osiris-document-example.json

Mehrere Dateien validieren

npx @osirisjson/cli validate osiris-document-example-01.json osiris-document-example-02.json

Ein Verzeichnis validieren

Wird auf alle .json-Dateien im Verzeichnis erweitert (nicht rekursiv):

npx @osirisjson/cli validate ./exports/

Aus der Standardeingabe validieren

cat osiris-document-example.json | npx @osirisjson/cli validate -

Mit dem strict-Profil validieren

npx @osirisjson/cli validate --profile strict ./exports/

Maschinenlesbares JSON ausgeben

npx @osirisjson/cli validate --profile strict --format json ./exports/

Schema-Auflösung überschreiben

Verwenden Sie statt der mitgelieferten Datei eine lokale schema-Datei:

npx @osirisjson/cli validate --schema ./osiris.schema.json topology.json

Ausführliche Ausgabe

Zeigt detaillierte Diagnosen einschließlich Quelltextauszügen an (nur Textformat):

npx @osirisjson/cli validate --verbose topology.json

Farbausgabe steuern

npx @osirisjson/cli validate --color never ./exports/

Erwartete Exit-Codes

Der CLI-Vertrag definiert stabile Exit-Codes:

0 = success Die Validierung wurde ausgeführt und es wurden keine error-Diagnosen ausgegeben.
1 = validation error Die Validierung wurde ausgeführt und es wurde mindestens eine error-Diagnose ausgegeben.
2 = operational error Die Validierung konnte für eine oder mehrere Eingaben nicht ausgeführt werden, weil Dateien nicht lesbar waren, JSON ungültig war, flags fehlerhaft waren oder ähnliche Vorvalidierungsfehler auftraten.

Ausgabemodi

Die CLI ist darauf ausgelegt, zwei Ausgabeformate zu unterstützen:

Menschenlesbarer Text

Standardmäßige Terminalausgabe für die lokale Nutzung:

Dateipfad
Zeile/Spalte, wenn verfügbar
Schweregrad
Diagnosecode
menschenlesbare Meldung

Maschinenlesbares JSON

Verwenden Sie --format json für CI, Skripte, Dashboards oder nachgelagerte Werkzeuge.

Für eine einzelne Eingabe gibt die CLI ein formatiertes JSON-Objekt an stdout aus. Für mehrere Eingaben gibt sie NDJSON aus (ein kompaktes JSON-Objekt pro Zeile).

Local-first und offline-first by design

Die OSIRIS-JSON-Validierung ist standardmäßig für die lokale Ausführung vorgesehen.

Die CLI MUST NOT während der Validierung Daten aus dem Netzwerk abrufen.
$schema wird als Versionshinweis behandelt, nicht als Live-URL, die abgerufen werden soll.
Für die Auflösung werden mitgelieferte oder zwischengespeicherte schemas verwendet.

Das ist wichtig, weil Infrastruktur-Topologiedokumente MAY sensible Designinformationen enthalten, selbst wenn Geheimnisse bereits entfernt wurden.

Empfohlene Nutzung nach Rolle

Producers

Vor der Veröffentlichung eines Dokuments validieren:

npx @osirisjson/cli validate --profile strict output.json

Consumers und CI-Pipelines

Validieren Sie das Dokument beim Eingang, bevor Sie es verarbeiten oder speichern.

Editoren und Integrationen

Verwenden Sie dasselbe Engine-Verhalten wie die CLI, indem Sie die Validierung an @osirisjson/core delegieren.