Validação de Esquema JSON Capturando violações do contrato de API antes de entregar

Se seu API retornar um campo que o esquema diz que não existe, ou aceitar um corpo de requisição com uma propriedade obrigatória ausente, você tem uma violação de contrato. Esses erros são sutis, muitas vezes silenciosos e notoriamente difíceis de encontrar em produção. A validação de esquema JSON é a camada que os captura mais cedo — mais perto do ponto em que são introduzidos.

Este guia aborda como funciona o esquema JSON, quais validadores usar em Node.js, Python e AWS, e como manter seu esquema longe da realidade.

O que é um Esquema JSON

O JSON Schema é um vocabulário para descrever a estrutura de um documento JSON. Não é código — é metadados. Você escreve um esquema que declara como um objeto JSON válido deve se parecer, depois o executa em um validador.

O esquema em si é um documento JSON. Um exemplo mínimo:

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "type": "object",
  "properties": {
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0 }
  },
  "required": ["email"]
}

Isso é tudo. Foque isso em um validador com qualquer payload JSON, e você obterá um resultado de passo ou uma lista estruturada de falhas.

Palavras-chave principais

Um conjunto pequeno de palavras-chave cobre a maioria das necessidades de validação no mundo real:

additionalProperties: false merece menção especial. É a palavra-chave que torna seu esquema rigoroso — qualquer propriedade não declarada no properties acusa um erro de validação. Ela está desativada por padrão, o que significa que a maioria dos esquemas aceita silenciosamente campos inválidos a menos que você opte por ativar.

Um Esquema Completo: Requisição de Registro de Usuário

Aqui está um esquema JSON completo para o corpo de requisição de um ponto de entrada de registro. É o tipo de esquema que você escreveria uma vez e validaria em todas as camadas que interagem com o ponto de entrada.

{
  "$schema": "https://json-schema.org/draft/2020-12",
  "title": "UserRegistration",
  "type": "object",
  "required": ["email", "password", "username"],
  "additionalProperties": false,
  "properties": {
    "email": {
      "type": "string",
      "format": "email"
    },
    "password": {
      "type": "string",
      "minLength": 8
    },
    "username": {
      "type": "string",
      "pattern": "^[a-zA-Z0-9_]{3,32}$"
    },
    "role": {
      "type": "string",
      "enum": ["user", "admin"],
      "default": "user"
    },
    "birthDate": {
      "type": "string",
      "format": "date"
    }
  }
}

Você pode testar isso interativamente contra qualquer payload usando o IO Tools JSON Schema Validator antes de integrá-lo ao seu código.

Validação de Corpos de Requisição de API

Express + AJV

AJV é o validador mais rápido de esquema JSON para Node.js. Aqui está um middleware do Express que valida o corpo do requisição antes que chegue ao seu manipulador:

import Ajv from "ajv";
import addFormats from "ajv-formats";

const ajv = new Ajv({ allErrors: true });
addFormats(ajv);

function validateBody(schema) {
  const validate = ajv.compile(schema);
  return (req, res, next) => {
    if (validate(req.body)) {
      return next();
    }
    res.status(400).json({
      error: "Validation failed",
      details: validate.errors,
    });
  };
}

// Usage
app.post("/register", validateBody(registrationSchema), registerHandler);

allErrors: true diz ao AJV para coletar todos os erros no documento, em vez de parar no primeiro — útil quando você deseja retornar todas as falhas de validação para o cliente de uma só vez.

Nginx

No Python, o FastAPI usa Pydantic por trás e gera um esquema JSON a partir das anotações de tipo automaticamente. Se você estiver trabalhando com um esquema JSON bruto vindo de uma fonte externa, em vez de modelos Pydantic, jsonschema é a biblioteca padrão:

from jsonschema import validate, ValidationError

schema = { ... }  # your schema dict

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

AWS API Gateway

O API Gateway suporta a validação do corpo de requisição nativamente. Você define um modelo (que é um documento de esquema JSON) e o anexa ao seu método como um REQUEST_BODY validador. Requisições que falham na validação são rejeitadas no nível do gateway — antes que a sua função Lambda nunca execute. Isso elimina uma classe inteira de erros de manipulador e reduz as chamadas de inicialização frias para tráfego inválido.

Esquemas Reutilizáveis com $ref e $defs

Quando múltiplos esquemas compartilham uma estrutura comum — como um endereço, um valor monetário ou um objeto de paginação — defina isso uma vez no $defs e faça referência a ele com $ref:

{
  "$defs": {
    "Address": {
      "type": "object",
      "required": ["street", "city", "country"],
      "properties": {
        "street": { "type": "string" },
        "city":   { "type": "string" },
        "country": { "type": "string", "pattern": "^[A-Z]{2}$" }
      }
    }
  },
  "type": "object",
  "properties": {
    "billingAddress":  { "$ref": "#/$defs/Address" },
    "shippingAddress": { "$ref": "#/$defs/Address" }
  }
}

Para projetos maiores, os esquemas vivem em arquivos separados e $ref ponta para um URI. Validadores que suportam a palavra-chave e a resolução de URI podem carregar os esquemas de forma lenta ou de um registro — o AJV trata isso através de $id Drift de Esquema addSchema().

O drift de esquema acontece quando o esquema e a API real divergem. É mais comum do que parece: o esquema é escrito uma vez, a API evolui e ninguém atualiza o esquema.

Os sintomas são sutis. Um campo é renomeado no código, mas não no esquema — a validação ainda passa porque

não está definida como falsa. Um campo obrigatório se torna opcional na prática porque o código não o verifica — o esquema ainda diz que é obrigatório, mas ninguém percebe até que um cliente envie uma requisição sem ele. additionalProperties Detectar o drift exige tratar a validação de esquema como um teste, e não como uma verificação em tempo de execução. Alguns times automatizam isso com testes de snapshot contra fixtures de resposta real. Outros executam o validador de esquema no CI contra um conjunto de requisições capturadas. O ponto é que o esquema deve ser exercitado regularmente, e não apenas implantado uma vez.

JSON Schema e OpenAPI

O OpenAPI (anteriormente Swagger) usa o JSON Schema para descrever corpos de requisição e resposta, mas com algumas modificações. As versões anteriores (OpenAPI 2.0, 3.0) usavam um subconjunto do JSON Schema com extensões. O OpenAPI 3.1 alinha-se mais com o JSON Schema draft 2020-12, então os esquemas são basicamente intercambiáveis.

A diferença prática: o OpenAPI envolve os esquemas em um documento maior que também descreve rotas, operações, autenticação e servidores. O JSON Schema sozinho é apenas um contrato de validação. Se você estiver construindo uma API com foco em esquemas, pode escrever o JSON Schema para cada ponto de entrada, validá-lo e depois transferir esses esquemas diretamente para um documento OpenAPI.

Geração de Esquemas a partir de Dados Existentes

Escrever esquemas à mão funciona bem para novas APIs. Para APIs existentes com comportamento não documentado, muitas vezes é mais rápido gerar um esquema a partir de payloads reais e depois ajustá-lo.

(Python) e

Ferramentas como genson (Node.js) pegam objetos JSON de exemplo e geram um esquema inicial. O esquema gerado é quase sempre excessivamente permissivo — tudo se torna opcional, sem generate-schema — mas fornece um ponto de partida. Em seguida, você adiciona additionalProperties: false , ajusta requireddefinições e adiciona type restrições onde os valores são limitados. enum Este método também ajuda ao integrar uma API de terceiro sem documentação de esquema. Execute várias respostas por meio de um gerador de esquema, combine o resultado e terá um contrato funcional para validar.

A validação de esquema JSON deve estar presente em todas as camadas que recebem dados estruturados — middleware HTTP, consumidores de fila de mensagens, caminhos de escrita no banco de dados. Quanto mais cedo um erro de contrato for detectado, mais barato será corrigir. Um

validador de esquema JSON online te permite prototipar esquemas contra payloads reais antes de se comprometer com a integração de uma biblioteca, o que o torna o passo certo inicial para qualquer trabalho de validação. Validação de Esquema JSON: Capturando Violações de Contrato de API Antes de Elas Serem Enviadas 2

Você também pode gostar

Geração de Paleta de Cores: Criando uma Paleta Completa a partir de um Único Hex

Ler mais »

Publicado em 12 de maio de 2026

Verificação de Assinatura PDF: O que os Desenvolvedores Precisam Saber

Ler mais »

Publicado em 10 de maio de 2026

Markdown vs HTML: Quando Usar Cada Um para Documentos, READMEs e APIs

Ler mais »

Publicado em 9 de maio de 2026

Parâmetros UTM: Como rastrear campanhas de marketing sem adivinhar

Ler mais »

Publicado em 7 de maio de 2026