JSON Schema é uma forma de descrever como deve ser a estrutura de um documento JSON, usando outro documento JSON. Em vez de validar dados manualmente com condicionais no código, é possível descrever declarativamente os tipos esperados, campos obrigatórios e restrições de valores, e então verificar os dados automaticamente.
Principais palavras-chave do draft-07
type— o tipo de valor esperado (object, string, number, array etc.).required— a lista de campos de um objeto que devem obrigatoriamente estar presentes.properties— a descrição do esquema para cada campo do objeto individualmente.enum— restringe um valor a um conjunto específico de opções.pattern— valida uma string com uma expressão regular, por exemplo para o formato do CPF.
Exemplo: pattern para o CPF brasileiro
O CPF brasileiro segue o formato 123.456.789-00: três grupos de três dígitos separados por ponto, seguidos de um hífen e dois dígitos verificadores. Num schema usado para testar o contrato de uma API de cadastro, isso pode ser descrito como "cpf": {"type": "string", "pattern": "^\\d{3}\\.\\d{3}\\.\\d{3}-\\d{2}$"}. Isso não confere se os dígitos verificadores batem com o algoritmo oficial do CPF — para isso é preciso lógica adicional —, mas já rejeita na hora um CPF sem pontuação, com letras ou com o número errado de dígitos, antes de chegar à lógica de negócio.
Em que isso difere da validação de sintaxe
A validação comum de JSON verifica apenas se o texto é sintaticamente correto — chaves, aspas e vírgulas no lugar certo. O JSON Schema verifica muito mais: se um objeto tem um campo obrigatório email, se o valor de age é um número e não uma string, se status está entre os valores permitidos.
Para que serve
- Verificar se a resposta de uma API de terceiros corresponde ao contrato documentado.
- Validar arquivos de configuração antes do deploy para pegar um erro mais cedo.
- Documentar a estrutura de dados esperada num formato que já pode ser verificado automaticamente.
additionalProperties: é possível adicionar campos extras?
Por padrão, o JSON Schema permite que um objeto tenha qualquer campo além dos descritos em properties — required e properties apenas estabelecem um mínimo, não uma lista exaustiva. Se for necessário proibir campos desconhecidos, é preciso adicionar explicitamente "additionalProperties": false — sem essa flag, o schema permanece "aberto".