Validar documents OSIRIS JSON
La validacio d’OSIRIS JSON ja no es nomes una part implicita de l’especificacio. Ara te un model documentat, un limit canonic del motor i un contracte de CLI pensat per a eines reals.
L’orientacio actual sobre validacio es reparteix en tres documents en esborrany publicats el febrer de 2026: les Directrius de nivells de validacio, la guia interna de Toolbox Core i la guia de Toolbox CLI. En conjunt, defineixen com s’han de validar els documents OSIRIS de manera coherent entre el desenvolupament local, les integracions als editors i les pipelines de CI.
La validacio es mes que un esquema
Una de les decisions mes clares del model de validacio d’OSIRIS es que el JSON Schema per si sol no es suficient.
El projecte defineix la validacio com una pipeline de tres nivells:
- Nivell 1: Estructural la validacio comprova si un document s’ajusta a l’esquema d’OSIRIS
- Nivell 2: Semantic la validacio comprova la integritat del graf, com ara referencies penjants, identificadors duplicats i jerarquies de grups no valides
- Nivell 3: Domini la validacio afegeix orientacio opcional de bones practiques que millora la interoperabilitat sense redefinir que compta com a OSIRIS valid
Aquesta separacio importa. Un document pot ser estructuralment correcte i tot i aixi ser insegur de consumir si no es pot confiar en la seva topologia. OSIRIS tracta aquests casos com problemes diferents i ofereix a les eines una manera mes neta d’informar-los.
Un motor compartit, no validadors en competencia
L’arquitectura de validacio es construeix al voltant d’una sola regla: les eines de referencia no haurien d’inventar la seva propia versio de la veritat.
@osirisjson/core es defineix com el motor de validacio canonic per a l’ecosistema. Es el component que gestiona la pipeline de tres etapes, el model de diagnostics, l’encaminament d’esquemes i la logica de perfils. S’espera que la CLI i les integracions als editors deleguin la validacio a aquest motor compartit en lloc de reimplementar les regles de manera independent.
Aquesta es una decisio arquitectonica forta, i es la correcta. Significa que el mateix document hauria de produir el mateix resultat tant si es comprova a CI, com si s’inspecciona en un editor o es processa amb una eina de nivell superior construida sobre la toolbox d’OSIRIS.
Els diagnostics son el contracte
Una altra decisio important de disseny es que OSIRIS tracta els diagnostics com una interficie estructurada, no com una sortida de text solta.
Les troballes de validacio es construeixen al voltant de codis V-* estables, severitats, missatges i rutes JSON Pointer. A la practica, aixo significa:
- El codi es el fet estable
- La severitat es una politica determinada pel perfil actiu
- El missatge pot evolucionar per guanyar claredat sense trencar les eines
Aquesta es la diferencia entre una validacio que nomes es visible i una validacio que realment es pot automatitzar. Les pipelines de CLI, els textos emergents als editors, els informes llegibles per maquines i les futures correccions rapides depenen d’aquesta separacio.
Pensat per al treball local i la CI
La guia de CLI es especialment pragmatica. La validacio esta pensada per ser determinista, prioritzar el treball sense connexio i funcionar be a la shell.
El contracte documentat espera:
- suport de
stdinper compondre pipelines - sortida JSON llegible per maquines per a CI i automatitzacio
- codis de sortida estables que separen les fallades de validacio de les fallades operatives
- resolucio d’esquemes sense connexio usant esquemes inclosos o en cache en lloc de descarregues en viu des de la xarxa
Els perfils son igualment practics:
basicse centra nomes en comprovacions estructuralsdefaultexecuta validacio estructural i semantica per al treball diaristrictafegeix comprovacions de domini seleccionades per a publicacions de productores i portes de CI
Aixo dona a OSIRIS un model de validacio que pot escalar des de la retroalimentacio a l’editor fins a la validacio per lots sense canviar el significat de les regles subjacents.
Per que aixo importa ara
Sense un model de validacio compartit, un estandard obert comenca a desviar-se gairebe immediatament. Cada eina acaba amb suposicions diferents, severitats diferents, comportaments de parser diferents i, finalment, definicions diferents del que significa “valid”.
Aquestes directrius de validacio i de la toolbox son importants perque intenten aturar aquesta deriva abans que comenci. Fan que la validacio sigui reproduible, ensenyable i portable a tot l’ecosistema. Igual d’important, mantenen la privacitat i la previsibilitat dins de l’abast exigint un comportament de validacio local i evitant la dependencia de la xarxa durant les comprovacions.
Llegir l’orientacio de validacio
Els documents actuals sobre validacio i toolbox es publiquen com a orientacio en esborrany: