Validador JSON Schema

O que é um Validador JSON Schema?

// A 5-line schema that catches three real bugs
const schema = {
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id":    { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "age":   { "type": "integer", "minimum": 0, "maximum": 150 }
  },
  "required": ["id", "email"],
  "additionalProperties": false
};

// Three bugs the schema catches:
const bad = { "id": "42", "age": 200 };
//   /id   → type: expected integer, got string
//   /email → required: missing
//   /age   → maximum: 200 > 150

// In Node:        new Ajv().compile(schema)(bad)  // false; ajv.errors has the paths
// In Python:      jsonschema.validate(bad, schema)
// In the browser: this tool — same errors, same paths, no install

Funcionalidades principais

Exemplos

{
  "id": 42,
  "email": "alice@example.com",
  "age": 30
}

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

{
  "id": "42",
  "age": 200
}

{
  "type": "object",
  "properties": {
    "id": { "type": "integer" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "maximum": 150 }
  },
  "required": ["id", "email"]
}

{
  "type": "order.created",
  "data": { "orderId": "ORD-001234", "totalUsd": 49.99 }
}

{
  "oneOf": [
    {
      "properties": {
        "type": { "const": "order.created" },
        "data": {
          "type": "object",
          "properties": {
            "orderId": { "type": "string", "pattern": "^ORD-[0-9]{6}$" },
            "totalUsd": { "type": "number", "minimum": 0 }
          },
          "required": ["orderId", "totalUsd"]
        }
      },
      "required": ["type", "data"]
    },
    {
      "properties": {
        "type": { "const": "order.refunded" },
        "data": { "type": "object", "required": ["refundId"] }
      },
      "required": ["type", "data"]
    }
  ]
}

[
  { "sku": "A1", "qty": 3 },
  { "sku": "B2", "qty": 5 },
  { "sku": "A1", "qty": 3 }
]

{
  "type": "array",
  "minItems": 1,
  "uniqueItems": true,
  "items": {
    "type": "object",
    "properties": {
      "sku": { "type": "string", "pattern": "^[A-Z][0-9]+$" },
      "qty": { "type": "integer", "minimum": 1 }
    },
    "required": ["sku", "qty"]
  }
}

Como usar

1. 1

   Cole o seu JSON Schema

   Coloque o seu esquema no painel direito. O validador deteta automaticamente o draft a partir do URI $schema se presente; caso contrário, escolha Draft 2020-12, 2019-09 ou Draft-07 na barra de ferramentas.

2. 2

   Cole os seus dados JSON

   Coloque o documento JSON que quer verificar no painel esquerdo. A validação corre enquanto escreve; inputs grandes (>200 KB) mudam para um botão Validate manual para manter a digitação fluida.

3. 3

   Leia a lista de erros

   Cada erro tem um caminho JSON Pointer, uma keyword e uma mensagem de uma linha. Clique num erro para saltar para a localização nos seus dados, corrija-o e veja o contador descer em tempo real.

Armadilhas comuns de JSON Schema

{ "qty": 1.0 }   schema: { "type": "integer" }   → error: not an integer

{ "qty": 1 }     schema: { "type": "integer" }   → valid

{ "properties": { "name": { "type": "string", "required": true } } }

{ "properties": { "name": { "type": "string" } }, "required": ["name"] }

{ "properties": { "id": { "type": "integer" } } }   accepts: { "id": 1, "foo": "bar", "x": null }

{ "properties": { "id": { "type": "integer" } }, "additionalProperties": false }

{ "type": "string", "nullable": true }   in 2020-12: nullable is just an unknown keyword

{ "type": ["string", "null"] }   in 2020-12: explicitly allows null

pattern: "[A-Z]+"   accepts: "helloX"   (because X matches)

pattern: "^[A-Z]+$"   accepts only: "HELLO"

oneOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → error: matches both

anyOf: [ { type: "string" }, { type: "string", maxLength: 10 } ]   on: "hi"   → valid

Casos de uso comuns

Validação de pedido de API

Cole um corpo de pedido e o esquema do seu endpoint antes do deploy. Apanhe respostas 400 que os seus testes não cobriram — campos required em falta, tipos errados, números fora do intervalo.

Verificação de payload de webhook

O fornecedor enviou um payload que o seu handler rejeita? Valide o payload real contra o seu esquema, depois contra o esquema publicado do fornecedor. A diferença entre os dois é o seu bug.

Linting de ficheiros de configuração

package.json, tsconfig.json, helm values.yaml — cada ficheiro de configuração tem um esquema público. Cole o esquema, cole a configuração, encontre o typo. Salte o tentativa-erro.

Teste de componentes OpenAPI

Extraia um componente de esquema de um documento OpenAPI 3.1, cole-o aqui, valide payloads de exemplo. Mais rápido do que levantar um mock server, determinístico, sem SDK.

Pré-voo de submissão de formulário

Cole um payload de formulário de exemplo antes de cablar a validação no frontend. Confirme que o esquema rejeita o que espera, aceita o que espera, e depois envie o mesmo esquema para cliente e servidor.

Verificação de contrato de pipeline de dados

O output ETL desviou-se? Cole uma linha de exemplo e o esquema a jusante. Identifique qual produtor mudou e quais chaves se partiram antes de o pipeline retentar 10.000 registos.

Detalhes técnicos

Conforme com Draft 2020-12

Implementa a especificação Draft 2020-12 publicada — keywords, sistema de tipos, vocabulário format. Verificado contra o output de Ajv 8.x e ajv-formats.

Caminhos de erro JSON Pointer

Os erros usam JSON Pointer RFC 6901 (/user/email/0). Cada falha de keyword aponta para uma única localização resolúvel nos dados — sem ambiguidade, sem pesquisa por string.

Resolução interna de $ref

Resolve ponteiros $ref dentro de um único documento (#/$defs/foo, #/properties/bar). Ciclos detetados e reportados. $ref HTTP externos desativados por privacidade.

Boas práticas

Defina sempre additionalProperties: false

Em contratos de input (corpos de pedido, ficheiros de configuração, mensagens de fila), chaves desconhecidas costumam ser bugs — typos, campos acidentais ou sondagem de atacante. Rejeite-as por defeito.

Use $defs para subesquemas reutilizáveis

Se inlinar a mesma forma duas vezes, vão divergir. Mova as definições partilhadas para $defs e referencie com $ref — uma única fonte de verdade, cada alteração aplica-se em todo o lado.

Valide antes da lógica de negócio

Corra a validação de esquema logo a seguir a JSON.parse, antes de tocar na estrutura analisada. Estreitamento de tipos, valores por defeito e persistência assumem que o contrato se mantém — garanta que se mantém.

Perguntas frequentes