O que é um JSON Schema?

Um JSON Schema descreve como um documento JSON deve ser: quais propriedades um objeto tem, quais são obrigatórias, o tipo de cada valor, os intervalos e comprimentos permitidos, padrões e formatos, como endereços de e-mail ou datas. APIs, arquivos de configuração e construtores de formulários usam schemas para verificar os dados antes de confiar neles, e o OpenAPI descreve os corpos das solicitações e respostas com eles.

Como usar o validador

  1. Cole ou digite o JSON Schema na primeira caixa.
  2. Cole ou digite os dados JSON que deseja verificar na segunda caixa.
  3. O resultado aparece enquanto você digita: o JSON é válido ou todos os erros são listados com o caminho do valor que falha, a palavra-chave do schema que ele viola e uma breve explicação.
  4. Cada valor inválido é marcado nos dados. Clique em um erro para rolar até ele nos dados ou clique em uma marcação para localizar o erro correspondente na lista.

O campo Versão do Schema mostra em relação a qual versão do JSON Schema os dados foram verificados.

Quais versões são compatíveis

A palavra-chave $schema do schema define a versão:

  • Versão 2020-12: https://json-schema.org/draft/2020-12/schema
  • Versão 2019-09: https://json-schema.org/draft/2019-09/schema
  • Versão 7: http://json-schema.org/draft-07/schema#
  • Versão 6: http://json-schema.org/draft-06/schema#

A versão 7 é usada para verificar um schema sem $schema. A versão 4 e as anteriores não são compatíveis. Primeiro, o próprio schema é verificado em relação ao meta-schema da sua versão; assim, um erro de digitação como "type": "strin" é informado como um schema inválido, em vez de ser ignorado. Anotações como title, description e examples são aceitas, assim como palavras-chave desconhecidas pela versão, como suas próprias anotações x-: elas são ignoradas.

Como interpretar os erros

  • Os caminhos são escritos como JSONPath, começando por $, que representa o documento inteiro: $.ingredients[1].unit é a propriedade unit do segundo ingrediente.
  • A ausência de uma propriedade obrigatória é informada no objeto que deveria contê-la, com o nome da propriedade na mensagem.
  • Uma propriedade adicional não permitida pelo schema aponta para o nome dessa propriedade.
  • Para enum e const, a mensagem lista os valores permitidos.
  • Com anyOf e oneOf, cada alternativa que falha acrescenta seus próprios erros, seguidos por um erro referente à própria palavra-chave; assim, um único valor incorreto pode gerar vários erros.

As mensagens de erro são fornecidas pela biblioteca Ajv, em inglês.

Formatos

Os valores com um format também são verificados: email, uri, uri-reference, date, time, date-time, duration, uuid, ipv4, ipv6, hostname, regex, json-pointer e outros. Um formato desconhecido pelo validador é ignorado, conforme permitido pela especificação JSON Schema.

Referências

$ref funciona para definições dentro do mesmo schema, como #/$defs/address ou #/definitions/address. Referências a outros arquivos ou URLs não são carregadas: um schema que dependa de uma delas é informado como inválido, junto com a referência que não pôde ser resolvida.

Como funciona

A ferramenta valida com o Ajv, um validador de JSON Schema amplamente usado, e verifica os formatos com ajv-formats. Tudo é executado no seu navegador: o schema e os dados nunca são enviados.

Recursos

  • Compatibilidade com as versões 6, 7, 2019-09 e 2020-12 do JSON Schema, selecionadas por $schema
  • Todos os erros, com caminho, palavra-chave e mensagem
  • Valores inválidos marcados nos dados, com clique para rolar até eles
  • Verificação de formatos de e-mail, URIs, datas, UUIDs, endereços IP e outros
  • Verificação do schema em relação ao seu meta-schema
  • Linha e coluna dos erros de sintaxe JSON
  • Execução no seu navegador