O que o JSON Schema realmente resolve
Resumo: O Schema governa estrutura e tipos, não significado de negócio. Ele detém campos ausentes, tipos errados e enums fora da faixa, enquanto regras como valor acima de zero ficam no código.
Resumo da ópera: deixe o JSON Schema impor estrutura, tipos, faixas e formatos, enquanto regras entre campos, invariantes de negócio e estado externo ficam no código; adote-o para APIs públicas e payloads compartilhados, não para um serviço interno de cinco campos.
Ele responde "estes dados têm a forma correta", não "estes dados fazem sentido".
O que ele faz bem
Completude estrutural. Quais campos precisam existir, se extras são permitidos (required, additionalProperties).
Tipos. port como número ou string, tags como array ou escalar. Só isso remove muito código defensivo em sistemas multilinguagem.
Faixas. enum, minimum/maximum, comprimento de string e de array.
Formatos. format para datas, e-mail, URIs e UUIDs, com validadores que os impõem.
Aninhamento. Cada nível de objetos e arrays ganha suas próprias restrições, e os erros carregam um caminho preciso.
Documentação. O Schema é o contrato. Mude um campo e o diff mostra o raio de impacto. Ele também gera tipos e formulários, então uma definição alimenta vários consumidores.
O que ele não consegue fazer
Dependências entre campos. "O fim deve ser depois do início" pode ser expresso com if/then/else, mas o resultado é mais longo e mais difícil de ler do que três linhas de código.
Invariantes de negócio. "O estoque não pode ficar negativo" depende de estado externo. O Schema vê um documento.
Semântica. price: -100 satisfaz perfeitamente {"type": "number"}. Se é um preço legal está fora do conhecimento do Schema.
Uma divisão viável
| Camada | Responsável |
|---|---|
| Sintaxe: é JSON válido | Analisador |
| Estrutura: campos, tipos, faixas, formatos | JSON Schema |
| Semântica: entre campos, regras de negócio, estado externo | Código da aplicação |
| Segurança: tamanho, profundidade, taxa | Gateway / middleware |
Colapse tudo em um lugar e o Schema cresce para centenas de linhas com cinco níveis de if/then. Nesse ponto as pessoas começam a contorná-lo.
Quando compensa
- APIs públicas com consumidores desconhecidos
- Múltiplos serviços lendo o mesmo payload
- Sistemas guiados por configuração onde erros de digitação precisam falhar rápido
- Geração de tipos ou formulários a partir do contrato
Para um serviço interno pequeno com cinco campos e um frontend, verificações escritas à mão são mais rápidas de manter. Introduzir Schema ali é trabalho negativo.
Perguntas frequentes
Como decido se devo adotar JSON Schema?
Pese consumidores públicos, múltiplos serviços lendo o mesmo payload e a necessidade de gerar tipos ou formulários. Para um serviço interno pequeno com cinco campos e um frontend, verificações escritas à mão são mais rápidas de manter.
Por que regras entre campos devem ficar no código?
"O fim deve ser depois do início" pode ser espremido em if/then/else, mas o resultado é mais longo e mais difícil de ler do que algumas linhas de código. O Schema também não enxerga estado externo.
O Schema deve validar tamanho do payload e profundidade de aninhamento?
Não. O Schema descreve estrutura, não tamanho nem profundidade; esses limites pertencem a uma camada de gateway ou middleware.