Convalidare documenti OSIRIS JSON
La convalida di OSIRIS JSON non è più soltanto una parte implicita della specifica. Ora dispone di un modello documentato, di un confine canonico del motore e di un contratto CLI progettato per strumenti reali.
Le attuali linee guida sulla convalida sono distribuite in tre documenti in bozza pubblicati a febbraio 2026: le Linee guida sui livelli di convalida, la guida interna di Toolbox Core e la guida di Toolbox CLI. Insieme, definiscono come i documenti OSIRIS debbano essere convalidati in modo coerente tra sviluppo locale, integrazioni negli editor e pipeline CI.
La convalida è più di uno schema
Una delle decisioni più chiare nel modello di convalida di OSIRIS è che il solo JSON Schema non è sufficiente.
Il progetto definisce la convalida come una pipeline a tre livelli:
- Livello 1: Strutturale la convalida verifica se un documento è conforme allo schema OSIRIS
- Livello 2: Semantico la convalida verifica l’integrità del grafo, come riferimenti pendenti, ID duplicati e gerarchie di gruppi non valide
- Livello 3: Dominio la convalida aggiunge linee guida opzionali di buone pratiche che migliorano l’interoperabilità senza ridefinire ciò che conta come OSIRIS valido
Questa separazione è importante. Un documento può essere strutturalmente corretto e comunque non sicuro da consumare se la sua topologia non è affidabile. OSIRIS tratta questi casi come problemi diversi e offre agli strumenti un modo più pulito di segnalarli.
Un motore condiviso, non validatori in competizione
L’architettura della convalida è costruita attorno a una sola regola: gli strumenti di riferimento non dovrebbero inventare una propria versione della verità.
@osirisjson/core è definito come il motore di convalida canonico per l’ecosistema. È il componente che gestisce la pipeline a tre fasi, il modello diagnostico, l’instradamento degli schemi e la logica dei profili. Ci si aspetta che la CLI e le integrazioni negli editor deleghino la convalida a questo motore condiviso invece di reimplementare le regole in modo indipendente.
Questa è una scelta architetturale forte, ed è quella giusta. Significa che lo stesso documento dovrebbe produrre lo stesso risultato sia che venga controllato in CI, ispezionato in un editor o elaborato da uno strumento di livello superiore costruito sulla toolbox OSIRIS.
Le diagnostiche sono il contratto
Un’altra importante scelta progettuale è che OSIRIS tratta le diagnostiche come un’interfaccia strutturata, non come semplice testo libero in output.
I risultati della convalida sono costruiti attorno a codici V-* stabili, livelli di severità, messaggi e percorsi JSON Pointer. In pratica, questo significa:
- Il codice è il fatto stabile
- La severità è una politica modellata dal profilo attivo
- Il messaggio può evolvere per maggiore chiarezza senza rompere gli strumenti
Questa è la differenza tra una convalida semplicemente visibile e una convalida realmente automatizzabile. Pipeline CLI, suggerimenti negli editor, report leggibili dalle macchine e futuri quick fix dipendono tutti da questa separazione.
Progettato per il lavoro locale e la CI
Le linee guida della CLI sono particolarmente pragmatiche. La convalida è progettata per essere deterministica, offline-first e adatta alla shell.
Il contratto documentato prevede:
- supporto a
stdinper la composizione di pipeline - output JSON leggibile dalle macchine per CI e automazione
- exit code stabili che separano i fallimenti di convalida dai fallimenti operativi
- risoluzione offline degli schemi usando schemi inclusi o in cache invece di recuperi live dalla rete
Anche i profili sono pragmatici:
basicsi concentra solo sui controlli strutturalidefaultesegue convalida strutturale e semantica per il lavoro quotidianostrictaggiunge controlli di dominio selezionati per release dei produttori e gate CI
Questo offre a OSIRIS un modello di convalida capace di scalare dal feedback dell’editor alla convalida batch senza cambiare il significato delle regole sottostanti.
Perché questo conta adesso
Senza un modello di convalida condiviso, uno standard aperto inizia quasi subito a deragliare. Ogni strumento finisce con assunzioni diverse, severità diverse, comportamenti diversi del parser e, infine, definizioni diverse di cosa significhi “valido”.
Queste linee guida su convalida e toolbox sono importanti perché cercano di fermare questa deriva prima che inizi. Rendono la convalida riproducibile, insegnabile e portabile nell’intero ecosistema. Altrettanto importante, mantengono privacy e prevedibilità nel perimetro richiedendo un comportamento di convalida locale ed evitando dipendenze di rete durante i controlli.
Leggi le linee guida sulla convalida
Gli attuali documenti su convalida e toolbox sono pubblicati come linee guida in bozza: