Validation d’OSIRIS JSON

La validation d’OSIRIS est conçue pour être local-first, déterministe et utilisable à la fois dans des workflows interactifs et dans des pipelines CI.

Le chemin canonique de validation est le package OSIRIS CLI :

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

Ce que vérifie le validator

La validation d’OSIRIS est volontairement organisée en couches :

Level 1: Structural Valide la conformité à JSON Schema : champs obligatoires, types de champs, enums, formats et structure de premier niveau.
Level 2: Semantic Valide la cohérence interne du graphe : ID dupliqués, références cassées, hiérarchies de groupes invalides et problèmes d’intégrité similaires.
Level 3: Domain Exécute des vérifications optionnelles de bonnes pratiques qui améliorent l’interopérabilité et la qualité sans redéfinir ce qui est considéré comme un document OSIRIS JSON valide.

Profils de validation

La CLI est conçue autour de trois profils :

basic Exécute uniquement Level 1. Utilisez-le pour des vérifications structurelles rapides.
default Exécute Level 1 + Level 2. C’est le profil de validation attendu au quotidien.
strict Exécute Level 1 + Level 2 + règles sélectionnées de Level 3. C’est le profil recommandé pour CI et les release gates.

Installation NPM

Exécuter sans installation globale

npx @osirisjson/cli validate ./example.json

C’est la manière recommandée d’exécuter le validator en CI ou lorsque vous ne voulez pas d’installation globale.

Installer globalement

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

Ajouter comme dépendance du projet

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

Commandes de validation

Valider un fichier

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

Valider plusieurs fichiers

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

Valider un répertoire

S’étend à tous les fichiers .json du répertoire (non récursif) :

npx @osirisjson/cli validate ./exports/

Valider depuis l’entrée standard

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

Valider avec le profil strict

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

Émettre un JSON lisible par machine

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

Remplacer la résolution du schema

Utilisez un fichier schema local à la place de celui fourni :

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

Sortie détaillée

Affiche des diagnostics détaillés, y compris des extraits de source (format texte uniquement) :

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

Contrôler la sortie en couleur

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

Codes de sortie attendus

Le contrat de la CLI définit des codes de sortie stables :

0 = success La validation s’est exécutée et aucun diagnostic error n’a été émis.
1 = validation error La validation s’est exécutée et au moins un diagnostic error a été émis.
2 = operational error La validation n’a pas pu s’exécuter pour une ou plusieurs entrées en raison de fichiers illisibles, de JSON invalide, de flags incorrects ou d’échecs similaires avant validation.

Modes de sortie

La CLI est conçue pour prendre en charge deux formats de sortie :

Texte lisible par un humain

Sortie terminal par défaut pour un usage local :

chemin du fichier
ligne/colonne lorsque disponible
sévérité
code de diagnostic
message lisible par un humain

JSON lisible par machine

Utilisez --format json pour CI, les scripts, les tableaux de bord ou les outils downstream.

Pour une seule entrée, la CLI émet un objet JSON formaté de manière lisible vers stdout. Pour plusieurs entrées, elle émet du NDJSON (un objet JSON compact par ligne).

Local-first et offline-first par conception

La validation d’OSIRIS JSON est conçue pour s’exécuter localement par défaut.

La CLI MUST NOT récupérer de données depuis le réseau pendant la validation.
$schema est traité comme une indication de version, et non comme une URL active à récupérer.
Des schemas fournis ou mis en cache sont utilisés pour la résolution.

Cela est important car les documents de topologie d’infrastructure MAY contenir des informations de conception sensibles, même lorsque les secrets ont déjà été supprimés.

Utilisation recommandée par rôle

Producers

Validez avant de publier tout document :

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

Consumers et pipelines CI

Validez à réception avant de traiter ou de stocker le document.

Éditeurs et intégrations

Utilisez le même comportement du moteur que la CLI en déléguant la validation à @osirisjson/core.