Validação JSON e Boas Práticas de Design de Schema

Por que a Validação JSON é Importante

As APIs são a espinha dorsal das aplicações modernas, e o JSON é sua língua franca. Mas sem validação adequada, JSON malformado ou malicioso pode derrubar seu serviço, corromper seu banco de dados ou abrir brechas de segurança. Já vi indisponibilidades em produção causadas por um único campo ausente ou um tipo inesperado. A validação JSON não é apenas sobre capturar erros de digitação—é sobre aplicar contratos, melhorar mensagens de erro e proteger seu sistema.

Neste artigo, abordaremos boas práticas práticas para projetar schemas JSON e validar payloads. Seja você construindo uma API REST, um resolver GraphQL ou um microsserviço, esses princípios ajudarão você a dormir melhor à noite.

1. Comece com um Schema Claro

Um schema é o contrato da sua API. Ele define quais campos são permitidos, seus tipos e quaisquer restrições. Sem ele, você está voando às cegas. Use JSON Schema (um vocabulário padronizado) para descrever seus dados. É agnóstico de linguagem e amplamente suportado.

Aqui está um exemplo mínimo para um objeto de usuário:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "name": { "type": "string", "minLength": 1 },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "name", "email"],
  "additionalProperties": false
}

Pontos-chave: required garante campos obrigatórios; additionalProperties: false rejeita campos desconhecidos (útil para APIs estritas).

2. Valide Cedo e Frequentemente

Valide na borda—antes que sua lógica de negócios seja executada. Isso evita que dados inválidos se propaguem. No Node.js, você pode usar bibliotecas como Ajv; no Python, jsonschema; no Go, gojsonschema. Sempre valide requisições recebidas e respostas enviadas (para capturar bugs).

Exemplo em Python:

from jsonschema import validate, ValidationError

try:
    validate(instance=request.json, schema=user_schema)
except ValidationError as e:
    return {"error": e.message}, 400

Retorne mensagens de erro claras—elas ajudam os clientes a corrigir problemas rapidamente.

3. Projete para Evolução

As APIs mudam. Seu schema deve acomodar adições sem quebrar clientes. Siga estas regras:

• Nunca remova ou renomeie campos sem um incremento de versão.
• Torne novos campos opcionais a menos que sejam críticos.
• Use versionamento na sua URL (ex.: /v1/users) ou media type.
• Prefira mudanças aditivas—adicione campos em vez de modificar os existentes.

Essa abordagem está alinhada com a lei de Postel: seja conservador no que você envia, liberal no que você aceita. Mas não seja liberal demais—validação estrita captura bugs cedo.

4. Lide com Tipos com Cuidado

JSON tem tipos limitados: string, number, boolean, object, array, null. Fique atento a:

• Números: JSON não distingue inteiros de floats. Use type: integer se precisar de números inteiros.
• Datas: Use strings ISO 8601 (ex.: 2026-01-15T10:00:00Z) e valide com format: date-time.
• Enums: Restrinja valores a um conjunto conhecido para evitar estados inválidos.
• Null vs. ausente: Decida se null é permitido. Muitas vezes, omitir um campo é melhor do que enviar null.

5. Proteja Sua Validação

A validação é um controle de segurança. Atacantes podem enviar payloads superdimensionados, objetos profundamente aninhados ou tipos inesperados para causar negação de serviço. Mitigue com:

• Limites de tamanho: Rejeite payloads acima de um certo tamanho (ex.: 1MB).
• Limites de profundidade: Previne JSON profundamente aninhado (ex.: profundidade máxima 10).
• Schemas estritos: Não permita propriedades adicionais para evitar injeção de campos inesperados.
• Sanitize strings: Mesmo após a validação, escape a saída para prevenir XSS.

Além disso, valide no servidor—nunca confie apenas na validação do lado do cliente.

6. Use uma Tabela Comparativa para Bibliotecas de Validação

Escolher a biblioteca certa depende da sua linguagem e necessidades de desempenho. Aqui está uma comparação rápida:

Todas essas bibliotecas implementam JSON Schema, então seus schemas são portáveis.

7. Documente Seu Schema

Um schema só é útil se os desenvolvedores o entenderem. Gere documentação de API a partir do seu schema usando ferramentas como OpenAPI (antigo Swagger) ou a palavra-chave description do JSON Schema. Inclua exemplos para cada campo.

Para inspeção rápida, você pode formatar e validar JSON manualmente usando um formatador JSON. Ele ajuda a identificar erros de sintaxe e problemas de estrutura antes de você mergulhar na validação de schema.

8. Teste Seus Schemas

Schemas são código—teste-os. Escreva testes unitários com payloads válidos e inválidos para garantir que suas regras de validação funcionem conforme o esperado. Ferramentas como json-schema-test-suite podem ajudar. Além disso, considere testes de contrato entre serviços para capturar incompatibilidades cedo.

FAQ

O que é JSON Schema e por que devo usá-lo?

JSON Schema é um padrão para descrever a estrutura de dados JSON. Ele permite definir tipos, campos obrigatórios e restrições, possibilitando validação e documentação automáticas. É amplamente suportado entre linguagens.

Como lidar com propriedades adicionais na validação JSON?

Por padrão, JSON Schema permite propriedades adicionais. Defina additionalProperties: false para rejeitar campos desconhecidos, o que melhora a segurança e captura erros de digitação. No entanto, seja cauteloso com a evolução da API—schemas estritos podem quebrar clientes que enviam campos extras.

Posso usar JSON Schema para validação de requisição e resposta?

Com certeza. Valide tanto requisições recebidas quanto respostas enviadas para garantir a integridade dos dados. A validação de resposta captura bugs no seu próprio código antes que cheguem aos clientes.

Conclusão

Validação JSON e design de schema são fundamentais para APIs robustas. Ao definir schemas claros, validar cedo, planejar a evolução e proteger seus endpoints, você constrói sistemas confiáveis e de fácil manutenção. Comece com um schema, escolha uma biblioteca de validação e teste minuciosamente. Seu eu do futuro (e seus usuários) agradecerão.