JSON Toolkit

Guia de Reparo de JSON: resgatando saídas quebradas de LLM sem perder a confiança

Resumo: Saídas de LLM embrulhadas em cercas de markdown, com vírgulas finais e literais Python, não sobrevivem a um parser estrito — o mesmo vale para configs editadas à mão sem aspas. Este guia traça a fronteira real entre nove classes de erros que um reparador corrige e quatro que ninguém corrige, explica por que máquinas de estados vencem regex e entrega uma cadeia de parse pronta para produção com jsonrepair e json-repair.

Intermediário~6 min de leituraPublicado em 2026-11-08Atualizado em 2026-11-08
Diagrama do pipeline de reparo de JSON: remoção de cercas, normalização de aspas, balanceamento de colchetes e validação final

Um parser estrito não dá desconto nenhum a entrada quebrada: uma mensagem de erro, um número de linha — e nem um único byte dos seus dados. O reparador existe para transformar "falha total" em "bom o suficiente para rodar" — mas o que ele preenche é sempre uma melhor estimativa da intenção, nunca uma garantia de correção.

Um: de onde vem o JSON quebrado

Reparo não é mágica — comece examinando a entrada. Em projetos reais, o JSON não padrão vem de três fontes concentradas:

  1. Saídas de LLM. Modelos de linguagem geram texto token por token; eles não rodam um serializador JSON. Mesmo pedindo "só JSON", o modelo embrulha a resposta em uma cerca ```json, adiciona "Claro! Aqui estão seus dados" antes, deixa uma vírgula final ou bate no teto de tokens e para no meio de um objeto.
  2. Cópia de outras linguagens. Um objeto JavaScript impresso via console.log carrega aspas simples e chaves sem aspas; um dicionário Python imprime como True/False/None. Essas strings "com cara de JSON" explodem no primeiro contato com JSON.parse.
  3. Configs JSON5/JSONC. Arquivos como tsconfig permitem legitimamente comentários e vírgulas finais. Cole um deles em um parser estrito e ele rejeita o arquivo inteiro.

As três fontes pedem tratamentos diferentes, mas reparadores cobrem todas — desde que o erro esteja na lista declarada de casos corrigíveis.

Dois: nove classes de erros que um reparador realmente corrige

Combinando a documentação da biblioteca jsonrepair com as listas de capacidades publicadas pelos fornecedores de ferramentas, os erros reparáveis automaticamente se dividem em nove classes:

Classe Entrada quebrada Resultado reparado
Vírgula final [1, 2, 3,] [1, 2, 3]
Aspas simples / curvas {'a': 'b'}、{"a": "b"} {"a": "b"}
Chaves sem aspas {name: 'Ada'} {"name": "Ada"}
Comentários {"a": 1 /* nota */} {"a": 1}
Literais Python {"ok": True, "v": None} {"ok": true, "v": null}
Cercas markdown ```json {...} ``` {...}
Vírgulas ausentes [1 2] [1, 2]
Colchetes / aspas não fechados {"a": [1, 2 {"a": [1, 2]}
JSONP / concatenação de strings cb({...})、"x" + "y" {...}、"xy"

O que essas nove classes têm em comum: os dados estão todos lá; só a sintaxe está quebrada. O reparador ajusta pontuação e embrulhos sem tocar em um único valor. Alguns detalhes merecem atenção especial:

  • Números com zero à esquerda viram strings. 007 é reparado como "007", não como 7, para não perder dígitos. Se o campo é realmente um código textual, isso é correto; se é um número de verdade, a decisão é sua.
  • Palavras nuas viram strings. NaN não pode ser reparado em número — algumas implementações emitem "NaN", outras null. O comportamento varia entre bibliotecas; teste a sua antes de colocá-la em um pipeline.
  • Entrada válida passa intacta. Todo reparador sério roda primeiro um caminho rápido de parse estrito. JSON válido nunca entra na lógica de reparo, então "reparar um documento bom em um ruim" é impossível.

Três: quatro coisas que um reparador não corrige

A fronteira do outro lado é igualmente explícita. Não espere reparo para:

  1. Páginas de erro HTML ou pura prosa. Não há estrutura JSON nenhuma na entrada, e nenhuma ferramenta cria dados do nada.
  2. Dados sintaticamente válidos, mas errados. Uma chave com erro de digitação, um valor no lugar errado, um número salvo como string — esses são problemas semânticos que todo parser, reparadores incluídos, deixa passar sem reclamar.
  3. Dados perdidos por truncamento. O preenchimento pode transformar {"items": [{"id": 1}, {"na em JSON válido, mas o valor de name nunca volta. Você recebe um objeto "válido, mas incompleto". Em produção, verifique stopReason === "max_tokens" antes de decidir entre completar ou tentar de novo.
  4. Chaves duplicadas e estruturas ambíguas. Qual de duas chaves idênticas vence depende da implementação do parser. Reparadores responsáveis oferecem um modo strict que lança erro em vez de escolher em silêncio.

Uma frase resume a fronteira de confiança: reparo é uma melhor estimativa, não uma garantia de correção. Deixar passar um resultado de reparo não verificado para jusante troca um erro de sintaxe barulhento por um erro de dados silencioso.

Quatro: duas escolas de implementação — uma URL resolve a discussão

Os reparadores do mercado vêm em dois sabores, e a diferença aparece em um tipo bem específico de entrada.

A escola de substituição por regex aplica buscar-e-substituir global sobre padrões quebrados. Considere esta entrada:

{"url": "http://example.com", 'note': 'fine'}

Uma regex que converte aspas simples em duplas mastigará o conteúdo da URL; uma regex de limpeza de comentários que apaga todo // cortará http:// ao meio. Dentro de uma string e fora de uma estrutura, os caracteres parecem idênticos — regex não consegue distinguir.

A escola de máquina de estados caractere por caractere rastreia um estado de parse: dentro de string com aspas duplas, com aspas simples, dentro de comentário de linha, de comentário de bloco, ou esperando um valor. Ao ver ', ela primeiro pergunta "estou dentro de uma string?" antes de decidir se converte a aspa ou pula. http://example.com está dentro de uma string de aspas duplas, então a máquina de estados sabe que o // é dado, não comentário, e o preserva. jsonrepair e json-healer pertencem a essa escola, e o mantra da comunidade "um reparador não é buscar-e-substituir" se refere exatamente a isso.

A ordem completa do pipeline de reparo (como divulgada pela implementação devkits) também vale uma olhada: remover cercas → normalizar aspas curvas → extrair o primeiro bloco balanceado → remover comentários → colocar aspas nas chaves nuas → tirar vírgulas finais → converter literais → re-serializar com JSON.stringify. Essa re-serialização final é o passo-chave: não importa o que as etapas anteriores fizeram, a saída é regenerada a partir do resultado parseado, então qualquer parser estrito a jusante a consome.

Cinco: integrando no código — uma cadeia de parse sequencial

Quando você integra reparo no código, a ordem importa mais que a escolha da biblioteca. Seguindo os padrões publicados por json2toon e aijsonmedic, a sequência deve ser: verificação de truncamento → extração do trecho JSON → parse estrito → reparo como fallback → validação por schema.

import { jsonrepair } from "jsonrepair";

export function parseModelJson(text, stopReason) {
  if (stopReason === "max_tokens") {
    // Reparar saída truncada ainda deixa dados faltando — tente novamente
    throw new Error("Truncated output: retry with a higher max_tokens");
  }
  // Extraia o trecho JSON: o LLM pode enrolar antes e depois
  const start = text.search(/[[{]/);
  const end = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
  const candidate = start >= 0 && end > start ? text.slice(start, end + 1) : text;
  try {
    return JSON.parse(candidate);   // caminho rápido para entrada válida
  } catch {
    return JSON.parse(jsonrepair(candidate));  // reparo como fallback
  }
}

No lado Python, o pacote json-repair (mais de 4.700 estrelas) oferece loads(), que devolve um objeto direto:

from json_repair import repair_json
import json

broken = "{name: 'Ada', tags: ['x',], active: True}"
data = json.loads(repair_json(broken))
# {'name': 'Ada', 'tags': ['x'], 'active': True}

Dois detalhes de engenharia:

  • Alinhe suas pilhas. Se frontend e backend repararem, escolha implementações com semântica compartilhada — o Python json-repair e seu porte TypeScript @yarmu/json-repair, ou o jsonmend, cujas versões Python e JS passam pelo mesmo corpus de conformidade de 485 casos. Senão, a mesma saída se repara em A no cliente e em B no servidor, e o debug vira um pesadelo.
  • Ative o log de reparo. @yarmu/json-repair com logging: true devolve um array de cada operação de reparo. Um salto súbito na taxa de reparos geralmente significa que o prompt ou a versão do modelo mudou — um sinal mais cedo do que qualquer relatório de erro.

Um passo depois do reparo é inegociável: validação por schema. Sintaticamente válido não significa utilizável. Campos ausentes, tipos errados e chaves inesperadas são todos pegos por um schema. A abordagem de testes de contrato se aplica diretamente aqui; veja nosso guia sobre testes de contrato com JSON Schema.

Seis: checklist de prevenção — o reparo mais barato é o que você nunca precisa fazer

Reparo é o fallback. Produzir menos JSON quebrado na fonte é a vitória real, em ordem de prioridade:

  1. Structured Outputs (modo json_schema). A decodificação é constrangida pelo schema, então uma vírgula final simplesmente não pode ser gerada. O modo strict da OpenAI falha em cerca de 0,1%, ao custo de exigências duras como additionalProperties: false.
  2. Modo JSON (json_object). Garante apenas validade sintática — não a forma — e truncamento por limite de tokens continua acontecendo.
  3. Instruções explícitas. Em endpoints sem modo JSON, escrever "sem cercas, sem comentários, sem vírgulas finais, só o objeto" reduz a taxa de erros em 70–80%.
  4. Baixar a temperature, subir o limite de tokens. A primeira reduz a deriva para prosa; a segunda reduz truncamentos.
  5. Tentar de novo com o erro anexado. Quando a validação falha, junte a saída quebrada mais o "caminho JSON + mensagem de erro" à conversa e peça novamente. Modelos geralmente se autocorrigem diante de um erro preciso.

Na prática, empilhar "structured outputs + reparo como fallback + validação por schema" cobre praticamente todos os cenários.

Sete: dividindo o trabalho — conversão de dialeto não é reparo

Na caixa de ferramentas deste site, dois destinos cobrem segmentos distintos deste pipeline:

  • Problemas de dialeto (comentários, aspas simples, vírgulas finais) vão direto ao conversor JSON5. A conversão JSON5 ↔ JSON padrão cobre exatamente essas três classes, com semântica explícita, sem adivinhação. Se a entrada inteira é um arquivo JSONC/JSON5, a conversão é mais previsível que o reparo. Sobre os compromissos dos próprios dialetos, veja o guia JSON5 e JSONC.
  • Depois do reparo, passe o resultado pelo parser JSON para validar e formatar, com erros localizados em linha e coluna, confirmando que um parser estrito realmente aceita a saída.
  • Problemas de classe biblioteca (literais Python, preenchimento de truncamento, embrulhos JSONP, cercas markdown) ainda exigem jsonrepair / json-repair no código — não existe reparo equivalente de um clique no navegador, porque esses reparos envolvem inferir intenção, e uma biblioteca local é um lar mais seguro para isso do que um conversor universal.

Se o que você tem em mãos é uma mensagem de erro em vez de dados quebrados, comece pelo guia de correção de erros de parse de JSON para traduzir a mensagem em coordenadas e só então decida: editar à mão ou reparar.

FAQ

O reparo de JSON corrompe meus dados?

Para as nove classes reparáveis, mudam só pontuação e embrulhos — os valores ficam intactos, e //, vírgulas e chaves dentro de strings são preservados pela máquina de estados. Mas o preenchimento de truncamento entrega objetos incompletos, números com zero à esquerda viram strings, e o tratamento de NaN varia entre bibliotecas. Revisar os campos-chave após o reparo é obrigatório.

Qual a relação entre reparo e validação?

A validação diz onde a entrada é ilegal; o reparo entrega um documento legal. O fluxo confiável faz os dois: reparar primeiro, validar depois — o schema pega tipos e campos obrigatórios, a checagem sintática confirma que um parser estrito aceita o resultado. Reparar sem validar troca um erro de sintaxe barulhento por um erro de dados silencioso.

O LLM sempre embrulha a saída em uma cerca ```json — o que faço?

A curto prazo, extraia: pegue o texto do primeiro { ou [ até o último } ou ] e faça o parse; um reparador com remoção de cercas também engole a mensagem inteira. A longo prazo, use structured outputs ou uma instrução explícita "sem cercas markdown" para que a cerca nunca seja gerada.

jsonrepair ou json-repair — qual escolher?

Para JavaScript, o pacote npm jsonrepair (suporta transform em streaming); para Python, json-repair do PyPI. Se as duas pontas reparam, escolha um par com semântica alinhada — por exemplo, json-repair mais seu porte TS — para que a mesma entrada se repare identicamente dos dois lados.

Reparadores lidam com português e aspas curvas?

Sim. Aspas tipográficas de teclados brasileiros (" "), espaços não separáveis e o BOM no começo do arquivo estão todos na lista padrão de reparo; aspas curvas são normalizadas para retas. Passe o resultado por um validador uma vez e está resolvido.