ADR-0005 Validação de entradas

Contexto

Todas as apps validam dados nas suas fronteiras: payloads de pedidos à API (server routes, ADR-0036), submissões de formulários, variáveis de ambiente no arranque, parâmetros de URL e payloads de webhooks de terceiros. Os tipos do TypeScript são apagados em runtime — sem validação em runtime, o any que vem da rede flui diretamente para a lógica de negócio.

Requisitos:

• Validação em runtime com inferência estática de tipos — um só schema produz tanto o validador como o tipo TS
• Funciona nas nossas rotas de API — safeParse simples nos handlers das server routes
• Integra com o TanStack Form/Router no cliente — via Standard Schema, a especificação partilhada que todas as principais bibliotecas de validação implementam atualmente
• Uma só biblioteca em todo o lado — servidor e cliente partilham schemas; sem lógica de validação duplicada

Opções consideradas

1. Zod

A opção dominante. Schema-first, excelente inferência de tipos, ecossistema enorme. A v4 trouxe um núcleo reescrito com grandes ganhos de desempenho e suporte oficial ao Standard Schema.

Prós

• O maior ecossistema e notoriedade — todas as ferramentas têm primeiro um adaptador para Zod
• Integração oficial com o Hono: @hono/zod-validator
• Compatível com Standard Schema → liga-se diretamente ao TanStack Form/Router
• Fonte única de verdade: schema → tipo TS inferido → validador Hono → validador de formulários
• O @hono/zod-openapi transforma schemas em specs OpenAPI
• A reescrita do núcleo do Zod 4 fecha a lacuna histórica de desempenho

Contras

• O maior bundle no cliente dos candidatos (atenuado pelo tree-shaking da v4)
• A superfície da API é ampla; a equipa deve cingir-se a um subconjunto comum

2. Valibot

Alternativa modular e com tree-shaking, com uma API quase idêntica.

Prós

• Os bundles mais pequenos; imports modulares
• Compatível com Standard Schema

Contras

• Ecossistema mais pequeno; existem adaptadores, mas chegam mais tarde do que os do Zod
• Menos cobertura no Stack Overflow, menos programadores da bolsa de recrutamento o conhecem

3. ArkType

Sintaxe de tipos como validação, extremamente rápido.

Prós

• A validação mais rápida das três
• Elegante: validadores escritos na própria sintaxe de tipos do TypeScript

Contras

• O mais recente; a curva de aprendizagem mais íngreme (uma nova DSL, por mais familiar que pareça)
• O mais pequeno ecossistema e comunidade

4. Yup / TypeBox / io-ts

O Yup é datado e mais fraco na inferência; o TypeBox é centrado em JSON Schema (ótimo para OpenAPI, DX mais desajeitada); o io-ts é muito centrado em FP. Todos viáveis, nenhum é uma predefinição melhor.

Decisão

O Zod é a biblioteca de validação padrão da empresa, usada em todas as fronteiras do sistema:

• Rotas de API — safeParse através de readJson e readQuery nos handlers das server routes (ADR-0036). (Alterado em 2026-11-13: este ADR nomeou inicialmente o @hono/zod-validator; o ADR-0036 substituiu o Hono pelas server routes do Start.)
• Server functions — o schema passado a .validator(); são endpoints que qualquer pessoa pode chamar, não apenas a nossa UI
• Variáveis de ambiente — processadas uma só vez no arranque; a app falha logo em caso de má configuração
• Formulários — schemas partilhados alimentam o TanStack Form através do Standard Schema
• Webhooks / payloads externos — validados à entrada, nunca assumidos como fiáveis

Os fatores decisivos: o maior ecossistema, adaptadores oficiais para tudo na nossa stack (TanStack, e o Hono onde um produto o adote), a conformidade com o Standard Schema que nos mantém portáveis, e um-schema-um-tipo como fonte única de verdade. Aceitamos o custo no tamanho do bundle, atenuado pelo tree-shaking do Zod 4 e por partilharmos schemas em vez de os duplicar.

Consequências

Mais fácil:

• Payloads de API, configuração de ambiente e formulários falam todos a mesma linguagem de schemas — menos mudanças de contexto
• Os schemas são partilhados entre cliente e servidor; o desvio entre a validação do lado do cliente e a do lado do servidor torna-se impossível
• A geração de OpenAPI, para um produto que publica uma API (ADR-0036), sai quase de borla dos mesmos schemas
• A validação do ambiente no arranque apanha erros de configuração operacional antes do primeiro pedido

Mais difícil:

• Os bundles do cliente carregam uma biblioteca de validação — aceitável, mas os schemas devem ser partilhados e sujeitos a tree-shaking, não colados em cada formulário
• É preciso disciplina para validar apenas nas fronteiras — sem revalidar dados internos já considerados fiáveis

Do que abdicamos: dos bundles mais pequenos do Valibot e da velocidade pura do ArkType. Aceite — o peso do ecossistema e a cobertura de integrações superam ambos à nossa escala.