Neste artigo
O que é JSON Schema?
JSON Schema é um vocabulário para anotar e validar documentos JSON. Ele define a estrutura, os tipos e as restrições que um documento JSON deve satisfazer. Pense nele como um contrato — o schema descreve como dados válidos parecem, e os validadores verificam se um documento está em conformidade com esse contrato.
JSON Schema é escrito no próprio JSON, tornando-o legível por máquinas e independente de linguagem. É suportado por validadores em todas as principais linguagens de programação (JavaScript/Ajv, Python/jsonschema, Java/everit, Go/gojsonschema) e é usado para validação de API, arquivos de configuração e geração de formulários.
Fundamentos do JSON Schema
As palavras-chave principais definem a estrutura dos documentos JSON válidos.
- type — especifica o tipo JSON permitido: string, number, integer, boolean, object, array ou null. A restrição mais fundamental.
- properties e required — para objetos, 'properties' define o schema de cada campo e 'required' lista quais campos devem estar presentes. Campos fora de 'required' são opcionais por padrão.
- enum e const — 'enum' restringe um valor a um conjunto fixo de opções, enquanto 'const' o restringe a um único valor exato. Útil para campos de status, categorias e opções de configuração.
- pattern e format — 'pattern' valida strings contra uma expressão regular. 'format' fornece validação semântica como 'email', 'uri', 'date-time' e 'ipv4' sem regex.
Essas palavras-chave básicas cobrem a maioria das necessidades de validação. Um schema simples pode definir um tipo objeto com propriedade 'name' (string) obrigatória e 'age' (integer, mínimo 0) opcional.
Recursos avançados do esquema
Para requisitos de validação complexos, o JSON Schema oferece composição, referências e lógica condicional.
- Referências $ref — reutilize definições de schema referenciando-as com $ref. Aponte para definições dentro do mesmo documento ($ref: #/$defs/Address) ou arquivos externos. Elimina duplicação em schemas grandes.
- allOf / anyOf / oneOf — palavras-chave de composição que combinam múltiplos schemas. 'allOf' exige que todos os sub-schemas correspondam, 'anyOf' exige pelo menos um e 'oneOf' exige exatamente um. Útil para tipos polimórficos.
- if / then / else — schemas condicionais que aplicam diferentes regras de validação com base nos valores dos dados. Por exemplo, se o país for 'US', o CEP deve corresponder a um padrão de 5 dígitos; caso contrário, qualquer formato é permitido.
- additionalProperties — controla se um objeto pode conter propriedades não listadas em 'properties'. Defina como false para validação estrita ou como um schema para restringir propriedades extras.
Experimente gratuitamente — sem cadastro
Validar JSON Schema →Versões de rascunho do esquema
O JSON Schema evoluiu por várias versões de rascunho, cada uma adicionando novos recursos e refinando o comportamento existente.
- Draft-04 — a primeira versão amplamente adotada. Introduziu $ref, required como array e palavras-chave básicas de validação. Ainda usado em muitos sistemas legados e OpenAPI 3.0.
- Draft-06 — adicionou a palavra-chave const, propertyNames, contains para arrays e schemas booleanos (true/false como schemas válidos). Adições menores, mas úteis.
- Draft-07 — adicionou lógica condicional if/then/else, anotações readOnly/writeOnly e palavras-chave de codificação de conteúdo. A versão de rascunho mais popular hoje.
- 2019-09 (Draft 2019-09) — grande reestruturação. Introduziu $defs (substituindo definitions), $anchor, unevaluatedProperties e o sistema de vocabulário. Melhor para design de schemas em larga escala.
- 2020-12 (Draft 2020-12) — o rascunho estável mais recente. Referências dinâmicas refinadas, prefixItems adicionado para validação de tuplas (substituindo items como array) e formatos de saída melhorados. Recomendado para novos projetos.
Casos de uso comuns
JSON Schema é usado em qualquer lugar onde dados JSON precisam ser validados ou documentados.
- Validação de API — valide corpos de requisição e parâmetros de consulta contra schemas em middleware Express/Fastify. As especificações OpenAPI/Swagger incorporam JSON Schema para definição de contratos de API.
- Validação de configuração — valide arquivos de configuração da aplicação (JSON, YAML convertido para JSON) na inicialização. Detecte erros de digitação e campos ausentes antes que causem erros em tempo de execução.
- Geração de formulários — ferramentas como react-jsonschema-form e vue-jsonschema-form geram automaticamente formulários HTML a partir de definições JSON Schema, incluindo regras de validação e widgets de interface.
- Geração de código — gere interfaces TypeScript, structs Go ou dataclasses Python a partir de definições JSON Schema. Mantém os tipos sincronizados com os contratos de API.
Erros de validação comuns
Ao validar JSON contra um schema, estes são os erros mais frequentes que você encontrará.
- Incompatibilidade de tipo — o tipo do valor não corresponde à restrição 'type' do schema. Exemplos comuns: string onde number é esperado, null para um campo não anulável, ou um objeto onde um array é necessário.
- Campos obrigatórios ausentes — o objeto JSON está sem uma propriedade listada no array 'required'. Os validadores informam qual campo específico está faltando.
- Falha de padrão — um valor de string não corresponde à regex 'pattern'. Isso geralmente detecta formatos de e-mail inválidos, números de telefone ou identificadores personalizados que não seguem o padrão esperado.
- Falha na resolução de $ref — o esquema referencia outro esquema via $ref que não pode ser encontrado. Isso acontece quando uma entrada em $defs está ausente, o caminho está errado ou os arquivos de esquema externos não estão acessíveis.
Perguntas frequentes
Qual rascunho de JSON Schema devo usar em novos projetos?
Use o Draft 2020-12 para novos projetos, a menos que haja restrições. Ele tem mais recursos (prefixItems para tuplas, unevaluatedProperties, referências dinâmicas) e a melhor qualidade de especificação. Se precisar de compatibilidade com OpenAPI 3.0, use o Draft-04. Se precisar do suporte mais amplo de bibliotecas, o Draft-07 é a escolha mais segura — quase todos os validadores o suportam.
Como reutilizar esquemas em vários arquivos?
Use $ref para referenciar esquemas por URI. Para definições locais, coloque esquemas reutilizáveis em $defs no mesmo arquivo e referencie-os com $ref: '#/$defs/NomeDoEsquema'. Para referências entre arquivos, use URIs relativas ($ref: './address.json') ou absolutas. A maioria dos validadores suporta a resolução de $ref tanto local quanto remota.
O JSON Schema pode validar objetos aninhados?
Sim. Defina esquemas aninhados em 'properties' do objeto pai. Cada propriedade aninhada pode ter seu próprio tipo, campos obrigatórios e regras de validação. Para estruturas muito aninhadas, use $ref para manter o esquema legível. Não há limite de profundidade de aninhamento — o validador valida recursivamente cada nível.