Validador de JSON contra Schema

JSON Schema: um vocabulario para validar documentos JSON

JSON Schema e uma especificacao do IETF que permite descrever a estrutura, os tipos e as restricoes de qualquer documento JSON usando JSON. Surgiu como rascunho da comunidade por volta de 2010 e hoje e a linguagem de contrato de fato para APIs REST, arquivos de configuracao, filas de mensagens e sistemas de plug-in SaaS. A referencia canonica esta em json-schema.org.

Um schema e um objeto JSON cujas palavras-chave descrevem como um documento valido deve ser: quais chaves sao obrigatorias, que tipos cada valor aceita, se strings combinam com regex, se numeros caem em um intervalo etc. Um validador percorre schema e documento em paralelo, devolvendo um veredito e uma lista de violacoes com caminhos JSON Pointer.

Drafts da especificacao: do Draft 4 ao 2020-12

O JSON Schema teve varias revisoes, cada uma com pequenas incompatibilidades. Saber a qual draft um schema pertence e essencial:

• Draft 4 (legado, 2013) — ainda comum em toolchains antigas de Swagger 2.0 / OpenAPI 2; usa id e "required": ["x"] na raiz.
• Draft 6 (2017) — introduziu const, examples e renomeou id para $id.
• Draft 7 (2018) — adicionou if/then/else, readOnly/writeOnly e contentEncoding. Ponto de maior maturidade de ferramentas.
• Draft 2019-09 — dividiu o spec em vocabularios, substituiu definitions por $defs e adicionou unevaluatedProperties.
• Draft 2020-12 (atual) — usado pelo OpenAPI 3.1; reformulou a resolucao de $ref e a validacao de tuplas via prefixItems.

Declare sempre o dialeto com $schema para que o validador aplique as regras certas:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["name"]
}

Keywords essenciais que todo autor deve conhecer

O vocabulario e extenso, mas um subconjunto cobre quase tudo no dia a dia:

• type — restringe a string, number, integer, boolean, array, object ou null.
• properties + required — formato do objeto e chaves obrigatorias.
• minLength, maxLength, pattern — restricoes de string; pattern aceita regex ECMA-262.
• minimum, maximum, exclusiveMinimum, multipleOf — intervalos numericos.
• enum e const — conjuntos fechados de valores permitidos.
• oneOf, anyOf, allOf, not — combinadores logicos.
• format — pistas semanticas (email, uri, uuid, date-time); opcional no 2020-12 a menos que o vocabulario de format-assertion seja ativado.
• $ref + $defs — reuso de subschemas (evita copia e cola).

Bibliotecas e desempenho em tempo de execucao

Existem implementacoes em todas as linguagens populares:

• AJV (Node, TypeScript) — o validador mais popular. Compila o schema uma vez para uma funcao JavaScript especializada, atingindo cerca de 1 milhao de validacoes por segundo.
• jsonschema e fastjsonschema (Python) — o primeiro interpreta; o segundo emite codigo Python e roda ate 10x mais rapido.
• Everit JSON Schema e NetworkNT (Java) — prontos para producao em stacks JVM.
• jsonschema (Rust) e boon — alta performance via binarios nativos.

Em hot paths, validadores JIT como o AJV superam if/else feito a mao porque se especializam para o schema exato e dispensam dispatch dinamico.

Casos de uso alem de contratos de API

• Validacao de request e response — OpenAPI 3.1 embute JSON Schema 2020-12 em cada payload.
• Arquivos de configuracao — Kubernetes CRDs, GitHub Actions workflows e VS Code settings tem schemas para autocompletar e alertar no editor.
• Geracao de formularios — react-jsonschema-form monta forms diretamente do schema.
• Validacao em banco — MongoDB (via JSON Schema validator) e Mongoose impoem o formato nas escritas.
• Geracao de tipos — json-schema-to-typescript emite interfaces TS; quicktype exporta para dezenas de linguagens.

JSON Schema vs Zod, Yup e TypeScript

Zod, Yup, io-ts e Valibot sao validadores TypeScript-first em tempo de execucao, com APIs encadeadas e binding direto aos tipos do TS. JSON Schema, ao contrario, e agnostico de linguagem e serializavel: o mesmo schema valida payloads em Node, Python, Go e Rust e trafega pela rede ate o cliente. Tipos TypeScript existem so em tempo de compilacao e desaparecem em runtime, entao nao protegem entradas nao confiaveis. Muitas equipes combinam os dois: definem em JSON Schema e derivam tipos TS com json-schema-to-typescript.

Armadilhas e boas praticas

• Defina additionalProperties: false quando os payloads precisarem ser estritos — o default aceita chaves extras silenciosamente.
• Prefira $defs + $ref a duplicacao; reuse shapes de usuario, endereco e dinheiro entre endpoints.
• Use examples com generosidade — eles alimentam o Swagger UI e os fixtures de contract testing.
• Fixe o draft com $schema para evitar drift quando o AJV for atualizado.
• Trate o caminho do erro como contrato com clientes (/users/0/email).

FAQ

Qual validador e o melhor para Node?

AJV e a escolha de fato — alta performance, suporte a multiplos drafts, tipos TypeScript e ecossistema robusto (Fastify, ESLint e NestJS dependem dele).

Qual a diferenca para tipos TypeScript?

TypeScript checa em tempo de compilacao e os tipos somem em runtime. JSON Schema atua em runtime e e a ferramenta certa para validar entradas nao confiaveis (HTTP, configs, mensagens de fila).

Posso reutilizar subschemas entre arquivos?

Sim. Defina em $defs e referencie com $ref, local (#/$defs/User) ou remoto (https://api.example.com/schemas/user.json). O AJV pre-carrega schemas remotos via addSchema().

OpenAPI 3.1 usa JSON Schema?

Sim — OpenAPI 3.1 esta totalmente alinhado com JSON Schema Draft 2020-12. O OpenAPI 3.0 anterior usava um subset que divergia em detalhes irritantes (nullable, formats de integer).

Por que meu schema nao rejeita campos extras?

Porque additionalProperties e true por padrao. Defina como false (ou como um schema) em cada objeto que voce quer selar.