Como Validar JSON Online: Sintaxe, Esquema e Erros Comuns

JSON (JavaScript Object Notation) tem uma especificação formal definida pela RFC 8259 e pelo padrão ECMA-404. Um documento JSON é válido quando se conforma completamente a essa especificação — nem mais, nem menos. As regras são mais rigorosas do que a maioria espera, e várias coisas que o JavaScript permite são explicitamente proibidas no JSON.

As regras da especificação JSON

• Strings devem usar aspas duplas - strings com aspas simples (`'value'`) não são JSON válido, mesmo que o JavaScript as aceite.
• Sem vírgulas finais - `[1, 2, 3,]` e `{"a": 1,}` são inválidos; a vírgula após o último elemento deve ser removida.
• Sem comentários - `// comentários de linha` e `/* comentários de bloco */` não fazem parte da especificação JSON.
• Sem valores undefined - `undefined` é um conceito do JavaScript; o JSON só permite `null`, números, strings, booleanos, arrays e objetos.
• Números não podem ter zeros à esquerda - `012` não é JSON válido; use `12`.
• Chaves de objeto devem ser strings - `{1: "value"}` é inválido; as chaves devem ser strings entre aspas duplas.
• Sem caracteres de controle em strings - quebras de linha, tabulações e outros caracteres de controle brutos devem ser escapados (`\n`, `\t`, etc.).

Sintaticamente válido vs. semanticamente válido

Um documento JSON pode ser sintaticamente válido (corretamente formado conforme a especificação) mas semanticamente inválido para sua aplicação. Por exemplo, um objeto JSON com "age" definido como -5 é JSON válido, mas uma idade inválida para um perfil de usuário. A validação de sintaxe é o que um parser JSON verifica; a validação de esquema é o que captura erros semânticos. Ambas as camadas importam, e este guia cobre as duas.

A forma mais rápida de verificar se uma string JSON é válida é colá-la em um validador JSON online. Sem instalação, sem configuração, sem conta. O resultado é instantâneo e - quando você usa uma ferramenta baseada em navegador - seus dados nunca saem do seu dispositivo.

Um texto JSON é um valor serializado. Note que certas especificações anteriores do JSON restringiam um texto JSON a ser um objeto ou um array.

Usando o Formatador e Validador de JSON

O Formatador e Validador de JSON da Aback Tools valida e formata JSON simultaneamente. Cole qualquer string JSON e ele informa imediatamente se a entrada é válida. Se for inválida, a ferramenta destaca a posição do erro com um número de linha e uma descrição em linguagem simples do que deu errado. Se for válida, ela gera JSON limpo e indentado que você pode copiar direto para o seu projeto.

Essa abordagem de dupla finalidade importa na prática. Quando você recebe JSON de uma API, copia de um arquivo de configuração ou extrai de uma linha de log, o texto bruto costuma estar minificado e difícil de ler. Formatar como parte da validação dá duas coisas ao mesmo tempo: a confirmação de que o JSON é válido e uma versão legível que você realmente pode inspecionar.

A maioria dos documentos JSON inválidos falha por uma de cinco razões. Conhecer esses padrões permite corrigir erros rapidamente sem depender inteiramente de uma ferramenta para diagnosticá-los.

// ❌ Inválido - vírgula após a última propriedade
{
  "name": "Alice",
  "age": 30,
}

// ✓ Válido - sem vírgula final
{
  "name": "Alice",
  "age": 30
}

// ❌ Inválido - chave e valor com aspas simples
{'city': 'London'}

// ✓ Válido - chave e valor com aspas duplas
{"city": "London"}

// ❌ Inválido - comentários não fazem parte da especificação JSON
{
  // Este é o objeto de usuário
  "name": "Alice",
  "role": "admin" /* permissões elevadas */
}

// ❌ Inválido - quebra de linha bruta dentro do valor
{"message": "line one
line two"}

// ✓ Válido - quebra de linha escapada
{"message": "line one\nline two"}

// ❌ Inválido - array aberto mas objeto fechado
{
  "items": [1, 2, 3
}

// ✓ Válido - delimitadores pareados
{
  "items": [1, 2, 3]
}

A validação de sintaxe confirma que o JSON está bem formado. A validação de esquema confirma que o JSON contém os dados certos - os campos certos, os tipos certos, as faixas de valores certas. São duas verificações distintas, e ambas são necessárias em sistemas de produção.

O que é JSON Schema?

JSON Schema é um vocabulário para descrever a estrutura e as restrições de um documento JSON. Um documento de esquema especifica quais campos são obrigatórios, que tipo cada campo deve ter, valores mínimos e máximos para números, padrões de string permitidos e mais. Ao validar um documento JSON contra um esquema, você recebe erros precisos como "o campo 'email' é obrigatório" ou "o campo 'age' deve ser um inteiro positivo" - não apenas "JSON inválido".

Usando o Validador de JSON Schema

O Validador de JSON Schema da Aback Tools aceita um payload JSON e um JSON Schema e valida o payload contra as restrições do esquema. Ele reporta erros em nível de regra com o caminho de campo exato que falhou - assim você sabe não apenas que a validação falhou, mas qual campo violou qual regra. É a ferramenta certa quando você precisa verificar se uma resposta de API atende a um contrato, ou se um arquivo de configuração contém todas as definições obrigatórias.

Validação de sintaxe vs. validação de esquema

Gerar um esquema a partir de um payload existente

A forma mais rápida de adicionar validação de esquema a um projeto existente é gerar o esquema a partir de um payload sabidamente bom. Cole um objeto JSON representativo no Gerador de JSON Schema e ele produzirá um esquema completo com definições de tipos, campos obrigatórios e dicas de formato. Copie a saída para o seu projeto e use-a como contrato de validação para todos os payloads futuros desse tipo.

Ferramentas online são a escolha mais rápida para checagens pontuais, mas sistemas de produção precisam de validação JSON embutida no código. Cada grande linguagem de programação tem pelo menos uma biblioteca de análise JSON bem mantida, e a maioria também tem bibliotecas dedicadas de validação de esquemas.

JavaScript e TypeScript

Em JavaScript, `JSON.parse()` lança um `SyntaxError` quando recebe JSON inválido - envolva-o em um try/catch para tratar o erro com elegância. Para validação de esquema, AJV (Another JSON Validator) é a biblioteca mais usada, com suporte a JSON Schema Draft-07 até Draft 2020-12 e alto desempenho. Zod é uma alternativa popular orientada a TypeScript que valida JSON contra esquemas de tipos em tempo de execução com inferência completa de TypeScript. O conversor de JSON para Esquema Zod da Aback Tools gera um esquema Zod a partir de qualquer payload JSON automaticamente.

function isValidJson(input: string): boolean {
  try {
    JSON.parse(input);
    return true;
  } catch {
    return false;
  }
}

// Or get the parsed value and the error together:
function parseJson<T>(input: string): { data: T } | { error: string } {
  try {
    return { data: JSON.parse(input) as T };
  } catch (e) {
    return { error: (e as SyntaxError).message };
  }
}

Python

O módulo `json` embutido do Python lança `json.JSONDecodeError` (uma subclasse de `ValueError`) quando a análise falha. O objeto de erro inclui o número da linha, a coluna e uma descrição. Para validação de esquema, jsonschema e pydantic são as escolhas padrão - pydantic é particularmente popular em projetos FastAPI porque valida e desserializa JSON em objetos Python tipados em uma única etapa.

import json

def is_valid_json(text: str) -> bool:
    try:
        json.loads(text)
        return True
    except json.JSONDecodeError as e:
        print(f"Invalid JSON at line {e.lineno}, col {e.colno}: {e.msg}")
        return False

Linha de comando

Em qualquer sistema com Python instalado, `python3 -m json.tool input.json` valida e imprime bonito um arquivo JSON em um único comando. O código de saída é diferente de zero em caso de falha, tornando-o adequado para scripts de shell e pipelines de CI. A ferramenta `jq` é uma alternativa mais poderosa: `jq . input.json` valida e formata, enquanto `jq 'empty' input.json` valida sem produzir saída.

# Validate and pretty-print with Python (built-in, no install)
python3 -m json.tool input.json

# Validate silently with jq (exit code 0 = valid, 1 = invalid)
jq empty input.json && echo "Valid" || echo "Invalid"

# Validate multiple files with a loop
for f in *.json; do
  jq empty "$f" && echo "$f: valid" || echo "$f: INVALID"
done

A validação JSON padrão cobre arquivos `.json` e payloads de API. Mas o JSON aparece em vários outros formatos que têm seus próprios requisitos de validação - formatos em que um parser JSON padrão produz resultados incorretos ou rejeita toda a entrada.

JSONL e NDJSON (JSON Lines)

Arquivos JSON Lines (`.jsonl`) contêm um objeto JSON por linha, sem array delimitador. Esse formato é padrão para arquivos de log, conjuntos de dados de ML e APIs de streaming. Um parser JSON padrão rejeita um arquivo JSONL porque o arquivo como um todo não é um documento JSON válido - cada linha deve ser analisada individualmente. O Validador e Corretor de JSON Lines valida cada linha separadamente, informa quais números de linha têm erros e oferece correções automáticas seguras para problemas de formatação comuns.

JSON com chaves duplicadas

A especificação JSON tecnicamente permite chaves duplicadas em objetos, mas o comportamento é indefinido - parsers diferentes o tratam de forma diferente. O `json.loads()` do Python mantém o último valor; alguns parsers mantêm o primeiro; outros lançam um erro. Na prática, chaves duplicadas são quase sempre um bug - uma mesclagem malfeita ou um erro de template. O Detector de Chaves Duplicadas em JSON encontra todas as chaves repetidas e diz exatamente onde ocorrem.

JSON em arquivos de configuração YAML

YAML é um superconjunto de JSON, então qualquer JSON válido também é YAML válido. Mas JSON embutido em arquivos YAML - como valor de um campo de string, por exemplo - precisa de sua própria validação. Se você trabalha com configs YAML que contêm valores JSON embutidos, valide as porções JSON separadamente com o formatador JSON e depois valide o YAML geral com um validador YAML. Se seu projeto usa ambos os formatos e você precisa comparar dois arquivos de configuração, o Destacador de Diferenças JSON/YAML trata ambos simultaneamente.

Validar JSON uma vez antes de uma operação importante é bom. Construir validação em todos os pontos onde o JSON entra ou sai do seu sistema é melhor. Essas práticas se aplicam tanto se você está construindo uma API, processando pipelines de dados ou gerenciando arquivos de configuração.

Valide na ingestão, não no consumo

O momento certo de validar JSON é quando ele entra pela primeira vez no seu sistema - na fronteira da API, no manipulador de upload de arquivos, no consumidor da fila de mensagens. Validar no consumo (na função que lê um valor no fundo do seu código) significa que dados inválidos se propagam mais longe antes de falhar, tornando o erro mais difícil de rastrear. Valide cedo e rejeite a entrada inválida no ponto de entrada.

Use um esquema, não apenas uma checagem de sintaxe

Validação de sintaxe é o mínimo exigível. Em qualquer sistema em que o JSON transporta dados críticos para o negócio - registros de usuários, payloads de pagamento, valores de configuração - um esquema adiciona uma segunda camada que captura tipos errados, campos obrigatórios ausentes e valores fora da faixa que a validação de sintaxe não consegue detectar. Gere seu esquema inicial a partir de um payload sabidamente bom com o Gerador de JSON Schema e refine-o conforme seu modelo de dados evolui.

Trate erros de validação explicitamente

Uma chamada a `JSON.parse()` envolta em um try/catch que engole o erro e retorna null é pior do que nenhuma validação - ela esconde o problema. Quando a validação de JSON falha, registre o erro com a fonte de entrada, a mensagem de erro exata e contexto suficiente para reproduzir o problema. Retorne um erro significativo ao chamador em vez de um resultado vazio que cause um erro secundário em outro lugar.

• Registre a entrada bruta - quando a validação de JSON falha em produção, a entrada bruta é o artefato de depuração mais valioso. Registre uma versão truncada (primeiros 500 caracteres) junto com o erro.
• Inclua o contexto de origem - anote de onde veio o JSON: qual endpoint da API, qual arquivo, qual mensagem da fila. Isso transforma um erro genérico de análise em um incidente acionável.
• Configure alertas para falhas de análise - um pico de erros de validação JSON costuma sinalizar uma mudança incompatível em uma API upstream ou um deploy que introduziu um bug de serialização.
• Teste com entradas inválidas - inclua JSON inválido (vírgula final, aspa ausente, tipo errado) na sua suíte de testes para confirmar que seu tratamento de erros se comporta corretamente.