O guia completo do JSON Schema (Draft 7)
O JSON Schema é um contrato para os seus dados: ele declara quais propriedades devem existir, que tipos elas têm e quais valores são permitidos. Este guia cobre as principais palavras-chave do Draft 7 com um exemplo realista de API.
O que é JSON Schema?
Um JSON Schema é, ele próprio, um documento JSON que descreve o formato de outros dados JSON. Use-o para validar payloads de API, documentar formatos esperados, gerar código (TypeScript, Go) e interceptar dados inválidos antes que atinjam a sua lógica.
Palavras-chave essenciais
A palavra-chave type restringe um valor a string, number, boolean, null, object ou array. properties e required descrevem o formato de um objeto; items descreve os elementos de um array.
{
"type": "object",
"properties": {
"name": { "type": "string", "minLength": 1 },
"age": { "type": "number", "minimum": 0, "maximum": 150 },
"email": { "type": "string", "format": "email" }
},
"required": ["name", "email"]
}Além do type: enum restringe a um conjunto fixo, const exige um valor exato, pattern casa com uma expressão regular, minLength/maxLength limitam o tamanho da string e additionalProperties: false proíbe chaves desconhecidas.
Um schema real de API
Aqui está um schema para um endpoint de registro de usuário. Note como cada restrição funciona também como documentação e como required + additionalProperties: false tornam o contrato rigoroso.
{
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"username": { "type": "string", "pattern": "^[a-zA-Z0-9_]{3,30}$" },
"email": { "type": "string", "format": "email" },
"password": { "type": "string", "minLength": 8 },
"acceptTerms": { "type": "boolean", "const": true }
},
"required": ["username", "email", "password", "acceptTerms"],
"additionalProperties": false
}Melhores práticas
Sempre declare $schema para que os validadores saibam qual draft você está almejando. Adicione campos description — eles se transformam em documentação viva da API. Prefira format (email, uri) a expressões regulares feitas à mão. Use additionalProperties: false para APIs rigorosas, mas permita-o quando a extensibilidade importar. Evite schemas profundamente aninhados — fatore com $ref e definitions.
FAQ
- Qual draft do JSON Schema este guia cobre?
- O Draft 7, a versão com suporte mais amplo. Ele cobre type, properties, required, items, enum, const, minimum/maximum, minLength/maxLength, pattern, format, additionalProperties, minItems/maxItems e uniqueItems.
- O TypeScript substitui o JSON Schema?
- Não. Os tipos do TypeScript são apagados em tempo de compilação e não oferecem validação em tempo de execução. Para payloads de API, use JSON Schema (ou Zod) para validar em tempo de execução e, opcionalmente, gere tipos TypeScript a partir dele.
- Posso gerar automaticamente um schema a partir de um JSON?
- Sim — infira um schema a partir de dados de exemplo e depois refine-o adicionando restrições (required, pattern, limites de tamanho). A geração dá a você um ponto de partida, não um contrato finalizado.
Artigos relacionados
O que é JSON? Um guia completo para iniciantes →
JSON (JavaScript Object Notation) é um formato leve de troca de dados, fácil de ler por humanos e de analisar por máquinas. Aprenda a sintaxe, os tipos de dados e a estrutura que sustentam as APIs modernas.
A história do JSON: de 2000 a padrão da indústria →
Acompanhe o JSON desde a ideia de Douglas Crockford em 2001, passando pela adoção pelo Yahoo, até se tornar o padrão ECMA-404 que sustenta 90% das APIs modernas.
Exemplos de JSON em 7 linguagens: JavaScript, Python, Go, Rust, PHP, Java, C# →
Exemplos prontos para produção de análise (parsing) e serialização de JSON em sete linguagens — com tratamento de erros e melhores práticas.