JSON Schema para contratos de API confiáveis
Um processo de criação de esquemas que transforma dados válidos e inválidos em documentação executável em vez de depender de um único exemplo ideal.
A sintaxe JSON apenas prova que o documento pode ser analisado. Um contrato de API útil deve definir as estruturas e os valores com os quais seus consumidores podem contar com segurança.
Modele explicitamente ausência e valores nulos
Um campo obrigatório, um opcional e um que aceita null representam estados diferentes. Defina tipos, itens de matrizes, enumerações, formatos, limites e additionalProperties conforme as regras reais de compatibilidade.
Teste as falhas além dos casos válidos
Mantenha exemplos com campos ausentes, tipos incorretos, valores nulos, enumerações desconhecidas, propriedades extras, matrizes vazias e todos os ramos oneOf ou anyOf.
Gerencie a evolução do contrato
Compare os esquemas e os dados reais durante cada lançamento, diferencie ampliações compatíveis de mudanças incompatíveis e trate os tipos de cliente gerados apenas como um ponto de partida que precisa de revisão.
Checklist de revisão do esquema de API
- Defina campos obrigatórios opcionais e anuláveis
- Restrinja deliberadamente matrizes enumerações e formatos
- Adicione exemplos inválidos representativos
- Revise as sobreposições de oneOf e anyOf
- Teste mudanças do esquema com dados reais
Guias relacionados
Entenda o workflow por trás desta ferramenta e o que revisar depois.
Como depurar uma resposta JSON de API passo a passo
Um processo repetível para separar erros de transporte, problemas de sintaxe JSON e falhas do contrato de dados nas respostas de uma API.
Como depurar payloads JSON de API
Um workflow prático para formatar JSON, encontrar erros de sintaxe, validar o formato do payload e revisar o status quando dados de API parecem errados.