Versionamento e validação de schema

JSON Schema tem versões de draft. Um draft define quais palavras-chave existem e como validadores devem interpretá-las. Schemas modernos costumam usar Draft 2020-12, enquanto ecossistemas mais antigos ainda podem exigir Draft 7.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

O campo $schema informa às ferramentas qual dialeto usar. Escolha um draft aceito por seus validadores, editores e ferramentas de API.

Erros de validação fazem parte do contrato

Um schema útil falha com erros que apontam para o problema:

• Propriedade obrigatória ausente
• Tipo errado
• Valor abaixo do mínimo
• String que não corresponde a um formato
• Propriedade extra rejeitada pela política

Ao revisar um schema, teste exemplos válidos e inválidos. Fixtures inválidas costumam ser mais valiosas porque provam que o validador detecta os erros importantes.

Regras de compatibilidade

Alterar um schema pode quebrar clientes. Trate evolução de schema como evolução de API:

• Adicionar propriedade opcional costuma ser seguro.
• Adicionar propriedade obrigatória pode quebrar produtores existentes.
• Restringir um enum pode quebrar dados armazenados e clientes.
• Alterar um tipo geralmente é mudança incompatível.
• Remover um campo pode quebrar consumidores.

Escolha de draft na prática

Draft 2020-12 é um bom padrão para novos fluxos locais. Draft 7 continua útil quando ferramentas antigas exigem. O melhor draft é o mais novo que seu validador de produção realmente suporta.

Schemas são contratos vivos. Mantenha-os perto de exemplos, testes e notas de release para que o contrato de dados evolua junto com o sistema.