Lignes directrices d’architecture OSIRIS JSON

OSIRIS JSON dispose désormais d’un document d’architecture dédié pour les personnes qui contribuent en construisant autour du standard.

Publiées le 4 février 2026, les OSIRIS JSON Architecture Development Guidelines définissent comment l’écosystème est censé évoluer à travers le dépôt de spécification, les paquets toolbox, les producers et les intégrations d’éditeur. Il ne s’agit pas d’une seconde spécification. C’est le plan opérationnel permettant de garder les implémentations alignées à mesure que le projet grandit.

Pourquoi ce document compte

Les standards ouverts deviennent souvent fragmentés lorsque chaque outil, extension ou producer commence à interpréter le format de manière autonome. Les lignes directrices d’architecture sont conçues pour empêcher ce résultat dès le départ.

Le document rend explicites deux positions :

• La spécification et le schema OSIRIS restent l’unique source de vérité pour le format
• @osirisjson/core est l’implémentation canonique du comportement de validation et du formatage des diagnostics

Cela compte parce que le même document OSIRIS doit se comporter de manière cohérente dans la CI, dans la CLI et au sein des intégrations d’éditeur. Le projet trace une ligne ferme contre les validateurs dupliqués, les forks incompatibles de logique de règles et l’étalement des dépôts déguisé en flexibilité.

La direction architecturale centrale

Les lignes directrices formalisent une séparation claire des responsabilités à travers l’écosystème :

• osiris définit la spécification canonique, le schema, les exemples et les lignes directrices de développement
• osiris-toolbox héberge les paquets TypeScript partagés, dont @osirisjson/core, @osirisjson/sdk et @osirisjson/cli
• osiris-producers contient les producers spécifiques aux fournisseurs ainsi que le Go producer SDK
• osiris-editor-integrations consomme le moteur de validation partagé au lieu de le réimplémenter

L’une des règles les plus importantes du document est la règle de “forbidden direction” pour les dépendances. La logique de validation s’écoule vers le bas dans le core partagé ; elle n’est pas copiée vers le haut dans les éditeurs, les producers ou les wrappers de commandes. C’est cette conception qui maintient l’écosystème portable et évite un comportement de split-brain entre les outils.

Plus qu’une structure de dépôt

Les lignes directrices d’architecture sont également l’endroit où OSIRIS définit comment le système doit se comporter sous une pression réelle d’implémentation.

Elles décrivent :

• Un pipeline de validation en trois étapes : contrôles structurels, sémantiques et de domaine
• Un modèle de diagnostic stable construit autour de codes, de sévérités, de messages et de chemins de document
• Des directives d’identité déterministe afin que les ressources, groupes et connexions restent compatibles avec les diff à travers les exports
• Des conventions de fichiers JSON destinées à réduire les changements bruyants et à améliorer l’outillage des éditeurs
• Des attentes en matière de sécurité et de rédaction, incluant une interdiction stricte des identifiants et secrets dans les documents OSIRIS

C’est également ici que le projet explique une séparation pragmatique des plateformes : la toolbox canonique est construite en TypeScript et distribuée via NPM pour une réutilisation maximale entre la CLI et les intégrations d’éditeur, tandis que les producers de première partie sont recommandés en Go parce que l’acquisition, le transport, la concurrence et la collecte spécifique aux fournisseurs ont des contraintes d’exécution différentes.

Ce que les personnes qui contribuent doivent en retenir

Le message principal du document d’architecture est simple : OSIRIS est conçu comme un écosystème, pas seulement comme un fichier de schema.

Si un producer, une règle de validation, une fonctionnalité CLI ou une intégration d’éditeur est en cours de développement, les lignes directrices précisent à quel endroit ce travail appartient, quels contrats sont stables et quels raccourcis ne sont pas acceptables. Cela rend le document particulièrement important pour les premières personnes qui contribuent, car il établit des limites avant que la duplication accidentelle ne devienne une dette du projet.

Lire les lignes directrices

Les lignes directrices d’architecture sont actuellement publiées comme un document draft, créé le 4 février 2026 et révisé le 11 février 2026 :

• Lire les OSIRIS Architecture Development Guidelines
• Lire la spécification OSIRIS JSON v1.0
• Lire les lignes directrices d’implémentation
• Lire le chapitre sur la validation
• Lire le chapitre sur le versioning et la compatibilité
• Voir le dépôt du projet

Banner icon author Reyda Dönmez