Linee guida architetturali di OSIRIS JSON

OSIRIS JSON dispone ora di un documento architetturale dedicato per chi contribuisce sviluppando attorno allo standard.

Pubblicate il 4 febbraio 2026, le OSIRIS JSON Architecture Development Guidelines definiscono come l’ecosistema dovrebbe evolvere attraverso il repository della specifica, i pacchetti toolbox, i producer e le integrazioni editor. Questa non è una seconda specifica. È il piano operativo per mantenere le implementazioni allineate mentre il progetto cresce.

Perché questo documento è importante

Gli standard aperti spesso si frammentano quando ogni strumento, estensione o producer inizia a interpretare il formato in autonomia. Le linee guida architetturali servono proprio a prevenire questo esito fin dalle prime fasi.

Il documento rende esplicite due posizioni:

• La specifica e lo schema OSIRIS restano l’unica fonte di verità per il formato
• @osirisjson/core è l’implementazione canonica del comportamento di validazione e della formattazione dei diagnostici

Questo è importante perché lo stesso documento OSIRIS dovrebbe comportarsi in modo coerente in CI, nella CLI e all’interno delle integrazioni editor. Il progetto traccia una linea netta contro validator duplicati, fork incompatibili della logica delle regole e proliferazione di repository mascherata da flessibilità.

La direzione architetturale centrale

Le linee guida formalizzano una chiara separazione delle responsabilità all’interno dell’ecosistema:

• osiris definisce la specifica canonica, lo schema, gli esempi e le linee guida di sviluppo
• osiris-toolbox ospita i pacchetti TypeScript condivisi, inclusi @osirisjson/core, @osirisjson/sdk e @osirisjson/cli
• osiris-producers contiene producer specifici per vendor e il Go producer SDK
• osiris-editor-integrations consuma il motore di validazione condiviso invece di reimplementarlo

Una delle regole più importanti del documento è la regola “forbidden direction” per le dipendenze. La logica di validazione fluisce verso il basso nel core condiviso; non viene copiata verso l’alto dentro editor, producer o command wrapper. È proprio questo design a mantenere portabile l’ecosistema ed evitare comportamenti split-brain tra gli strumenti.

Più della struttura del repository

Le linee guida architetturali sono anche il luogo in cui OSIRIS definisce come il sistema dovrebbe comportarsi sotto una reale pressione implementativa.

Descrivono:

• Una pipeline di validazione in tre fasi: controlli strutturali, semantici e di dominio
• Un modello diagnostico stabile costruito attorno a codici, severità, messaggi e percorsi del documento
• Indicazioni per un’identità deterministica così che risorse, gruppi e connessioni restino compatibili con i diff attraverso le esportazioni
• Convenzioni per i file JSON pensate per ridurre modifiche rumorose e migliorare gli strumenti editor
• Aspettative di sicurezza e redazione, inclusa una rigida proibizione di credenziali e segreti all’interno dei documenti OSIRIS

Qui il progetto spiega anche una divisione pragmatica delle piattaforme: la toolbox canonica è costruita in TypeScript e distribuita tramite NPM per garantire il massimo riuso tra CLI e integrazioni editor, mentre i producer di prima parte sono raccomandati in Go perché acquisizione, trasporto, concorrenza e raccolta specifica per vendor hanno vincoli di esecuzione differenti.

Cosa dovrebbe emergere per chi contribuisce

Il messaggio principale del documento architetturale è diretto: OSIRIS è progettato come un ecosistema, non solo come un file di schema.

Se si sta costruendo un producer, una regola di validazione, una funzionalità CLI o un’integrazione editor, le linee guida chiariscono dove appartiene quel lavoro, quali contratti sono stabili e quali scorciatoie non sono accettabili. Questo rende il documento particolarmente importante per chi contribuisce nelle fasi iniziali, perché stabilisce confini prima che duplicazioni accidentali diventino debito progettuale.

Leggi le linee guida

Le linee guida architetturali sono attualmente pubblicate come documento draft, creato il 4 febbraio 2026 e rivisto l’11 febbraio 2026:

• Leggi le OSIRIS Architecture Development Guidelines
• Leggi la specifica OSIRIS JSON v1.0
• Leggi le linee guida di implementazione
• Leggi il capitolo sulla validazione
• Leggi il capitolo su versioning e compatibilità
• Visualizza il repository del progetto

Banner icon author Reyda Dönmez