O que é JSON Schema?

JSON Schema é um vocabulário para descrever a forma de dados JSON. Um schema pode dizer que um valor precisa ser um objeto, que esse objeto precisa ter um campo name, que tags deve ser um array de strings ou que um identificador deve seguir o formato UUID.

O objetivo não é apenas documentação. Um schema pode ser usado por validadores, editores, checagens de CI, gateways de API e fixtures de teste.

O que um schema descreve

No nível mais simples, um schema responde a três perguntas:

• Qual tipo JSON é permitido?
• Quais campos podem ou devem existir?
• Quais restrições se aplicam a cada valor?

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": { "type": "string", "format": "uuid" },
    "name": { "type": "string" }
  },
  "required": ["id", "name"]
}

Esse schema valida forma, não verdade de negócio. Ele pode exigir id, mas não pode provar que esse id existe no banco de dados sem uma consulta da aplicação.

Onde schemas ajudam

• Payloads de requisição e resposta
• Arquivos de configuração
• Filas e streams de eventos
• Fixtures de teste
• Dados gerados por scripts ou sistemas de IA

O que schemas não substituem

Schemas não substituem parse de JSON, validação de domínio, autorização ou restrições de banco. Eles ficam na fronteira onde JSON bruto vira um valor que seu programa está disposto a confiar.

Bons schemas são previsíveis: fazem dados inválidos falharem cedo, perto da borda do sistema, antes que virem uma história de depuração em produção.