JSON Schema para validação prática de API

JSON Schema é mais útil quando descreve a forma em que sua API realmente depende. Não precisa modelar toda regra de negócio para valer a pena.

Até um schema pequeno pode pegar campos ausentes, tipos errados, valores de enum inesperados e deriva acidental de contrato entre equipes.

Este artigo faz parte do cluster ferramentas locais para depuração de API. Quando a saída de conversão precisa de checagem de contrato, combine com converter cURL com segurança.

Comece pela fronteira do contrato

Um bom schema mira uma fronteira:

• Corpo de requisição aceito por um endpoint.
• Corpo de resposta retornado por um serviço.
• Payload de webhook enviado a parceiros.
• Arquivo de config lido na inicialização.
• Mensagem de evento publicada em uma fila.

A fronteira importa porque define quem deve manter o contrato estável.

Valide a estrutura primeiro

Comece pelos campos que quebram consumidores quando mudam:

• Propriedades obrigatórias.
• Tipos primitivos.
• Arrays vs objetos.
• Valores de enum.
• Campos anuláveis.
• Formatos de string de data ou identificador.

Você pode refinar depois. A primeira versão deve deixar erros comuns óbvios.

Mantenha exemplos ao lado dos schemas

Schemas são mais confiáveis com exemplos pareados. Guarde pelo menos um exemplo válido e um inválido de propósito.

Na depuração, cole o payload no Formatador JSON, valide contra o schema e compare o caminho do erro com o código da API ou a documentação. Para um schema inicial a partir de JSON de exemplo, use o Gerador de JSON Schema e refine os campos.

Não coloque toda regra no JSON Schema

Algumas regras pertencem a outro lugar:

• Checagens de permissão.
• Existência no banco de dados.
• Regras entre campos que dependem do estado atual.
• Rate limits e cotas.
• Fluxos de negócio.

JSON Schema é excelente para a forma do payload. Não substitui lógica de aplicação.

Sinais de deriva de schema

Fique atento a estes sinais:

• O frontend começa a checar typeof em todo lugar.
• Clientes de API aceitam nomes de campo antigos e novos.
• Webhooks falham só para um parceiro.
• Fixtures de teste não batem mais com payloads de produção.
• Exemplos na documentação diferem das respostas reais.

São bons momentos para adicionar ou atualizar um schema.

Regra prática

Se alguém abre um payload repetidamente só para ver se um campo existe e tem o tipo certo, essa checagem provavelmente pertence a um schema.

Veja também o fluxo de depuração de API.