Validador de JSON Schema

O que é validação de JSON Schema?

Validação de JSON Schema é o processo de verificar se um documento JSON está em conformidade com um conjunto de restrições estruturais e de valor definidas em um JSON Schema. O próprio schema é um documento JSON que descreve a forma esperada dos seus dados: quais propriedades são obrigatórias, quais tipos devem ter, os intervalos permitidos para números, padrões de strings, tamanhos de arrays e muito mais. A especificação JSON Schema é mantida em json-schema.org e publicada como uma série de rascunhos IETF; Draft 7 e Draft 2020-12 são os mais amplamente adotados.

Enquanto a validação JSON simples verifica apenas sintaxe (os colchetes estão pareados? as strings estão entre aspas?), a validação por schema vai além. Ela responde perguntas como: a resposta desta API contém um campo "id" que é sempre um inteiro? O campo "status" é um dos três valores permitidos? Os objetos aninhados têm a forma correta? Esse tipo de verificação estrutural captura bugs que a verificação de sintaxe ignora completamente, pois um JSON sintaticamente válido pode ainda ser semanticamente incorreto para sua aplicação.

JSON Schema é usado em definições OpenAPI/Swagger, validação de arquivos de configuração, validação de formulários, restrições de documentos em bancos de dados e testes automatizados. Ferramentas como Ajv (JavaScript), jsonschema (Python) e check-jsonschema (CLI) implementam a especificação para que você possa validar dados programaticamente. Este validador online permite colar um schema e um documento de dados para verificar a conformidade instantaneamente, sem instalar nenhuma biblioteca.

Por que usar um validador de JSON Schema online?

Escrever schemas e depurar erros de validação manualmente é lento. Um validador de JSON Schema online fornece feedback imediato sobre se seus dados estão em conformidade com o schema, com mensagens de erro claras apontando exatamente a propriedade que falhou.

Casos de uso para validação de JSON Schema

Referência de palavras-chave do JSON Schema

Um JSON Schema é construído a partir de palavras-chave que impõem restrições aos dados validados. A tabela abaixo lista as palavras-chave mais usadas no Draft 7 e versões posteriores. Cada palavra-chave pode ser combinada com outras no mesmo objeto de schema.

Comparação de versões do JSON Schema: Draft 7 vs 2019-09 vs 2020-12

O JSON Schema passou por várias versões de rascunho. O Draft 7 (publicado em 2018) é o mais amplamente suportado pelas ferramentas. O Draft 2019-09 introduziu $defs (substituindo definitions), unevaluatedProperties e $recursiveRef. O Draft 2020-12 (a versão estável mais recente) substituiu $recursiveRef por $dynamicRef e introduziu prefixItems para validação de tuplas. Ao escolher um draft, verifique se sua biblioteca de validação o suporta. O Ajv suporta os três drafts. A biblioteca jsonschema do Python suporta até 2020-12 desde a versão 4.0.

Exemplos de código

Estes exemplos mostram como validar JSON contra um schema programaticamente. Cada um utiliza uma biblioteca bem mantida para seu ecossistema de linguagem.

import Ajv from 'ajv';

const ajv = new Ajv();

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string', minLength: 1 },
    age: { type: 'integer', minimum: 0 },
    email: { type: 'string', format: 'email' }
  },
  required: ['name', 'email'],
  additionalProperties: false
};

const data = { name: 'Alice', age: 30, email: 'alice@example.com' };

const validate = ajv.compile(schema);
const valid = validate(data);
console.log(valid);          // → true
console.log(validate.errors); // → null

// Invalid data — missing required "email"
validate({ name: 'Bob', age: 25 });
console.log(validate.errors);
// → [{ instancePath: '', keyword: 'required', params: { missingProperty: 'email' } }]

from jsonschema import validate, ValidationError

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "age": {"type": "integer", "minimum": 0},
        "tags": {
            "type": "array",
            "items": {"type": "string"},
            "uniqueItems": True
        }
    },
    "required": ["name"]
}

# Valid data
validate(instance={"name": "Alice", "age": 30, "tags": ["admin"]}, schema=schema)
# → No exception raised

# Invalid data — wrong type for "age"
try:
    validate(instance={"name": "Alice", "age": "thirty"}, schema=schema)
except ValidationError as e:
    print(e.message)
    # → 'thirty' is not of type 'integer'
    print(e.json_path)
    # → $.age

package main

import (
    "fmt"
    "strings"
    "github.com/santhosh-tekuri/jsonschema/v5"
)

func main() {
    schemaJSON := `{
        "type": "object",
        "properties": {
            "id": { "type": "integer" },
            "status": { "enum": ["active", "inactive"] }
        },
        "required": ["id", "status"]
    }`

    compiler := jsonschema.NewCompiler()
    compiler.AddResource("schema.json", strings.NewReader(schemaJSON))
    schema, _ := compiler.Compile("schema.json")

    // Valid data
    data := map[string]interface{}{"id": 1, "status": "active"}
    err := schema.Validate(data)
    fmt.Println(err) // → <nil>

    // Invalid — missing "status"
    bad := map[string]interface{}{"id": 2}
    err = schema.Validate(bad)
    fmt.Println(err) // → validation failed: missing properties: 'status'
}

# Install via pip
pip install check-jsonschema

# Validate a file against a schema
check-jsonschema --schemafile schema.json data.json
# → ok -- validation done

# Validate against a remote schema (e.g., GitHub Actions workflow)
check-jsonschema --builtin-schema vendor.github-workflows my-workflow.yml

# Validate multiple files at once
check-jsonschema --schemafile schema.json file1.json file2.json file3.json

Perguntas frequentes