Validar documentos OSIRIS JSON
A validacao do OSIRIS JSON nao e mais apenas uma parte implicita da especificacao. Agora ela tem um modelo documentado, um limite canonico para o mecanismo e um contrato de CLI pensado para ferramentas reais.
As orientacoes atuais sobre validacao estao distribuidas em tres documentos em rascunho publicados em fevereiro de 2026: as Diretrizes de niveis de validacao, o guia interno do Toolbox Core e o guia do Toolbox CLI. Juntos, eles definem como os documentos OSIRIS devem ser validados de forma consistente entre o desenvolvimento local, as integracoes com editores e os pipelines de CI.
Validacao e mais do que esquema
Uma das decisoes mais claras do modelo de validacao do OSIRIS e que o JSON Schema sozinho nao basta.
O projeto define a validacao como um pipeline de tres niveis:
- Nivel 1: Estrutural a validacao verifica se um documento esta em conformidade com o esquema do OSIRIS
- Nivel 2: Semantico a validacao verifica a integridade do grafo, como referencias pendentes, identificadores duplicados e hierarquias de grupos invalidas
- Nivel 3: Dominio a validacao adiciona orientacoes opcionais de boas praticas que melhoram a interoperabilidade sem redefinir o que conta como um OSIRIS valido
Essa separacao importa. Um documento pode estar estruturalmente correto e ainda assim ser inseguro para consumo se nao for possivel confiar em sua topologia. O OSIRIS trata esses casos como problemas diferentes e oferece as ferramentas uma forma mais limpa de relata-los.
Um mecanismo compartilhado, nao validadores concorrentes
A arquitetura de validacao e construida em torno de uma unica regra: as ferramentas de referencia nao devem inventar sua propria versao da verdade.
@osirisjson/core e definido como o mecanismo de validacao canonico do ecossistema. Ele e o componente responsavel pelo pipeline de tres etapas, pelo modelo de diagnostico, pelo roteamento de esquemas e pela logica de perfis. Espera-se que a CLI e as integracoes com editores deleguem a validacao a esse mecanismo compartilhado em vez de reimplementar regras de forma independente.
Essa e uma escolha arquitetural forte, e a correta. Isso significa que o mesmo documento deve produzir o mesmo resultado, seja verificado em CI, inspecionado em um editor ou processado por uma ferramenta de nivel superior construida sobre a toolbox do OSIRIS.
Os diagnosticos sao o contrato
Outra escolha importante de design e que o OSIRIS trata os diagnosticos como uma interface estruturada, e nao como uma saida de texto solta.
Os resultados da validacao sao construidos em torno de codigos V-* estaveis, severidades, mensagens e caminhos JSON Pointer. Na pratica, isso significa:
- O codigo e o fato estavel
- A severidade e uma politica moldada pelo perfil ativo
- A mensagem pode evoluir para ganhar clareza sem quebrar as ferramentas
Essa e a diferenca entre uma validacao apenas visivel e uma validacao que realmente pode ser automatizada. Pipelines de CLI, dicas em editores, relatorios legiveis por maquina e futuras correcoes rapidas dependem dessa separacao.
Pensado para trabalho local e CI
O guia de CLI e especialmente pragmatico. A validacao foi pensada para ser deterministica, priorizar o uso offline e funcionar bem no shell.
O contrato documentado espera:
- suporte a
stdinpara composicao de pipelines - saida JSON legivel por maquina para CI e automacao
- codigos de saida estaveis que separam falhas de validacao de falhas operacionais
- resolucao offline de esquemas usando esquemas incluidos ou em cache em vez de buscas ao vivo pela rede
Os perfis sao igualmente praticos:
basicfoca apenas em verificacoes estruturaisdefaultexecuta validacao estrutural e semantica para o trabalho do dia a diastrictadiciona verificacoes de dominio selecionadas para lancamentos de produtores e gates de CI
Isso da ao OSIRIS um modelo de validacao que pode escalar do retorno no editor a validacao em lote sem mudar o significado das regras subjacentes.
Por que isso importa agora
Sem um modelo de validacao compartilhado, um padrao aberto comeca a se desviar quase imediatamente. Cada ferramenta acaba com pressupostos diferentes, severidades diferentes, comportamentos de parser diferentes e, por fim, definicoes diferentes do que significa “valido”.
Essas diretrizes de validacao e da toolbox sao importantes porque tentam impedir esse desvio antes que ele comece. Elas tornam a validacao reproduzivel, ensinavel e portavel em todo o ecossistema. Tao importante quanto isso, mantem privacidade e previsibilidade no escopo ao exigir comportamento de validacao local e evitar dependencia de rede durante as verificacoes.
Ler a orientacao de validacao
Os documentos atuais sobre validacao e toolbox sao publicados como orientacao em rascunho: