Validazione di OSIRIS JSON

La validazione di OSIRIS è progettata per essere local-first, deterministica e utilizzabile sia nei flussi di lavoro interattivi sia nelle pipeline CI.

Il percorso canonico di validazione è il pacchetto OSIRIS CLI:

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

Cosa controlla il validator

La validazione di OSIRIS è intenzionalmente strutturata a livelli:

Level 1: Structural Valida la conformità a JSON Schema: campi obbligatori, tipi di campo, enums, formati e struttura di primo livello.
Level 2: Semantic Valida la coerenza interna del grafo: ID duplicati, riferimenti interrotti, gerarchie di gruppo non valide e problemi di integrità simili.
Level 3: Domain Esegue controlli opzionali di best practice che migliorano interoperabilità e qualità senza ridefinire cosa debba essere considerato un documento OSIRIS JSON valido.

Profili di validazione

La CLI è progettata attorno a tre profili:

basic Esegue solo Level 1. Usalo per controlli strutturali rapidi.
default Esegue Level 1 + Level 2. Questo è il profilo di validazione previsto per l’uso quotidiano.
strict Esegue Level 1 + Level 2 + regole selezionate di Level 3. Questo è il profilo consigliato per CI e release gates.

Installazione con NPM

Eseguire senza installazione globale

npx @osirisjson/cli validate ./example.json

Questo è il modo consigliato per eseguire il validator in CI o quando non vuoi un’installazione globale.

Installare globalmente

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

Aggiungere come dipendenza di progetto

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

Comandi di validazione

Validare un file

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

Validare più file

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

Validare una directory

Si espande a tutti i file .json nella directory (non ricorsivo):

npx @osirisjson/cli validate ./exports/

Validare dallo standard input

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

Validare con il profilo strict

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

Emettere JSON leggibile dalle macchine

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

Sostituire la risoluzione dello schema

Usa un file schema locale invece di quello incluso:

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

Output dettagliato

Mostra diagnostiche dettagliate, inclusi snippet del sorgente (solo formato testuale):

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

Controllare l’output a colori

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

Codici di uscita previsti

Il contratto della CLI definisce codici di uscita stabili:

0 = success La validazione è stata eseguita e non è stata emessa alcuna diagnostica error.
1 = validation error La validazione è stata eseguita ed è stata emessa almeno una diagnostica error.
2 = operational error La validazione non ha potuto essere eseguita per uno o più input a causa di file illeggibili, JSON non valido, flags errati o guasti simili precedenti alla validazione.

Modalità di output

La CLI è progettata per supportare due formati di output:

Testo leggibile dall’uomo

Output predefinito del terminale per l’uso locale:

percorso del file
riga/colonna quando disponibile
severità
codice diagnostico
messaggio leggibile dall’uomo

JSON leggibile dalle macchine

Usa --format json per CI, script, dashboard o strumenti downstream.

Per un singolo input, la CLI emette un oggetto JSON formattato in modo leggibile su stdout. Per più input, emette NDJSON (un oggetto JSON compatto per riga).

Local-first e offline-first per progettazione

La validazione di OSIRIS JSON è pensata per essere eseguita localmente per impostazione predefinita.

La CLI MUST NOT recuperare dati dalla rete durante la validazione.
$schema viene trattato come un’indicazione di versione, non come un URL live da recuperare.
Per la risoluzione vengono usati schema inclusi o in cache.

Questo è importante perché i documenti di topologia dell’infrastruttura MAY contenere informazioni di progettazione sensibili, anche quando i segreti sono già stati rimossi.

Utilizzo consigliato per ruolo

Producers

Valida prima di pubblicare qualsiasi documento:

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

Consumers e pipeline CI

Valida alla ricezione prima di elaborare o archiviare il documento.

Editor e integrazioni

Usa lo stesso comportamento del motore della CLI delegando la validazione a @osirisjson/core.