Validador de JSON Schema

O que é uma ferramenta de JSON Schema?#

Um valor JSON por si só diz-lhe o que os dados são — uma string aqui, um número ali. Não diz o que os dados deviam ser: se age tem de ser um inteiro não negativo, se email é obrigatório, se tags pode ser vazio. JSON Schema é o vocabulário para dizer essas coisas. Escreve-se um esquema — um pequeno documento JSON que descreve uma forma — e um validador verifica se um dado se encaixa nessa forma, campo a campo.

Esta página faz dois trabalhos com o mesmo motor de esquemas. Validar recebe um esquema e um documento de dados e diz-lhe exatamente que campos violam que regras, cada um fixado no seu caminho no documento. Inferir vai no outro sentido: dê-lhe um valor JSON de exemplo e ele escreve por si um esquema ao estilo Draft-07, percorrendo a estrutura e registrando o tipo de cada campo. Os dois compõem-se naturalmente — infira um esquema a partir de um exemplo representativo e depois valide todos os documentos futuros contra ele.

A validação corre no mesmo motor Ajv que o código de produção usa, com três drafts selecionáveis (Draft-07, 2019-09, 2020-12) e a proteção de modo estrito relaxada, pelo que um esquema ligeiramente não-estrito é tolerado em vez de recusado frontalmente.

Como usar#

1. Escolha um modo no interruptor da barra de ferramentas:
   • Validar (predefinição): cole o esquema à esquerda, os dados à direita.
   • Inferir: cole um valor JSON de exemplo à esquerda, leia o esquema gerado à direita.
2. No modo Validar, escolha o Draft contra o qual o esquema está escrito — Draft-07 cobre a grande maioria dos esquemas existentes; escolha 2019-09 ou 2020-12 apenas se o seu esquema usa funcionalidades que esses drafts introduziram.
3. Escolha uma Indentação para a saída — 2 ou 4 espaços. No modo Inferir, isto controla a formatação do esquema gerado.
4. O painel da direita mostra o documento de dados (Validar) ou o esquema inferido (Inferir). As etiquetas do painel trocam para corresponder ao modo.
5. No modo Validar, o painel Violações por baixo dos painéis lista cada infração como caminho — razão. A raiz do documento aparece como (root); um campo aninhado aparece como o seu JSON Pointer, como /age.
6. Clique em Copiar no painel da direita para recolher o esquema inferido ou os dados, ou Exemplo / Limpar para carregar ou repor.

Os resultados calculam-se assim que ambas as entradas analisam. Um erro de sintaxe de esquema ou dados é reportado com a sua linha e coluna exatas, etiquetado como problema de esquema, dados ou compilação para saber onde procurar.

Principais funcionalidades#

• Dois modos, um motor. Valide documentos, ou gere um esquema a partir de um exemplo, com o mesmo validador confiável por baixo.
• Três drafts. Draft-07, 2019-09 e 2020-12, cada um carregando apenas o seu próprio validador compilado, pelo que valida sempre contra o draft que efetivamente visa.
• Todos os erros, não só o primeiro. Cada violação é recolhida, pelo que um documento com cinco problemas mostra cinco problemas em vez de obrigar a cinco viagens.
• Violações fixadas no caminho. Cada infração aponta para a sua localização no documento — (root) para problemas de todo o documento, ou um ponteiro preciso como /user/address/zip.
• Modo estrito relaxado. Um esquema com uma palavra-chave desconhecida ou um tipo de topo em falta é tolerado e executado, não rejeitado em tempo de compilação — o comportamento certo para uma ferramenta cujo trabalho é verificar, não dar lições de moral.
• Apenas local. Esquemas e dados são processados no seu navegador. Nada é enviado.

Exemplo prático#

Um objeto user tem de ter um name, e age tem de ser um inteiro não negativo. Cole este esquema à esquerda no modo Validar:

{
  "type": "object",
  "properties": {
    "name": { "type": "string" },
    "age": { "type": "integer", "minimum": 0 }
  },
  "required": ["name"]
}

Agora teste um documento que parte ambas as regras — name em falta, e age negativo:

{
  "age": -3
}

O painel Violações reporta duas infrações, cada uma fixada onde aconteceu:

(root) — must have required property 'name'
/age   — must be >= 0

O caminho (root) diz-lhe que a propriedade obrigatória em falta é um problema ao nível do documento; /age aponta direito para o campo ofensor. Corrija os dados para {"name":"ada","age":36} e o estado muda para válido com uma lista de violações vazia. O texto da razão é a redação própria da palavra-chave do Ajv, mantida à letra para corresponder ao que os seus registros de produção dirão.

FAQ#

Draft-07, 2019-09 ou 2020-12 — qual devo escolher?#

Draft-07 é a predefinição pragmática: a esmagadora maioria dos esquemas em tutoriais, bibliotecas e especificações OpenAPI visa-o, e tudo o que provavelmente vai precisar (type, properties, required, minimum, format, $ref) funciona aí. Mude para 2019-09 ou 2020-12 apenas quando o seu esquema usa explicitamente funcionalidades que esses drafts acrescentaram — como unevaluatedProperties ou o comportamento revisto de $ref. Escolher o draft errado normalmente ainda funciona, mas a escolha segura é o draft que o autor do esquema pretendeu.

Porque é que as mensagens de violação estão em inglês?#

São o texto de razão próprio do Ajv para cada palavra-chave (must have required property, must be >= 0, e por aí), passado inalterado. A ideia é a consistência: estas são as strings exatas que a validação do seu servidor vai registrar, pelo que correspondê-las aqui torna um desalinhamento trivialmente pesquisável nos registros de produção.

O que significa “modo estrito relaxado”?#

O modo estrito do Ajv rejeita esquemas que considera descuidados — uma palavra-chave desconhecida, um $ref que não consegue resolver, um type em falta. Isso é útil num pipeline de build mas errado para uma ferramenta de validação, cujo trabalho é verificar dados contra qualquer esquema que lhe entreguem. Esta página desliga o modo estrito, pelo que um esquema não-estrito compila e corre em vez de lançar um erro.

Posso inferir um esquema e depois validar contra ele?#

Sim — essa é a viagem de ida-e-volta pretendida. Cole um exemplo representativo no modo Inferir, copie o esquema gerado, mude para Validar, e cole o esquema de volta à esquerda. O esquema inferido volta a validar o exemplo original de forma limpa, e a partir daí pode verificar todos os documentos novos contra ele.