Diretrizes de arquitetura do OSIRIS JSON

O OSIRIS JSON agora conta com um documento de arquitetura dedicado para quem contribui construindo em torno do padrão.

Publicadas em 4 de fevereiro de 2026, as OSIRIS JSON Architecture Development Guidelines definem como se espera que o ecossistema evolua por meio do repositório da especificação, dos pacotes toolbox, dos producers e das integrações de editor. Esta não é uma segunda especificação. É o plano operacional para manter as implementações alinhadas à medida que o projeto cresce.

Por que este documento importa

Padrões abertos frequentemente se fragmentam quando cada ferramenta, extensão ou producer começa a interpretar o formato por conta própria. As diretrizes de arquitetura existem justamente para evitar esse resultado desde cedo.

O documento deixa duas posições explícitas:

• A especificação e o schema do OSIRIS continuam sendo a única fonte de verdade para o formato
• @osirisjson/core é a implementação canônica do comportamento de validação e da formatação de diagnósticos

Isso importa porque o mesmo documento OSIRIS deve se comportar de forma consistente na CI, na CLI e dentro das integrações de editor. O projeto traça uma linha dura contra validadores duplicados, forks incompatíveis da lógica de regras e a proliferação de repositórios disfarçada de flexibilidade.

A direção arquitetural central

As diretrizes formalizam uma separação clara de responsabilidades em todo o ecossistema:

• osiris define a especificação canônica, o schema, os exemplos e as diretrizes de desenvolvimento
• osiris-toolbox hospeda os pacotes TypeScript compartilhados, incluindo @osirisjson/core, @osirisjson/sdk e @osirisjson/cli
• osiris-producers contém producers específicos de fornecedores e o Go producer SDK
• osiris-editor-integrations consome o motor de validação compartilhado em vez de reimplementá-lo

Uma das regras mais importantes do documento é a regra de “forbidden direction” para dependências. A lógica de validação flui para baixo em direção ao core compartilhado; ela não é copiada para cima em editores, producers ou command wrappers. Esse design é o que mantém o ecossistema portável e evita comportamento de split-brain entre ferramentas.

Mais do que estrutura de repositório

As diretrizes de arquitetura também são o lugar onde o OSIRIS define como o sistema deve se comportar sob pressão real de implementação.

Elas descrevem:

• Um pipeline de validação em três estágios: verificações estruturais, semânticas e de domínio
• Um modelo de diagnóstico estável construído em torno de códigos, severidades, mensagens e caminhos de documento
• Diretrizes de identidade determinística para que recursos, grupos e conexões continuem amigáveis a diff ao longo das exportações
• Convenções de arquivos JSON pensadas para reduzir mudanças ruidosas e melhorar as ferramentas de editor
• Expectativas de segurança e redação, incluindo uma proibição rígida de credenciais e segredos dentro dos documentos OSIRIS

É também aqui que o projeto explica uma divisão pragmática de plataformas: a toolbox canônica é construída em TypeScript e distribuída por meio do NPM para máximo reaproveitamento entre CLI e integrações de editor, enquanto producers de primeira parte são recomendados em Go porque aquisição, transporte, concorrência e coleta específica por fornecedor têm restrições de execução diferentes.

O que deve ficar claro para quem contribui

A principal mensagem do documento de arquitetura é direta: o OSIRIS foi projetado como um ecossistema, não apenas como um arquivo de schema.

Se estiver sendo desenvolvido um producer, uma regra de validação, uma funcionalidade de CLI ou uma integração de editor, as diretrizes deixam claro onde esse trabalho pertence, quais contratos são estáveis e quais atalhos não são aceitáveis. Isso torna o documento especialmente importante para quem contribui nas fases iniciais, porque estabelece limites antes que a duplicação acidental se torne dívida de projeto.

Leia as diretrizes

As diretrizes de arquitetura estão atualmente publicadas como um documento draft, criado em 4 de fevereiro de 2026 e revisado em 11 de fevereiro de 2026:

• Leia as OSIRIS Architecture Development Guidelines
• Leia a especificação OSIRIS JSON v1.0
• Leia as diretrizes de implementação
• Leia o capítulo de validação
• Leia o capítulo de versionamento e compatibilidade
• Veja o repositório do projeto

Banner icon author Reyda Dönmez