Validar documentos OSIRIS JSON
La validacion de OSIRIS JSON ya no es solo una parte implicita de la especificacion. Ahora tiene un modelo documentado, un limite canonico del motor y un contrato CLI pensado para herramientas reales.
La orientacion actual sobre validacion se reparte en tres documentos en borrador publicados en febrero de 2026: las Directrices de niveles de validacion, la guia interna de Toolbox Core y la guia de Toolbox CLI. En conjunto, definen como deben validarse los documentos OSIRIS de forma coherente entre el desarrollo local, las integraciones en editores y los pipelines de CI.
La validacion es mas que un esquema
Una de las decisiones mas claras del modelo de validacion de OSIRIS es que JSON Schema por si solo no es suficiente.
El proyecto define la validacion como un pipeline de tres niveles:
- Nivel 1: Estructural la validacion comprueba si un documento se ajusta al esquema de OSIRIS
- Nivel 2: Semantico la validacion comprueba la integridad del grafo, como referencias colgantes, identificadores duplicados y jerarquias de grupos no validas
- Nivel 3: Dominio la validacion agrega orientacion opcional de buenas practicas que mejora la interoperabilidad sin redefinir que cuenta como un OSIRIS valido
Esa separacion importa. Un documento puede ser estructuralmente correcto y aun asi resultar inseguro de consumir si no se puede confiar en su topologia. OSIRIS trata esos casos como problemas distintos y ofrece a las herramientas una forma mas limpia de informarlos.
Un motor compartido, no validadores en competencia
La arquitectura de validacion se construye alrededor de una sola regla: las herramientas de referencia no deberian inventar su propia version de la verdad.
@osirisjson/core se define como el motor de validacion canonico del ecosistema. Es el componente que gestiona el pipeline de tres etapas, el modelo de diagnostico, el enrutamiento de esquemas y la logica de perfiles. Se espera que la CLI y las integraciones en editores deleguen la validacion en ese motor compartido en lugar de reimplementar las reglas por separado.
Esa es una decision arquitectonica firme, y es la correcta. Significa que el mismo documento deberia producir el mismo resultado tanto si se comprueba en CI, como si se inspecciona en un editor o se procesa con una herramienta de nivel superior construida sobre la toolbox de OSIRIS.
Los diagnosticos son el contrato
Otra decision importante de diseno es que OSIRIS trata los diagnosticos como una interfaz estructurada, no como una salida de texto suelta.
Los hallazgos de validacion se construyen alrededor de codigos V-* estables, severidades, mensajes y rutas JSON Pointer. En la practica, eso significa:
- El codigo es el hecho estable
- La severidad es una politica determinada por el perfil activo
- El mensaje puede evolucionar para ganar claridad sin romper las herramientas
Esta es la diferencia entre una validacion que solo es visible y una validacion que realmente puede automatizarse. Los pipelines de CLI, los mensajes emergentes en editores, los informes legibles por maquinas y las futuras correcciones rapidas dependen de esa separacion.
Pensado para el trabajo local y la CI
La guia de CLI es especialmente pragmatica. La validacion esta pensada para ser determinista, priorizar el trabajo sin conexion y funcionar bien en la shell.
El contrato documentado espera:
- soporte de
stdinpara componer pipelines - salida JSON legible por maquinas para CI y automatizacion
- codigos de salida estables que separan los fallos de validacion de los fallos operativos
- resolucion de esquemas sin conexion usando esquemas incluidos o en cache en lugar de descargas en vivo desde la red
Los perfiles son igual de practicos:
basicse centra solo en comprobaciones estructuralesdefaultejecuta validacion estructural y semantica para el trabajo diariostrictagrega comprobaciones de dominio seleccionadas para publicaciones de productores y puertas de CI
Eso le da a OSIRIS un modelo de validacion que puede escalar desde la retroalimentacion en el editor hasta la validacion por lotes sin cambiar el significado de las reglas subyacentes.
Por que esto importa ahora
Sin un modelo de validacion compartido, un estandar abierto empieza a desviarse casi de inmediato. Cada herramienta termina con supuestos distintos, severidades distintas, comportamientos de analizador distintos y, finalmente, definiciones distintas de lo que significa “valido”.
Estas directrices de validacion y de la toolbox son importantes porque intentan detener esa deriva antes de que empiece. Hacen que la validacion sea reproducible, ensenable y portable en todo el ecosistema. Igual de importante, mantienen la privacidad y la previsibilidad dentro del alcance al exigir un comportamiento de validacion local y evitar la dependencia de la red durante las comprobaciones.
Leer la orientacion de validacion
Los documentos actuales sobre validacion y toolbox se publican como orientacion en borrador: