Entendendo JSON Schema: Valide seus dados como um profissional

Já teve um bug onde sua API retornou "42" (uma string) em vez de 42 (um número) e tudo que vinha depois quebrou? Ou alguém enviou uma requisição sem um campo obrigatório e seu app crashou em vez de retornar um erro útil? JSON Schema existe exatamente para prevenir esse tipo de problema.

Pense nele como uma planta para seus dados JSON — descreve qual forma os dados devem ter e captura qualquer coisa que não corresponda.

Como JSON Schema se parece

JSON Schema é escrito em JSON (meta, né?). Aqui está um schema simples para um objeto de usuário:

Isso diz: "Espero um objeto com um name obrigatório (string não vazia) e um email (formato de email válido), mais um age opcional (inteiro entre 0 e 150)." Se alguém enviar {"name": "", "email": "not-an-email"}, o validador vai detectar ambos os problemas.

Construindo schemas passo a passo

Comece pelo tipo. Todo schema começa com "type": object, array, string, number, integer, boolean ou null.

Adicione restrições. Para strings: minLength, maxLength, pattern (regex). Para números: minimum, maximum, multipleOf. Para arrays: minItems, maxItems, uniqueItems. O guia oficial JSON Schema tem a lista completa.

Marque campos obrigatórios. Use o array "required" no nível do objeto. Liste apenas os campos que realmente precisam estar presentes — não torne tudo obrigatório a menos que seja intencional.

Defina objetos aninhados. Basta aninhar definições de schema dentro de "properties". Aqui está um usuário com um endereço:

Aquele pattern no CEP? Garante que apenas CEPs americanos de 5 dígitos sejam aceitos. Validação prática como essa impede que dados lixo se infiltrem no seu banco de dados.

Por que você realmente deveria usar isso

Validação de API: Valide os corpos das requisições entrantes na borda da sua API. Dados ruins são rejeitados com mensagens de erro claras antes de tocar sua lógica de negócio. A maioria dos frameworks suporta isso — Ajv para JavaScript é extremamente rápido.

Validação de configuração: Valide arquivos de config na inicialização do app. Falhe rápido com uma mensagem clara como "sua configuração está sem o campo database.host" em vez de uma exceção críptica de ponteiro nulo 5 minutos depois.

Documentação: JSON Schema serve como documentação viva. Ferramentas como Swagger UI geram docs de API diretamente dos schemas.

Geração de código: Gere interfaces TypeScript, structs Go ou dataclasses Python a partir do seu schema. Escreva uma vez, use em todo lugar.

Testes: Valide respostas de API na sua suite de testes para detectar regressões automaticamente.

Começar em 30 segundos

O jeito mais rápido de começar? Gere um schema a partir de dados JSON existentes. Cole uma resposta JSON de exemplo no nosso JSON Schema Generator — ele vai analisar os dados e produzir um schema que você pode refinar. Depois use nosso JSON Schema Validator para testá-lo contra dados reais.

Você também pode validar programaticamente. Aqui está um exemplo rápido em Node.js com Ajv:

Para Python, confira a biblioteca jsonschema. Para Java, tem o everit-json-schema. Praticamente toda linguagem tem suporte sólido — confira a lista completa de implementações.

Recursos avançados de Schema que você deve conhecer

Depois que dominar o básico, JSON Schema tem recursos poderosos que tornam a validação complexa possível.

oneOf, anyOf, allOf — Combinando Schemas:

Às vezes um campo pode ser um de vários tipos. Por exemplo, uma API pode aceitar tanto um ID de string quanto um ID numérico:

Esse schema aceita tanto {"id": "PRD-1234"} quanto {"id": 42}, mas rejeita {"id": -1} ou {"id": "invalid"}.

$ref — Definições de Schema reutilizáveis:

Conforme seus schemas crescem, você vai querer evitar repetir as mesmas definições. A palavra-chave $ref permite referenciar definições compartilhadas:

Agora tanto billing_address quanto shipping_address usam exatamente as mesmas regras de validação. Altere a definição de address uma vez, e ambos os campos são atualizados. Isso é essencial para manter schemas grandes gerenciáveis.

additionalProperties — Trave seus objetos:

Por padrão, JSON Schema permite propriedades adicionais que não estão listadas em properties. Isso frequentemente NÃO é o que você quer — campos inesperados podem indicar um bug do cliente ou incompatibilidade de versão. Defina "additionalProperties": false para rejeitar campos desconhecidos:

Com esse schema, {"name": "Alice", "email": "[email protected]", "admin": true} seria rejeitado porque admin não é uma propriedade definida.

Erros comuns de JSON Schema

Até desenvolvedores experientes cometem esses erros ao escrever schemas:

1. Esquecer que required fica no nível do objeto, não no nível da propriedade. Isso está errado:

O jeito correto é:

2. Usar "type": "number" quando você quer dizer "type": "integer". O tipo number aceita decimais como 3.14, enquanto integer só aceita números inteiros. Se seu campo é um contador ou um ID, use integer.

3. Não especificar format para padrões comuns. JSON Schema tem validadores de formato embutidos para email, uri, date-time, ipv4, ipv6, uuid e mais. Use-os em vez de escrever padrões regex complexos.

4. Tornar tudo obrigatório. Só marque campos como obrigatórios se eles realmente precisam estar presentes. Restringir demais seu schema torna a evolução da API mais difícil — adicionar um novo campo opcional é uma mudança não-disruptiva, mas você perde essa flexibilidade se tudo for obrigatório.

Exemplo do mundo real: Schema de produto E-Commerce

Vamos ver um schema prático que você poderia usar para uma API de produtos:

Esse schema garante que todo produto tenha um nome (1-200 caracteres), um preço positivo e uma categoria de uma lista fixa. Tags são opcionais, mas devem ser strings únicas com no máximo 10. A palavra-chave enum é incrivelmente útil para campos que só devem aceitar valores específicos.

Versões do JSON Schema: Qual Draft usar

JSON Schema passou por vários drafts — cada um publicado como um Internet-Draft do IETF — e isso pode ser confuso para iniciantes. Aqui vai um resumo rápido:

Para novos projetos, use 2020-12 (o mais recente). Se você está trabalhando com uma base de código existente, verifique qual draft seu validador suporta. A maioria dos validadores modernos como Ajv suportam Draft 7 e posteriores.

Integrando JSON Schema no seu fluxo de trabalho

Aqui está uma abordagem prática para adicionar validação JSON Schema a uma API Express.js:

Esse padrão te dá validação automática de requisições com mensagens de erro claras. A opção allErrors: true garante que todos os erros de validação são reportados de uma vez, não apenas o primeiro.

Experimente você mesmo

Pronto para adicionar validação de schema ao seu projeto? Comece com estas ferramentas:

• JSON Schema Generator — Cole qualquer dado JSON e obtenha um schema gerado automaticamente. Perfeito para criar schemas a partir de respostas de API de exemplo.
• JSON Schema Validator — Teste seu schema contra dados reais para garantir que ele detecta o que deveria e permite o que deveria.
• JSON Validator — Verifique rapidamente se seu JSON é sintaticamente válido antes de se preocupar com validação de schema.

JSON Schema pode parecer trabalho extra no começo, mas se paga muitas vezes ao detectar bugs na fronteira do seu sistema em vez de no fundo da sua lógica de negócio.