JSON Schema Validator

O que é JSON Schema e por que é importante?

JSON (JavaScript Object Notation) é a língua franca das APIs web, arquivos de configuração e troca de dados. Mas o JSON puro não tem um sistema de tipos embutido — um campo pode ser uma string em um dia e um número no outro, e a única forma de descobrir a incompatibilidade é um erro em tempo de execução ou um bug de dados sutil. O JSON Schema preenche essa lacuna: é um vocabulário declarativo para descrever a estrutura esperada e as restrições de um documento JSON, validado contra dados reais em tempo de execução.

As equipes utilizam JSON Schema para validar payloads de requisições de API antes de processá-los, para impor o formato dos arquivos de configuração carregados na inicialização, para gerar automaticamente documentação e formulários de UI a partir de uma única fonte de verdade, e para manter a consistência de contratos entre microsserviços. OpenAPI — o padrão para documentação de APIs REST — é construído diretamente sobre JSON Schema, tornando-o o padrão de validação de dados mais amplamente implantado na web.

Versões do rascunho de JSON Schema: Draft-07, Draft 2019-09 e Draft 2020-12

O JSON Schema passou por vários rascunhos de especificação. O Draft-07, lançado em 2018, continua sendo o mais amplamente suportado em todas as principais bibliotecas de validadores e é o dialeto usado pelo OpenAPI 3.0. Ele introduziu as poderosas palavras-chave de validação condicional if/then/else, as anotações de propriedade readOnly/writeOnly e as palavras-chave de codificação de conteúdo. Se você está escrevendo schemas hoje e não precisa dos recursos mais recentes, o Draft-07 é a escolha mais segura para máxima compatibilidade com o ecossistema.

O Draft 2020-12 é a especificação estável atual e introduz várias mudanças significativas: a palavra-chave items é substituída por prefixItems para validação de tuplas, as referências dinâmicas usam $dynamicRef em vez de $recursiveRef, e as novas palavras-chave unevaluatedProperties e unevaluatedItems fornecem controle mais preciso sobre conteúdo adicional.

Palavras-chave principais do JSON Schema explicadas

A palavra-chave type impõe um tipo de dado: string, number, integer, boolean, array, object ou null. required lista as propriedades que devem estar presentes em um objeto. properties mapeia cada nome de propriedade para seu próprio subesquema. pattern aplica uma expressão regular a um valor de string. minimum, maximum, minLength e maxLength restringem intervalos numéricos e de string. enum restringe um valor a um conjunto fixo de valores permitidos; const restringe a um único valor.

As palavras-chave de composição permitem construir regras complexas a partir de blocos de construção simples: allOf funciona como AND lógico, anyOf como OR e oneOf como XOR. A palavra-chave not inverte um esquema. As palavras-chave if/then/else habilitam a validação condicional. Juntas, permitem expressar quase qualquer regra de validação sem escrever código imperativo personalizado.

JSON Schema em produção: contratos de API e pipelines de CI

Em sistemas de produção, a validação de JSON Schema roda no lado do servidor ou em pipelines de CI usando bibliotecas como Ajv (JavaScript/Node.js), jsonschema (Python) ou Newtonsoft.Json (C#). Os schemas são commitados no controle de versão junto com o código da aplicação para que as mudanças de contrato sejam revisadas e rastreadas como qualquer outra mudança. Mudanças quebradas — remover um campo obrigatório, restringir um tipo — são detectadas na revisão de código antes de chegarem à produção.

Esta ferramenta baseada no navegador é ideal para projetar e depurar schemas iterativamente antes de commitá-los. Cole seus dados, escreva seu schema, clique em Validar, leia as mensagens de erro detalhadas e refine — sem servidor, sem npm install, sem idas e vindas. O validador também formata seu JSON em cada execução de validação, tornando-o um prático formatador JSON combinado e testador de schemas.

Exemplo prático: Validando uma resposta de API

Suponha que sua API retorna um objeto de usuário. Um JSON Schema que o valida pode exigir um id inteiro, um nome de string não vazio, um email de string correspondendo a um padrão de email e um papel de string opcional de um enum de 'admin', 'editor' e 'viewer'. Definir additionalProperties como false garante que sua API nunca retorne silenciosamente campos não documentados dos quais os consumidores posteriores possam inadvertidamente depender.

O recurso if/then/else habilita regras condicionais — por exemplo, se o papel for 'admin' então um array de permissões é obrigatório, caso contrário está proibido. Essas regras composicionais permitem que um único schema cubra múltiplas formas válidas de um objeto sem duplicar definições de propriedades.

Como o UtiloKit se compara a outros validadores de JSON Schema

A maioria das ferramentas de validação de JSON Schema online se enquadra em duas categorias: construtores visuais de schemas e validadores de API no lado do servidor. O jsonschema.net obriga você a passar por uma UI de apontar e clicar para construir schemas — é útil para iniciantes aprendendo a estrutura de schemas, mas lento para desenvolvedores que já sabem quais palavras-chave precisam.

O jsonschemavalidator.net, construído sobre a biblioteca Newtonsoft.Json da Microsoft, reporta erros usando caminhos de propriedade .NET e códigos de erro que parecem desconhecidos para desenvolvedores JavaScript. Ferramentas como Stoplight e SwaggerHub validam schemas como parte de um documento OpenAPI completo e exigem configuração de projeto e conta.

O validador do UtiloKit roda no mesmo motor Ajv que alimenta a maioria das aplicações Node.js, Express e Fastify. As mensagens de erro, os caminhos de ponteiro JSON e o comportamento das palavras-chave correspondem exatamente ao seu ambiente de produção — e roda de graça no seu navegador sem conta, sem upload, sem limite de tamanho de arquivo e sem limite de uso diário.