Você acha que seu JSON está bom porque o JSON.parse não disparou erro? Na realidade, ser parseável não significa que os dados estão corretos. O que você faz quando o backend retorna {user_id: 123} (chave sem aspas)? A API espera um campo email, mas você só vê mail? Essas são as três camadas da validação de JSON — a maioria dos tutoriais só cobre a primeira. Este post detalha as 3 camadas e como o formatador de JSON do Piick aponta a localização exata do erro.

Os três níveis da validação de JSON

A validação tem três camadas, e cada uma resolve um problema diferente:

  • Camada de sintaxe: se a string é um JSON válido — aspas, vírgulas e colchetes batem. O JSON.parse faz isso por padrão.
  • Camada de estrutura: se os dados casam com um schema predefinido — user é um objeto, tags é um array, os campos obrigatórios estão presentes. O JSON Schema é o padrão de fato aqui.
  • Camada semântica: se os valores fazem sentido — status está em um enum válido, age está entre 0 e 150, email tem o formato correto. Essa camada depende do código de negócio ou de bibliotecas como Zod e Ajv.

90% dos bugs vivem nas duas últimas camadas. A camada de sintaxe é só o ticket de entrada.

Sintaticamente correto não é o mesmo que dados corretos

Aqui vai um cenário real: a API deveria retornar { "code": 0, "data": { "userId": 123 } }, mas na verdade retorna { "data": { "userid": 123 } } — caixa errada. O JSON.parse passa, mas o frontend lê userId e recebe undefined, então a UI fica em branco. Esse tipo de bug é especialmente difícil de rastrear em produção.

A solução: use JSON Schema para gerar os tipos em TypeScript, ou faça validação de schema na camada de requisição. Trate o schema como o contrato da API e rejeite tudo que não bater imediatamente, em vez de esperar por erros em tempo de execução.

5 erros comuns em JSON e como depurar

  1. Vírgulas finais {"a":1,} — remova a última vírgula, ou use o modo tolerante do formatador de JSON do Piick para removê-las automaticamente
  2. Strings com aspas simples {'a':1} — substitua globalmente por aspas duplas, ou deixe o modo tolerante cuidar disso
  3. Chaves sem aspas {a:1} — envolva as chaves com aspas duplas
  4. Comentários esquecidos // xxx — apague-os, ou deixe o modo tolerante removê-los
  5. Cabeçalho BOM {"a":1} — salve como UTF-8 sem BOM

Dica de depuração: não conte colchetes no olho. Use direto o recurso “mostrar números de linha” da ferramenta.

Mais um caso clássico: copiar JSON de um PDF ou de uma página web frequentemente insere caracteres invisíveis como o U+200B (zero-width space) ou o U+FEFF (BOM). Eles passam despercebidos no olho, mas quebram o parser. Se o erro parece estar numa linha “vazia”, vale abrir o arquivo em um editor hexadecimal e conferir o início do arquivo.

Como localizar a posição exata do erro após o parse

Os erros do JSON.parse só dizem Unexpected token sem informar onde. O Chrome DevTools, o Postman e plugins do VS Code mostram números de linha, mas todos exigem copiar e colar manualmente.

Mais preciso é o formatador de JSON do Piick — ele lê o position N do erro do V8, converte para um número de linha e coluna e exibe no banner de erro. Cole um JSON quebrado e você verá exatamente em qual linha e coluna está o erro. Para pontos de partida em validação de schema, confira a lista oficial de implementações de JSON Schema.

Abra agora o formatador de JSON do Piick, cole uma string de JSON e experimente a localização precisa dos erros que ele oferece.