Validador de JSON Schema para estrutura, campos e tipos

Um JSON Schema é, ele próprio, um documento JSON que descreve o formato esperado de outros documentos JSON. Enquanto a validação de sintaxe apenas confirma que o texto está bem formado, a validação de schema vai muito além: ela verifica se o conteúdo faz sentido para a sua aplicação. Um JSON pode ser perfeitamente válido em sintaxe e ainda assim estar errado para o seu caso, por exemplo se faltar o campo email, se a idade vier como texto em vez de número, ou se um campo obrigatório estiver ausente. O schema formaliza esse contrato. Você define uma vez como os dados devem ser e passa a validar qualquer documento contra essa definição, em vez de checar campo por campo manualmente no código.

Os dois usos mais frequentes de um schema são exigir campos obrigatórios e fixar tipos. A palavra-chave required lista as propriedades que precisam existir no objeto; se qualquer uma faltar, a validação falha e aponta qual delas está ausente. A palavra-chave type define o tipo esperado de cada valor, como string, number, boolean, object, array ou null. Assim, se o schema diz que preco deve ser number e o documento traz o preço como texto entre aspas, a validação acusa incompatibilidade de tipo, porque o valor veio como string. Esse tipo de verificação é exatamente o que evita erros silenciosos mais adiante, quando o código assume um número e recebe texto. A ferramenta mostra o campo divergente e o tipo esperado contra o encontrado.

Um schema pode ir bem além de campos obrigatórios e tipos. Com properties você descreve cada propriedade de um objeto e pode aninhar schemas para estruturas complexas, validando objetos dentro de objetos e arrays de objetos. Restrições como minimum e maximum limitam faixas numéricas, minLength e maxLength controlam o tamanho de strings, pattern aplica uma expressão regular, enum restringe um valor a uma lista fixa de opções e items descreve o formato de cada elemento de um array. Há ainda additionalProperties para decidir se campos não previstos são aceitos. Combinando essas palavras-chave, você expressa regras de negócio inteiras de forma declarativa. A validação percorre o documento aplicando cada regra e relata as que não foram cumpridas, com o caminho até o campo em questão.

Para usar a ferramenta, você fornece dois textos: o documento JSON e o JSON Schema contra o qual quer validá-lo. Antes de comparar os dois, ambos precisam ser JSON sintaticamente válido, então um schema mal formado também será sinalizado. A validação acontece inteiramente no navegador: nem o seu documento nem o seu schema são enviados para um servidor ou armazenados em qualquer lugar. Isso importa porque schemas costumam refletir a estrutura interna dos seus dados e das suas APIs, informação que você prefere manter privada. O padrão JSON Schema é mantido por uma especificação aberta e existe em várias versões, chamadas de drafts, então vale conferir se o seu schema declara a versão adequada por meio da palavra-chave que identifica o schema, para evitar ambiguidades na interpretação das regras.

Como nas demais verificações, a ferramenta aponta e explica cada divergência, mas não altera o seu JSON nem o seu schema por conta própria. A correção é sua, e isso é desejável: você decide se ajusta o documento para atender ao contrato ou se, na verdade, é o schema que precisa evoluir. O fluxo típico é validar, ler quais campos falharam e por qual regra, corrigir o lado apropriado e validar de novo, até o documento passar limpo contra o schema. Esse ciclo é especialmente útil ao integrar com uma API de terceiros: você modela o schema a partir da documentação e valida as respostas reais contra ele, descobrindo rapidamente quando o retorno diverge do combinado, antes que isso vire um bug dentro da sua aplicação.