Directrices de arquitectura de OSIRIS JSON

OSIRIS JSON ahora cuenta con un documento de arquitectura dedicado para quienes contribuyen construyendo alrededor del estándar.

Publicadas el 4 de febrero de 2026, las OSIRIS JSON Architecture Development Guidelines definen cómo se espera que evolucione el ecosistema a través del repositorio de la especificación, los paquetes toolbox, los productores y las integraciones de editor. Esto no es una segunda especificación. Es el plano operativo para mantener las implementaciones alineadas a medida que el proyecto crece.

Por qué este documento importa

Los estándares abiertos suelen fragmentarse cuando cada herramienta, extensión o productor empieza a interpretar el formato por su cuenta. Las directrices de arquitectura están pensadas para prevenir ese resultado desde el principio.

El documento deja explícitas dos posiciones:

• La especificación y el schema de OSIRIS siguen siendo la única fuente de verdad para el formato
• @osirisjson/core es la implementación canónica del comportamiento de validación y del formateo de diagnósticos

Esto importa porque el mismo documento OSIRIS debería comportarse de forma consistente en CI, en la CLI y dentro de las integraciones de editor. El proyecto traza una línea clara contra los validadores duplicados, los forks incompatibles de la lógica de reglas y la expansión desordenada de repositorios disfrazada de flexibilidad.

La dirección arquitectónica central

Las directrices formalizan una separación clara de responsabilidades en todo el ecosistema:

• osiris define la especificación canónica, el schema, los ejemplos y las directrices de desarrollo
• osiris-toolbox aloja los paquetes compartidos de TypeScript, incluyendo @osirisjson/core, @osirisjson/sdk y @osirisjson/cli
• osiris-producers contiene productores específicos de proveedor y el Go producer SDK
• osiris-editor-integrations consume el motor de validación compartido en lugar de reimplementarlo

Una de las reglas más importantes del documento es la regla de “forbidden direction” para dependencias. La lógica de validación fluye hacia abajo dentro del core compartido; no se copia hacia arriba dentro de editores, productores o command wrappers. Ese diseño es lo que mantiene portable al ecosistema y evita un comportamiento de split-brain entre herramientas.

Más que estructura de repositorio

Las directrices de arquitectura también son el lugar donde OSIRIS define cómo debe comportarse el sistema bajo presión real de implementación.

Describen:

• Una pipeline de validación de tres etapas: verificaciones estructurales, semánticas y de dominio
• Un modelo de diagnóstico estable construido alrededor de códigos, severidades, mensajes y rutas de documento
• Directrices de identidad determinista para que recursos, grupos y conexiones sigan siendo amigables con diff a través de las exportaciones
• Convenciones de archivos JSON pensadas para reducir cambios ruidosos y mejorar las herramientas de editor
• Expectativas de seguridad y redacción, incluyendo una prohibición estricta de credenciales y secretos dentro de los documentos OSIRIS

Aquí también es donde el proyecto explica una división pragmática de plataformas: la toolbox canónica está construida en TypeScript y distribuida a través de NPM para una reutilización máxima entre la CLI y las integraciones de editor, mientras que se recomiendan productores de primera parte en Go porque la adquisición, el transporte, la concurrencia y la recolección específica de proveedor tienen restricciones de ejecución diferentes.

Qué deberían extraer quienes contribuyen

El mensaje principal del documento de arquitectura es directo: OSIRIS está diseñado como un ecosistema, no solo como un archivo de schema.

Si se está construyendo un productor, una regla de validación, una funcionalidad de CLI o una integración de editor, las directrices aclaran dónde pertenece ese trabajo, qué contratos son estables y qué atajos no son aceptables. Eso hace que el documento sea especialmente importante para quienes contribuyen en etapas tempranas, porque establece límites antes de que la duplicación accidental se convierta en deuda del proyecto.

Lee las directrices

Las directrices de arquitectura actualmente se publican como un documento draft, creado el 4 de febrero de 2026 y revisado el 11 de febrero de 2026:

• Lee las OSIRIS Architecture Development Guidelines
• Lee la especificación OSIRIS JSON v1.0
• Lee las directrices de implementación
• Lee el capítulo de validación
• Lee el capítulo de versionado y compatibilidad
• Ve el repositorio del proyecto

Banner icon author Reyda Dönmez