Validador de JSON Schema | Alterne entre draft-07, 2019-09 e 2020-12 no navegador

Ferramenta leve para validar respostas de API, trechos extraídos de um OpenAPI ou arquivos de configuração contra um JSON Schema. Troque entre os três drafts principais com um clique e veja cada erro com caminho JSON Pointer, palavra-chave e mensagem em uma tabela.

💡 Sobre esta ferramenta

JSON Schema é a linguagem declarativa padrão para descrever a estrutura permitida de um JSON: contratos REST, payloads de webhooks, arquivos de configuração e autocomplete do settings.json no VS Code. O ponto que mais consome tempo no dia a dia raramente é ler o schema — é localizar exatamente qual palavra-chave quebra com uma instância específica. Instalar ajv-cli via npm i -g é exagero para uma revisão pontual de PR, e plugins de IDE costumam estar amarrados a uma versão fixa de draft. Esta ferramenta cobre exatamente esse meio-termo.

Selecione draft-07, 2019-09 ou 2020-12 conforme a versão usada pela sua cadeia de ferramentas. O validador analisa ambas as entradas com JSON.parse nativo e executa uma implementação subset da especificação. Os erros aparecem em uma tabela de três colunas — instancePath (JSON Pointer), keyword e mensagem — permitindo rastrear falhas em properties profundamente aninhados sem se perder. Ative o modo "Apenas o primeiro" para uma saída antecipada na primeira violação encontrada, especialmente útil ao depurar schemas grandes em etapas.

As palavras-chave cobertas são as do núcleo: type, required, enum, const, minLength, maxLength, pattern, minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf, minItems, maxItems, uniqueItems, prefixItems, items, minProperties, maxProperties, additionalProperties, patternProperties, format (subset), allOf, anyOf, oneOf, not e schemas booleanos false. O que não é resolvido: $ref / $defs, dependentSchemas, contains, if/then/else e unevaluatedProperties / unevaluatedItems. Se o seu schema depende dessas palavras-chave, complemente com ajv ou jsonschema no CI — esta ferramenta cumpre o papel de checagem prévia, não de validador de produção.

🧐 Perguntas frequentes

Q. O que muda ao alternar a versão do draft? Em 2020-12, items aceita apenas um único schema; a validação tipo tupla migrou para prefixItems. Este validador implementa prefixItems nativamente e ainda aceita items como array em 2019-09 e draft-07. exclusiveMinimum e exclusiveMaximum são tratados como numéricos nos três drafts.

Q. Quão rigorosa é a verificação de format? email, uri, url, uuid, date, time, date-time, ipv4, ipv6 e hostname são checados via expressões regulares internas — um subset rápido, não conformidade RFC completa. Para revisão estrita de bits de variant do UUID ou date-time ciente de segundos intercalares, sobreponha ajv-formats no seu passo de CI.

Q. Schemas com $ref funcionam? O parsing passa, mas os destinos de $ref não são desreferenciados — as restrições atrás da referência simplesmente não são aplicadas, então a instância pode aparecer como válida mesmo quando o schema referenciado a rejeitaria. Use ajv ou outra implementação completa quando a resolução de $ref for crítica.

Q. A lista de erros está enorme — como priorizo? Mude "Erros" para "Apenas o primeiro" e o validador sai na primeira violação encontrada. Combinado com schemas profundos, é a forma mais rápida de subir a árvore de falhas sem que 200 erros em cascata escondam a causa raiz.

Q. Existe um limite de tamanho de entrada? Não há teto explícito, mas JSON.parse roda na thread principal e consome memória real. Payloads de vários megabytes pertencem ao CI com ajv; esta ferramenta foi dimensionada para corpos de requisição únicos, fixtures e amostras de webhook.

Q. Posso reaproveitar a saída de erros? O botão Copiar abaixo da tabela coloca no clipboard um array JSON de registros {instancePath, schemaPath, keyword, message}. Cole diretamente em um Issue do GitHub, comentário de PR ou relatório de testes.

📚 Curiosidades

O histórico de versões do JSON Schema é incomum: draft-04 (2013) → draft-06 (início de 2017) → draft-07 (fim de 2017) → draft-2019-09 → draft-2020-12. A numeração saltou de sequencial para etiquetas ano-mês por volta de 2019, quando o grupo de trabalho do IETF deixou claro que "draft" aqui significa número de revisão, não "incompleto". Apesar da conotação, draft-07 segue como o mais usado porque está cravado no OpenAPI 3.0 (a spec 3.1 finalmente adotou 2020-12).

No ecossistema lusófono de desenvolvimento, JSON Schema apareceu primeiro pela mão da comunidade de APIs Rails / Sinatra (json-schema gem) e hoje é central em stacks Node.js como Fastify e NestJS combinados com @sinclair/typebox. Palavras-chave anotativas (description, examples, default, deprecated) não interferem na validação mas alimentam Swagger UI, Stoplight e Redoc — vale documentar mesmo schemas internos para que a equipe de produto consiga ler o contrato sem abrir o código.