Validação do OSIRIS JSON

A validação do OSIRIS foi projetada para ser local-first, determinística e utilizável tanto em fluxos de trabalho interativos quanto em pipelines de CI.

O caminho canônico de validação é o pacote OSIRIS CLI:

Package name: @osirisjson/cli
Canonical engine behind the CLI: @osirisjson/core
Primary command: validate

O que o validator verifica

A validação do OSIRIS é intencionalmente estruturada em camadas:

Level 1: Structural Valida a conformidade com JSON Schema: campos obrigatórios, tipos de campo, enums, formatos e a estrutura de nível superior.
Level 2: Semantic Valida a consistência interna do grafo: IDs duplicados, referências quebradas, hierarquias de grupo inválidas e problemas de integridade semelhantes.
Level 3: Domain Executa verificações opcionais de boas práticas que melhoram a interoperabilidade e a qualidade sem redefinir o que conta como um documento OSIRIS JSON válido.

Perfis de validação

A CLI foi projetada em torno de três perfis:

basic Executa apenas Level 1. Use-o para verificações estruturais rápidas.
default Executa Level 1 + Level 2. Este é o perfil de validação esperado para o dia a dia.
strict Executa Level 1 + Level 2 + regras selecionadas de Level 3. Este é o perfil recomendado para CI e gates de release.

Instalação com NPM

Executar sem instalação global

npx @osirisjson/cli validate ./example.json

Esta é a forma recomendada de executar o validator em CI ou quando você não quiser uma instalação global.

Instalar globalmente

npm install -g @osirisjson/cli
osirisjson validate ./example.json

Adicionar como dependência do projeto

npm install --save-dev @osirisjson/cli
npx @osirisjson/cli validate ./example.json

Comandos de validação

Validar um arquivo

npx @osirisjson/cli validate osiris-document-example.json

Validar vários arquivos

npx @osirisjson/cli validate osiris-document-example-01.json osiris-document-example-02.json

Validar um diretório

Expande para todos os arquivos .json no diretório (não recursivo):

npx @osirisjson/cli validate ./exports/

Validar a partir da entrada padrão

cat osiris-document-example.json | npx @osirisjson/cli validate -

Validar com o perfil strict

npx @osirisjson/cli validate --profile strict ./exports/

Emitir JSON legível por máquina

npx @osirisjson/cli validate --profile strict --format json ./exports/

Substituir a resolução do schema

Use um arquivo schema local em vez do que vem incluído:

npx @osirisjson/cli validate --schema ./osiris.schema.json topology.json

Saída detalhada

Mostra diagnósticos detalhados, incluindo trechos da origem (apenas formato texto):

npx @osirisjson/cli validate --verbose topology.json

Controlar a saída em cores

npx @osirisjson/cli validate --color never ./exports/

Códigos de saída esperados

O contrato da CLI define códigos de saída estáveis:

0 = success A validação foi executada e nenhum diagnóstico error foi emitido.
1 = validation error A validação foi executada e pelo menos um diagnóstico error foi emitido.
2 = operational error A validação não pôde ser executada para uma ou mais entradas devido a arquivos ilegíveis, JSON inválido, flags incorretas ou falhas semelhantes antes da validação.

Modos de saída

A CLI foi projetada para suportar dois formatos de saída:

Texto legível por humanos

Saída padrão de terminal para uso local:

caminho do arquivo
linha/coluna quando disponível
severidade
código de diagnóstico
mensagem legível por humanos

JSON legível por máquina

Use --format json para CI, scripts, dashboards ou ferramentas downstream.

Para uma única entrada, a CLI emite um objeto JSON formatado em stdout. Para múltiplas entradas, ela emite NDJSON (um objeto JSON compacto por linha).

Local-first e offline-first por design

A validação do OSIRIS JSON foi pensada para ser executada localmente por padrão.

A CLI MUST NOT buscar dados da rede durante a validação.
$schema é tratado como uma indicação de versão, não como uma URL ativa a ser buscada.
Schemas incluídos ou em cache são usados para resolução.

Isso importa porque documentos de topologia de infraestrutura MAY conter informações sensíveis de design, mesmo quando os segredos já tiverem sido removidos.

Uso recomendado por função

Producers

Valide antes de publicar qualquer documento:

npx @osirisjson/cli validate --profile strict output.json

Consumers e pipelines de CI

Valide no recebimento antes de processar ou armazenar o documento.

Editores e integrações

Use o mesmo comportamento do mecanismo da CLI delegando a validação para @osirisjson/core.