Schema validation API: por que usar e como aplicar

Schema validation em APIs é a prática de verificar se os dados enviados e recebidos seguem um contrato predefinido, como tipos, campos obrigatórios e formatos. Ele evita que erros silenciosos cheguem ao servidor, reduz bugs de integração e documenta o comportamento esperado da API de forma executável.

O que é schema validation em uma API?

Um schema é uma descrição formal da estrutura de dados. No contexto de API, ele define quais campos são esperados em um request ou response, qual o tipo de cada um (string, inteiro, objeto), se são opcionais ou obrigatórios e se há regras de formato, como data ou e-mail. A validação compara os dados reais contra esse schema e retorna erro explícito quando há divergência.

Ferramentas como JSON Schema, OpenAPI e bibliotecas como Joi ou Zod implementam essa checagem. O ponto central é que a validação ocorre antes de qualquer lógica de negócio, criando uma barreira clara contra dados malformados.

Por que validar schema em vez de confiar no cliente?

Clientes podem enviar campos extras, valores nulos ou tipos inesperados. Um erro de digitação no front-end vira um campo nome em vez de name, e sem validação o servidor processa um dado vazio. O resultado é um bug difícil de rastrear, porque o banco aceita o valor nulo e a falha aparece dias depois.

Com schema validation, o erro é detectado no momento da requisição. A resposta já indica qual campo falhou e qual regra foi violada. Isso encurta o ciclo de depuração e evita que dados corrompidos persistam no sistema.

Quais problemas comuns a validação resolve?

Um caso frequente é o campo de data enviado em formato americano quando o servidor espera o brasileiro. Sem validação, a data é interpretada de forma incorreta ou gera exceção em runtime. Outro exemplo é um campo numérico que chega como string, causando comparações inesperadas. A validação tipa os dados na borda da API, antes de qualquer processamento.

Também previne ataques por injeção de campos inesperados. Um payload com propriedades extras pode sobrescrever parâmetros internos, dependendo do framework. Schemas que bloqueiam campos não declarados reduzem essa superfície de risco.

Como implementar schema validation na prática?

Primeiro, defina o contrato de cada endpoint. Para APIs REST, OpenAPI 3 descreve schemas de request e response em formato declarativo. Em seguida, use uma biblioteca que valide automaticamente no middleware, antes do handler. No Node.js, Zod permite criar schemas com TypeScript e obter inferência de tipos. Em Python, Pydantic faz checagem na definição do modelo.

O passo final é retornar erros padronizados. Use o formato RFC 7807 para problem details, incluindo status HTTP, título e lista de violações. Isso facilita o consumo por qualquer cliente.

Quando a validação de schema não é suficiente?

Validação de schema cobre estrutura, não semântica. Um CPF com 11 dígitos passa no schema, mas pode ser inválido. Regras de negócio, como estoque negativo ou usuário duplicado, exigem validação no domínio. O schema é a primeira camada, não a única.

FAQ

Schema validation e validação de negócio são a mesma coisa?

Não. Schema validation verifica forma dos dados, como tipos e campos obrigatórios. Validação de negócio confere regras específicas, como limites de valor ou permissões. Ambos são necessários, mas atuam em camadas diferentes da aplicação.

Qual a diferença entre JSON Schema e OpenAPI?

JSON Schema é uma especificação para descrever e validar estruturas JSON. OpenAPI usa JSON Schema para definir contratos de API REST, incluindo endpoints, parâmetros e respostas. OpenAPI é mais amplo, focado em documentação e geração de código.

Posso usar schema validation sem afetar a performance?

Sim, o custo é baixo se a validação ocorrer apenas na borda. Em linguagens interpretadas, bibliotecas como Joi e Zod são otimizadas. Para altíssimo throughput, é possível validar apenas em endpoints críticos ou usar validação em nível de schema compilado.

Quais erros devo retornar quando a validação falha?

Use status HTTP 400 Bad Request com corpo descritivo, listando campo e regra violada. Padrões como RFC 7807 ajudam na consistência entre endpoints. Evite retornar 500 para erros de validação, pois isso confunde logs e monitoramento.

Schema validation substitui testes de API?

Não. Testes de integração garantem que o fluxo completo funciona, incluindo autenticação e banco de dados. Schema validation é uma checagem estática de dados. Os dois se complementam, mas a validação não cobre lógica de aplicação.