Validació d’OSIRIS JSON

La validació d’OSIRIS està dissenyada per ser local-first, determinística i utilitzable tant en fluxos de treball interactius com en pipelines de CI.

El camí canònic de validació és el paquet OSIRIS CLI:

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

Què comprova el validator

La validació d’OSIRIS està intencionadament estructurada en capes:

Level 1: Structural Valida la conformitat amb JSON Schema: camps obligatoris, tipus de camp, enums, formats i l’estructura de nivell superior.
Level 2: Semantic Valida la consistència interna del graf: IDs duplicats, referències trencades, jerarquies de grup no vàlides i problemes d’integritat similars.
Level 3: Domain Executa comprovacions opcionals de bones pràctiques que milloren la interoperabilitat i la qualitat sense redefinir què es considera un document OSIRIS JSON vàlid.

Perfils de validació

La CLI està dissenyada al voltant de tres perfils:

basic Executa només Level 1. Feu-lo servir per a comprovacions estructurals ràpides.
default Executa Level 1 + Level 2. Aquest és el perfil de validació previst per al dia a dia.
strict Executa Level 1 + Level 2 + regles seleccionades de Level 3. Aquest és el perfil recomanat per a CI i release gates.

Instal·lació amb NPM

Executar sense instal·lació global

npx @osirisjson/cli validate ./example.json

Aquesta és la manera recomanada d’executar el validator en CI o quan no voleu una instal·lació global.

Instal·lar globalment

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

Afegir com a dependència del projecte

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

Ordres de validació

Validar un fitxer

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

Validar diversos fitxers

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

Validar un directori

S’expandeix a tots els fitxers .json del directori (no recursiu):

npx @osirisjson/cli validate ./exports/

Validar des de l’entrada estàndard

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

Validar amb el perfil strict

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

Emetre JSON llegible per màquina

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

Sobreescriure la resolució de l’schema

Feu servir un fitxer schema local en lloc del que ve inclòs:

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

Sortida detallada

Mostra diagnòstics detallats, inclosos fragments d’origen (només en format de text):

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

Controlar la sortida amb color

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

Codis de sortida esperats

El contracte de la CLI defineix codis de sortida estables:

0 = success La validació s’ha executat i no s’ha emès cap diagnòstic error.
1 = validation error La validació s’ha executat i s’ha emès almenys un diagnòstic error.
2 = operational error La validació no s’ha pogut executar per a una o més entrades a causa de fitxers il·legibles, JSON no vàlid, flags incorrectes o errors previs a la validació similars.

Modes de sortida

La CLI està dissenyada per admetre dos formats de sortida:

Text llegible per humans

Sortida de terminal predeterminada per a ús local:

camí del fitxer
línia/columna quan estigui disponible
severitat
codi de diagnòstic
missatge llegible per humans

JSON llegible per màquina

Feu servir --format json per a CI, scripts, dashboards o eines downstream.

Per a una sola entrada, la CLI emet un objecte JSON amb format llegible a stdout. Per a múltiples entrades, emet NDJSON (un objecte JSON compacte per línia).

Local-first i offline-first per disseny

La validació d’OSIRIS JSON està pensada per executar-se localment per defecte.

La CLI MUST NOT recuperar dades de la xarxa durant la validació.
$schema es tracta com una pista de versió, no com una URL activa que s’hagi de recuperar.
Es fan servir schemas inclosos o en memòria cau per a la resolució.

Això és important perquè els documents de topologia d’infraestructura MAY contenir informació de disseny sensible, fins i tot quan ja se n’han eliminat els secrets.

Ús recomanat per rol

Producers

Valideu abans de publicar qualsevol document:

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

Consumers i pipelines de CI

Valideu-lo en rebre’l abans de processar o emmagatzemar el document.

Editors i integracions

Feu servir el mateix comportament del motor que la CLI delegant la validació a @osirisjson/core.