JSON inválido: como encontrar o erro, preservar tipos e validar com JSON Schema

Por Equipe IATechNerds. Revisão: Revisão humana pendente. Atualizado em 14 de agosto de 2026.

Como este conteúdo foi produzido: Conteúdo original baseado no RFC 8259, na especificação ECMAScript de JSON.parse e na documentação oficial do JSON Schema. Exemplos usam dados sintéticos e aguardam revisão humana.

Intenção de busca: resolver buscas como “JSON inválido”, “Unexpected token em JSON” e “como validar JSON Schema”, separando erro de sintaxe, codificação, transporte e contrato.

A mensagem “Unexpected token” costuma aparecer no pior lugar: depois de baixar uma resposta, importar uma configuração ou colar um documento grande. Corrigir a vírgula indicada pode resolver o primeiro erro e revelar outros. Em casos mais difíceis, o arquivo é JSON válido, mas a aplicação continua falhando porque um identificador virou número, uma data chegou em formato inesperado ou um campo obrigatório não existe.

O caminho confiável tem quatro camadas. Primeiro preserve os bytes recebidos. Depois valide a sintaxe. Em seguida examine tipos e valores. Por fim aplique um contrato, normalmente um JSON Schema. Essa ordem evita “consertar” o arquivo até que ele pareça aceitável enquanto o significado original é perdido.

Comece distinguindo JSON de objeto JavaScript

JSON possui uma gramática pequena: objetos, arrays, strings, números, os literais true, false e null. Nomes de propriedades e strings usam aspas duplas. Comentários, vírgulas finais, undefined, NaN, funções e aspas simples não fazem parte do formato definido pelo RFC 8259.

{
  "nome": "Ana",
  "ativo": true,
  "idade": 17
}

Um literal aceito pelo JavaScript pode não ser JSON. O trecho {nome: 'Ana'} é uma expressão de objeto em certos contextos, mas não um documento JSON. Não use eval para “aceitar mais formatos”; isso executa código e muda completamente o risco do processamento.

Se a fonte promete JSON, exija JSON. Se ela entrega JSON5, YAML ou JavaScript, identifique o formato e use um parser próprio. Renomear a extensão não altera a gramática.

Preserve os bytes e confirme a codificação

Antes de editar, guarde uma cópia do conteúdo bruto. Uma interface pode mostrar caracteres substitutos enquanto o arquivo original ainda contém bytes recuperáveis. O RFC 8259 recomenda UTF-8 para interoperabilidade entre sistemas que não fazem parte de um ecossistema fechado.

Se a entrada veio por HTTP, registre status, Content-Type, tamanho e um identificador da requisição. Uma página HTML de erro pode ser recebida no lugar do JSON; nesse caso, o parser acusa o caractere < no início, mas o defeito real é autenticação, rota ou gateway. Examine uma amostra segura do corpo antes de culpar a sintaxe.

Não publique tokens ou dados pessoais ao pedir ajuda. Substitua valores sensíveis preservando aspas, vírgulas, chaves e comprimentos relevantes. Para comparar duas cópias, use a ferramenta Diferenças entre textos; para calcular uma impressão do arquivo, use o gerador de hash.

Use a posição do parser como ponto de partida, não como sentença

JSON.parse normalmente informa uma posição ou descreve o token inesperado. Essa posição aponta onde o parser deixou de conseguir continuar, que pode ser depois da causa. Uma aspa não fechada em uma linha faz a mensagem aparecer várias linhas abaixo.

try {
  const dados = JSON.parse(texto);
  console.log('válido', dados);
} catch (erro) {
  console.error(erro.message);
}

Formate apenas quando o documento já for analisável. Um “beautifier” não consegue estruturar com segurança um texto quebrado; ferramentas que tentam adivinhar podem inserir ou remover caracteres. No formatador e validador JSON, valide primeiro e use a mensagem para criar uma cópia corrigida.

Para arquivos grandes, extraia uma janela ao redor da posição: alguns caracteres antes e depois, com dados mascarados. Conte linhas a partir do arquivo bruto, pois editores podem normalizar quebras de linha e deslocar a referência.

Revise os oito erros de sintaxe mais frequentes

• aspas simples em vez de aspas duplas;
• nome de propriedade sem aspas;
• vírgula após o último item;
• vírgula ausente entre propriedades ou elementos;
• barra invertida sem escape válido dentro de string;
• quebra de linha literal dentro de string;
• comentário // ou /* */;
• texto adicional antes ou depois do valor JSON.

Corrija um erro por vez na cópia e valide novamente. Quando dezenas de linhas exibem o mesmo padrão, volte à origem: provavelmente um serializador manual está concatenando strings. A solução durável é gerar JSON com a biblioteca da linguagem, que escapa caracteres e posiciona delimitadores corretamente.

Não faça substituições globais como trocar todas as aspas simples. Apóstrofos podem fazer parte do conteúdo e barras podem representar caminhos. A correção deve respeitar o contexto sintático.

Entenda escapes, barras e Unicode

Dentro de uma string JSON, aspas duplas e barra invertida precisam de escape. Quebra de linha é representada por \n, tabulação por \t e uma barra literal por \\. Um caminho do Windows pode aparecer como "C:\\dados\\arquivo.json".

Sequências \uXXXX representam unidades de código Unicode. Caracteres fora do plano básico podem usar um par substituto. Na prática, prefira transportar UTF-8 diretamente quando o sistema suporta, mas mantenha um parser compatível com os escapes previstos pelo padrão.

O caractere invisível no início, como um BOM, pode ser tolerado por algumas ferramentas e rejeitado por outras. Se a origem é interoperável, padronize a geração e teste com acentos, emoji, barras, aspas e controles. Não remova caracteres de controle silenciosamente: reporte a posição e peça correção na fonte.

Números válidos podem ser inadequados para o seu sistema

A gramática JSON usa ponto como separador decimal e não permite zeros iniciais em inteiros com vários dígitos. Assim, 00123 não é um número JSON válido. Se representa CEP, pedido ou matrícula, deve ser string: "00123".

Mesmo um número sintaticamente válido pode exceder a precisão segura do ambiente. JavaScript usa o tipo Number para o caminho comum, e inteiros grandes podem ser arredondados. Identificadores longos devem viajar como strings. Valores monetários exigem contrato de escala, arredondamento e unidade; uma opção é transportar centavos como inteiro dentro do intervalo seguro, outra é usar string decimal validada.

Teste limites: zero, negativo, decimal, inteiro máximo esperado e valor ausente. Diferencie null de zero e de propriedade ausente. Essas três situações podem ter significados de negócio distintos.

Detecte chaves duplicadas antes que o parser escolha por você

Um objeto pode conter o mesmo nome mais de uma vez no texto. O RFC alerta que o comportamento dos consumidores pode variar; muitas implementações mantêm apenas o último valor. O documento parece carregar duas informações, mas depois de JSON.parse resta uma.

{"status":"novo","status":"cancelado"}

Para dados críticos, valide duplicidade durante a leitura textual com um parser que ofereça esse diagnóstico, antes de converter para a estrutura comum da linguagem. Não tente detectar depois: a informação já pode ter sido descartada.

A correção depende da intenção. Se deveriam ser campos diferentes, ajuste os nomes. Se são ocorrências repetidas, use um array. Se existe uma regra de prioridade, implemente-a explicitamente na origem e gere apenas uma propriedade. Um objeto JSON não deve funcionar como histórico implícito.

Separe validade sintática de validade estrutural

{} é JSON válido, mas provavelmente não é um pedido válido. A sintaxe responde “consigo analisar este texto?”. O contrato responde “os campos necessários, tipos, formatos e limites correspondem ao que a aplicação aceita?”. JSON Schema formaliza essa segunda pergunta.

Comece com um esquema pequeno que declare o vocabulário e a versão usados. Defina type: "object", propriedades, campos obrigatórios e restrições que realmente pertencem à interface. Evite transformar toda regra de negócio em expressão complexa; algumas verificações dependem de banco, usuário ou estado e devem permanecer na aplicação.

Valide entrada e saída em limites de sistema: requisição recebida, mensagem de fila, arquivo importado e resposta de API. Dentro do mesmo processo, tipos estáticos e testes também ajudam, mas não substituem a verificação de dados externos.

Monte um JSON Schema mínimo e evolua com exemplos

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {"type": "string", "minLength": 1},
    "quantidade": {"type": "integer", "minimum": 0},
    "ativo": {"type": "boolean"}
  },
  "required": ["id", "quantidade"],
  "additionalProperties": false
}

properties descreve campos, mas não os torna obrigatórios. Para isso existe required. additionalProperties: false rejeita nomes não declarados, útil para detectar erro de digitação, mas pode dificultar evolução compatível. Decida se consumidores antigos devem ignorar novos campos ou falhar cedo.

Inclua exemplos válidos e inválidos no repositório. Um teste deve mostrar o caminho do erro, o valor recebido e a regra violada sem despejar dados sensíveis. Ao atualizar o esquema, execute os exemplos das versões anteriores para saber se a mudança é compatível.

Valide datas, formatos e relações sem criar falsa confiança

JSON não possui tipo de data; datas são strings por convenção. Um schema pode exigir format: "date" ou date-time, mas o comportamento de format depende do validador e da configuração. Confirme se a implementação realmente afirma essa validação.

Uma data de calendário como 2026-08-14 não é o mesmo que um instante. Para instantes, inclua deslocamento ou Z e defina como o sistema normaliza fuso. Para valores com dependência entre campos — por exemplo, data final posterior à inicial — pode ser necessária uma validação de aplicação além do esquema.

Use expressões regulares com cautela. Elas verificam aparência, não existência real de uma data ou semântica completa. A ferramenta testador de expressões regulares ajuda a construir casos, mas mantenha exemplos negativos e limites de tamanho para evitar padrões caros.

Crie um pipeline reproduzível de diagnóstico e correção

1. salve o corpo bruto e calcule tamanho e hash;
2. confirme status HTTP, tipo de conteúdo e codificação;
3. execute um parser estrito e registre posição;
4. corrija somente a cópia;
5. repita até a sintaxe ser válida;
6. verifique chaves duplicadas, números e Unicode;
7. aplique o JSON Schema da versão correta;
8. liste erros por caminho, sem descartar campos;
9. compare original e corrigido;
10. corrija o serializador na origem.

Para reproduzir, crie uma amostra mínima que mantenha o defeito. Use o gerador de dados fictícios quando precisar substituir valores reais e o comparador de texto para revisar alterações.

Se o documento vier em fluxo contínuo ou em JSON Lines, não tente analisá-lo como um único JSON. Defina o formato: JSON Lines contém um valor JSON por linha e exige processamento adequado.

Trate arrays grandes, ordem e paginação de forma explícita

Arrays preservam a ordem dos elementos, mas isso não significa que a ordem tenha valor de negócio. Se uma API retorna itens ordenados, documente o critério e um desempate estável. Caso contrário, duas respostas equivalentes podem produzir diferenças enormes apenas porque a sequência mudou. Para comparar conjuntos, use uma chave única e ordene uma cópia exclusivamente para o diagnóstico.

Em listas grandes, valide cada elemento e registre o índice junto ao caminho do erro, por exemplo /itens/37/quantidade. Limite a quantidade de mensagens mostradas sem esconder a contagem total: milhares de falhas idênticas costumam apontar para uma regra de origem, não para milhares de correções manuais.

Paginação também pertence ao contrato. Defina se o cursor pode ser nulo, se a lista vazia encerra a leitura e se itens podem aparecer novamente entre páginas. Um JSON perfeito por página ainda pode gerar perda ou duplicidade quando o cliente ignora essas regras. Teste primeira página, página intermediária, última página e resposta vazia com dados sintéticos.

Checklist editorial e técnico do JSON corrigido

• O conteúdo bruto foi preservado?
• Status, tipo de conteúdo e codificação foram registrados?
• O documento é JSON, e não JavaScript, JSON5 ou HTML?
• A posição do primeiro erro foi documentada?
• Identificadores longos e com zeros são strings?
• Chaves duplicadas foram procuradas antes do parse comum?
• null, ausência e zero possuem significados definidos?
• O schema declara versão e campos obrigatórios?
• Campos adicionais seguem uma política consciente?
• Exemplos válidos e inválidos passam pelos testes?
• A origem foi corrigida para usar serialização nativa?

Um JSON confiável não é apenas aquele que o formatador colore. Ele preserva o significado dos dados e comprova sua aderência a um contrato versionado.

Fontes e documentação primária

• RFC Editor — RFC 8259, JSON Data Interchange Format
• ECMAScript — JSON.parse
• JSON Schema — referência de objetos

Camada extra: como tomar uma decisão melhor neste cenário

Um artigo sobre JSON inválido: como encontrar o erro, preservar tipos e validar com JSON Schema fica mais útil quando separa a solução imediata da decisão que continua válida depois que a tela, a versão do software ou o dispositivo muda.

Diagnóstico prático de JSON quebrado, com reprodução no navegador e Node.js, cuidados com números e Unicode e validação estrutural por esquema. A ideia central pode ser testada com quatro perguntas: o que foi observado, qual hipótese explica o sintoma, qual mudança é reversível e qual evidência prova que funcionou. Esse encadeamento evita que uma coincidência seja confundida com causa e torna o procedimento repetível por outra pessoa.

Integridade vem antes da aparência

Em JSON, JSON Schema, API, qualidade de dados, o arquivo “abrir” não significa que os dados chegaram intactos. Antes de transformar, separe uma amostra com um registro normal, uma duplicidade, um valor vazio, um código com zero à esquerda e um caso de limite. Essa amostra funciona como teste de regressão: qualquer importação, limpeza ou conversão precisa preservar o que é informação e alterar somente o que é representação.

Compare contagem de linhas, quantidade de chaves únicas, somas de controle quando fizer sentido e tipos esperados. Datas, identificadores e casas decimais merecem atenção especial porque podem parecer visualmente corretos e ainda assim mudar de significado. Guarde o original sem sobrescrever e documente a regra aplicada; isso permite voltar atrás sem depender da memória.

Uma matriz simples para não misturar problemas

Camada	Pergunta	Validação
Estrutura	Colunas e registros continuam presentes?	Contagens e cabeçalhos
Tipo	Código, data e número mantiveram o significado?	Amostra com casos-limite
Conteúdo	Houve perda, truncamento ou duplicação?	Comparação antes/depois

Quando automatizar

Automação vale a pena quando a regra já é clara e o teste consegue detectar erro. Se ainda existem exceções não descritas, automatizar apenas faz o erro chegar mais rápido a mais linhas. Comece com uma amostra pequena, registre a saída esperada e só então escale para o conjunto inteiro.

Checklist de fechamento

• Registre o estado inicial antes de alterar qualquer coisa.
• Faça uma mudança por rodada e anote o efeito.
• Teste um caso normal, um caso-limite e o cenário que originalmente falhou.
• Confirme que a solução continua válida depois de reiniciar, reabrir ou repetir o fluxo.
• Guarde uma forma de voltar ao estado anterior quando a alteração for destrutiva.

Esse método acrescenta profundidade sem transformar o artigo em teoria abstrata: o leitor entende por que cada passo existe e como reconhecer quando a situação exige uma decisão diferente.