Validación de OSIRIS JSON

La validación de OSIRIS está diseñada para ser local-first, determinística y utilizable tanto en flujos de trabajo interactivos como en pipelines de CI.

La ruta canónica de validación es el paquete OSIRIS CLI:

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

Qué comprueba el validator

La validación de OSIRIS está organizada intencionalmente por capas:

Level 1: Structural Valida la conformidad con JSON Schema: campos obligatorios, tipos de campo, enums, formatos y la estructura de nivel superior.
Level 2: Semantic Valida la consistencia interna del grafo: IDs duplicados, referencias rotas, jerarquías de grupo no válidas y problemas de integridad similares.
Level 3: Domain Ejecuta revisiones opcionales de buenas prácticas que mejoran la interoperabilidad y la calidad sin redefinir lo que cuenta como un documento OSIRIS JSON válido.

Perfiles de validación

La CLI está diseñada alrededor de tres perfiles:

basic Ejecuta solo Level 1. Úsalo para revisiones estructurales rápidas.
default Ejecuta Level 1 + Level 2. Este es el perfil de validación esperado para el día a día.
strict Ejecuta Level 1 + Level 2 + reglas seleccionadas de Level 3. Este es el perfil recomendado para CI y release gates.

Instalación con NPM

Ejecutar sin instalación global

npx @osirisjson/cli validate ./example.json

Esta es la forma recomendada de ejecutar el validator en CI o cuando no quieres una instalación global.

Instalar globalmente

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

Agregar como dependencia del proyecto

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

Comandos de validación

Validar un archivo

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

Validar varios archivos

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

Validar un directorio

Se expande a todos los archivos .json del directorio (no recursivo):

npx @osirisjson/cli validate ./exports/

Validar desde la entrada estándar

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

Validar con el perfil strict

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

Emitir JSON legible por máquina

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

Sobrescribir la resolución del schema

Usa un archivo schema local en lugar del incluido:

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

Salida detallada

Muestra diagnósticos detallados, incluidos fragmentos de origen (solo formato de texto):

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

Controlar la salida con color

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

Códigos de salida esperados

El contrato de la CLI define códigos de salida estables:

0 = success La validación se ejecutó y no se emitió ningún diagnóstico error.
1 = validation error La validación se ejecutó y se emitió al menos un diagnóstico error.
2 = operational error La validación no pudo ejecutarse para una o más entradas debido a archivos ilegibles, JSON no válido, flags incorrectas o fallas similares previas a la validación.

Modos de salida

La CLI está diseñada para soportar dos formatos de salida:

Texto legible para humanos

Salida de terminal predeterminada para uso local:

ruta del archivo
línea/columna cuando esté disponible
severidad
código de diagnóstico
mensaje legible para humanos

JSON legible por máquina

Usa --format json para CI, scripts, dashboards o herramientas downstream.

Para una sola entrada, la CLI emite un objeto JSON con formato legible a stdout. Para múltiples entradas, emite NDJSON (un objeto JSON compacto por línea).

Local-first y offline-first por diseño

La validación de OSIRIS JSON está pensada para ejecutarse localmente por defecto.

La CLI MUST NOT obtener datos de la red durante la validación.
$schema se trata como una pista de versión, no como una URL activa que deba recuperarse.
Se usan schemas incluidos o en caché para la resolución.

Esto es importante porque los documentos de topología de infraestructura MAY contener información sensible de diseño, incluso cuando los secretos ya se eliminaron.

Uso recomendado por rol

Producers

Valida antes de publicar cualquier documento:

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

Consumers y pipelines de CI

Valida al recibirlo antes de procesar o almacenar el documento.

Editores e integraciones

Usa el mismo comportamiento del motor que la CLI delegando la validación a @osirisjson/core.