Directrius d’arquitectura d’OSIRIS JSON

OSIRIS JSON ara disposa d’un document d’arquitectura dedicat per a col·laboradors que construeixen al voltant de l’estàndard.

Publicades el 4 de febrer de 2026, les OSIRIS JSON Architecture Development Guidelines defineixen com s’espera que evolucioni l’ecosistema a través del repositori de l’especificació, els paquets toolbox, els producers i les integracions d’editor. Això no és una segona especificació. És el plànol operatiu per mantenir les implementacions alineades a mesura que el projecte creix.

Per què aquest document importa

Els estàndards oberts sovint es fragmenten quan cada eina, extensió o producer comença a interpretar el format pel seu compte. Les directrius d’arquitectura estan pensades per prevenir aquest resultat ben aviat.

El document fa explícites dues posicions:

• L’especificació i l’schema d’OSIRIS continuen sent l’única font de veritat per al format
• @osirisjson/core és la implementació canònica del comportament de validació i del format de diagnòstic

Això importa perquè el mateix document OSIRIS hauria de comportar-se de manera coherent a CI, a la CLI i dins de les integracions d’editor. El projecte marca una línia clara contra validators duplicats, forks incompatibles de la lògica de regles i l’expansió desordenada de repositoris disfressada de flexibilitat.

La direcció arquitectònica central

Les directrius formalitzen una separació clara de responsabilitats a tot l’ecosistema:

• osiris defineix l’especificació canònica, l’schema, els exemples i les directrius de desenvolupament
• osiris-toolbox allotja els paquets compartits de TypeScript, incloent @osirisjson/core, @osirisjson/sdk i @osirisjson/cli
• osiris-producers conté producers específics de proveïdor i el Go producer SDK
• osiris-editor-integrations consumeix el motor de validació compartit en lloc de reimplementar-lo

Una de les regles més importants del document és la regla de “forbidden direction” per a dependències. La lògica de validació flueix cap avall dins del core compartit; no es copia cap amunt cap a editors, producers o command wrappers. Aquest disseny és el que manté l’ecosistema portable i evita un comportament de split-brain entre eines.

Més que l’estructura del repositori

Les directrius d’arquitectura també són el lloc on OSIRIS defineix com s’hauria de comportar el sistema sota pressió real d’implementació.

Descriuen:

• Una pipeline de validació en tres etapes: comprovacions estructurals, semàntiques i de domini
• Un model de diagnòstic estable construït al voltant de codis, severitats, missatges i rutes de document
• Directrius d’identitat determinista perquè recursos, grups i connexions continuïn sent amigables amb diff a través de les exportacions
• Convencions de fitxers JSON pensades per reduir canvis sorollosos i millorar les eines d’editor
• Expectatives de seguretat i redacció, incloent una prohibició estricta de credencials i secrets dins dels documents OSIRIS

Aquí també és on el projecte explica una divisió pragmàtica de plataformes: la toolbox canònica està construïda en TypeScript i distribuïda a través de NPM per a la màxima reutilització entre la CLI i les integracions d’editor, mentre que els producers de primera part es recomanen en Go perquè l’adquisició, el transport, la concurrència i la recollida específica de proveïdor tenen restriccions d’execució diferents.

Què n’han de treure els col·laboradors

El missatge principal del document d’arquitectura és directe: OSIRIS està dissenyat com un ecosistema, no només com un fitxer d’schema.

Si s’està construint un producer, una regla de validació, una funcionalitat de CLI o una integració d’editor, les directrius aclareixen on pertany aquesta feina, quins contractes són estables i quines dreceres no són acceptables. Això fa que el document sigui especialment important per a col·laboradors inicials, perquè estableix límits abans que la duplicació accidental es converteixi en deute del projecte.

Llegeix les directrius

Les directrius d’arquitectura actualment es publiquen com un document draft, creat el 4 de febrer de 2026 i revisat l’11 de febrer de 2026:

• Llegeix les OSIRIS Architecture Development Guidelines
• Llegeix l’especificació OSIRIS JSON v1.0
• Llegeix les directrius d’implementació
• Llegeix el capítol de validació
• Llegeix el capítol de versionat i compatibilitat
• Consulta el repositori del projecte

Banner icon author Reyda Dönmez