JSON Schema

JSON Schema é uma forma padronizada de descrever como é um documento JSON válido: quais propriedades existem, seus tipos, quais são obrigatórias, os valores permitidos e os formatos. Um validador então compara os dados reais com o schema e informa cada violação. Para quem testa APIs, ele transforma “a resposta parece certa” em uma única verificação repetível de todo o formato da resposta. A versão atual da especificação é a draft 2020-12; a draft-07 ainda é muito usada.

Exemplo

Um schema para o usuário retornado por GET /users/{id}:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email", "role", "createdAt"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "role": { "enum": ["admin", "member", "viewer"] },
    "createdAt": { "type": "string", "format": "date-time" },
    "nickname": { "type": ["string", "null"] }
  },
  "additionalProperties": false
}

Validando no Node com Ajv (ajv/dist/2020 suporta a draft 2020-12, e ajv-formats acrescenta email e date-time):

import Ajv2020 from 'ajv/dist/2020';
import addFormats from 'ajv-formats';

const ajv = new Ajv2020({ allErrors: true });
addFormats(ajv);
const validate = ajv.compile(userSchema);

if (!validate(responseBody)) {
  console.log(validate.errors);
}

Em Java, o módulo json-schema-validator do REST Assured oferece matchesJsonSchemaInClasspath("schemas/user.json") para usar dentro de .body(...). Confira qual draft o seu validador suporta antes de usar palavras-chave mais novas.

Por que isso importa

• Uma asserção cobre o formato inteiro. Campos ausentes, tipos errados e nulls inesperados são detectados sem escrever uma verificação por campo.
• Pega vazamentos. "additionalProperties": false falha se a resposta de repente incluir algo como passwordHash.
• Documenta o contrato. As especificações OpenAPI usam JSON Schema para descrever os corpos de requisição e resposta.

Erros comuns

• Schemas que aceitam qualquer coisa. Um schema sem required passa com {}. Liste sempre os campos obrigatórios.
• Supor que o format é validado. Muitos validadores tratam format como uma anotação, a menos que a validação de formato seja ativada.
• Validar só o schema. Uma resposta pode bater com o schema e mesmo assim trazer o usuário errado. Mantenha asserções de valor para os dados que importam.