Formatador JSON

O que este formatador de JSON faz

JSON (JavaScript Object Notation) é o formato mais comum para mover dados estruturados entre programas: respostas de API, arquivos de configuração, linhas de log e mais. Foi projetado para ser compacto, o que também o torna difícil de ler quando os objetos aninham alguns níveis ou chegam em uma única linha. Esta ferramenta pega qualquer JSON que você cola e o reescreve de duas formas: embelezado, com indentação consistente para que a estrutura fique óbvia num relance, ou minificado, sem nenhum espaço opcional, para ser o menor possível ao enviar.

Ela também valida enquanto formata. Como analisa o texto antes de reserializá-lo, um JSON inválido nunca produz uma saída enganosa — em vez disso você recebe a linha e a coluna onde a análise falhou, sempre que ela consegue deduzi-las, para ir direto ao problema.

Embelezar vs. minificar: quando usar cada um

Os dois modos têm objetivos opostos, e a maioria dos fluxos de trabalho usa ambos em etapas diferentes:

• Embeleze quando você lê ou depura: inspecionar uma resposta de API, comparar dois payloads ou revisar um arquivo de configuração em um pull request. A indentação transforma um muro de texto em uma árvore navegável.
• Minifique quando você envia: incorporar JSON em HTML, armazená-lo em um cookie ou cache, ou mandá-lo no corpo de uma requisição onde cada byte conta. O JSON minificado é exatamente os mesmos dados, apenas sem os espaços.

O seletor de indentação (2 espaços, 4 espaços ou tabulação) só afeta a saída embelezada. Dois espaços é a convenção mais comum em JavaScript e no tooling web; quatro espaços ou tabulações servem a equipes que os preferem. Qualquer que seja a escolha, o resultado continua sendo JSON válido — a indentação é puramente cosmética.

Ler os erros de validação

Quando o JSON é inválido, a ferramenta relata a linha e a coluna do primeiro problema em vez de um simples "inválido", exceto no único caso que a seção sobre para onde apontam a linha e a coluna descreve. As mensagens de erro dos motores diferem entre navegadores e frequentemente omitem uma posição, então o local é calculado de forma independente e aponta um ponto razoável para começar. Corrija o primeiro erro e verifique de novo — um único caractere perdido muitas vezes se desdobra em vários problemas aparentes.

Erros comuns de JSON

JSON é mais rígido que os objetos literais de JavaScript com os quais se parece. Estes são os erros que mais confundem:

• Vírgulas finais: uma vírgula após o último item de um objeto ou array é válida em JavaScript, mas não em JSON.
• Aspas simples: as strings e chaves JSON devem usar aspas duplas. 'valor' é inválido; "valor" é correto.
• Chaves sem aspas: toda chave de objeto deve ser uma string entre aspas, então { name: "x" } deve virar { "name": "x" }.
• Comentários: JSON não tem sintaxe de comentário. // e /* */ causarão um erro de análise.
• Números especiais: NaN, Infinity e -Infinity não são números JSON válidos.
• Aspas erradas: as "aspas tipográficas" coladas de um processador de texto parecem aspas, mas são caracteres diferentes e não serão analisadas.

Para onde apontam a linha e a coluna relatadas

A posição não é onde você omitiu algo: é onde o analisador encontrou pela primeira vez algo que não pode legitimamente estar ali, e normalmente são dois lugares diferentes. No objeto abaixo, falta à linha 3 a vírgula que deveria fechá-la, e a ferramenta relata a linha 4, coluna 3: a aspa de abertura da chave seguinte. Nada estava errado até aquela aspa chegar, porque o documento poderia legitimamente ter terminado depois da linha 3; então o analisador só fica sabendo da omissão quando encontra algo que não é nem uma vírgula nem uma chave de fechamento.

{
  "id": 42,
  "name": "widget"
  "price": 9.99
}

• Uma vírgula que falta é relatada no primeiro caractere do que vem depois, que em JSON indentado como o de cima é a linha seguinte: leia a linha indicada junto com a de cima.
• Uma vírgula sobrando é relatada na chave ou no colchete de fechamento: linha 3, coluna 1 para um objeto cujo último par está na linha 2. A vírgula promete outro par e a chave é o que quebra a promessa.
• Uma string não fechada costuma ser relatada no fim da linha em que ela abriu, e não na aspa de abertura, porque a próxima aspa numa linha posterior pode fechá-la em outro lugar. Uma quebra de linha não pode aparecer dentro de uma string JSON, então a quebra é o primeiro caractere que não pode estar ali.
• Linha 1, coluna 1 em um documento que parece perfeito quase sempre significa uma marca de ordem de bytes. Alguns editores escrevem uma ao salvar como UTF-8; ela é invisível, fica antes da chave de abertura, e JSON não tem lugar para ela.

E onde a ferramenta não consegue deduzir posição alguma, ela relata a falha sem ela em vez de citar uma coordenada adivinhada. Uma linha e uma coluna ditas com segurança mas apontando para uma sintaxe perfeitamente correta fariam você procurar no lugar errado, e isso é pior do que saber apenas que o documento não é analisado.

O que a formatação muda e o que ela conserva

Para quase todo documento a resposta é o espaço em branco e mais nada. Mas a ferramenta não edita o seu texto: ela o analisa transformando-o em valores reais e escreve esses valores de novo, e cinco coisas não sobrevivem a essa ida e volta. Nenhuma delas é uma falha da ferramenta, porque cada uma é o que a especificação do JSON diz que são um número e um objeto, e vale conhecer cada uma antes de colar a saída sobre o seu original.

• A mesma chave escrita duas vezes: só a última das duas sobrevive, porque um objeto não pode carregar uma chave duas vezes. A RFC 8259 diz que um programa que recebe um objeto com nomes duplicados se comporta de forma imprevisível, e outro analisador pode ficar com o primeiro, então qual das duas sobra também não é algo em que confiar.
• Um inteiro com mais de quinze dígitos: os números JSON são lidos como ponto flutuante de dupla precisão, que guarda com exatidão todo número inteiro até dois elevado a cinquenta e três — um número de dezesseis dígitos — então um inteiro de quinze dígitos sempre sobrevive e um mais longo pode não sobreviver. Cole 12345678901234567890 e sai 12345678901234567000. Identificadores longos de banco de dados são a vítima habitual: mantenha-os como strings se puder.
• As formas com expoente e com zeros finais são normalizadas: 1e3 volta como 1000, e 1.50 como 1.5. É o mesmo número escrito do jeito padrão.
• Uma magnitude fora do que esse formato aguenta volta como outra coisa: 1e400 não tem valor em dupla precisão e volta como null, e 1e-400 volta como 0. Uma fração decimal longa é arredondada para a precisão que o formato tem, do mesmo jeito que um inteiro longo.
• Uma sequência de escape se transforma no caractere que ela denota: \u00e9 volta como é, e um par surrogado com escape volta como o emoji que ele soletra. Para qualquer analisador são a mesma string; uma das duas escritas é simplesmente mais curta.

A ordem das chaves é conservada como você escreveu, com uma exceção que vale conhecer: uma chave feita só de dígitos, que se lê como um inteiro não negativo simples abaixo de uns quatro bilhões, é tratada como índice de array e volta para o começo do seu objeto em ordem numérica, onde quer que você a tenha posto. Mais nada se move: nenhuma outra chave é reordenada, e nenhuma é acrescentada ou renomeada. Se algo disso importa para você, minifique em vez de embelezar e compare o resultado com o seu original caractere por caractere. É o caminho mais curto para ver o que a ida e volta fez.

Quando o JSON que você quer está dentro de uma string

Registros de webhooks, filas de mensagens e colunas de banco de dados carregam muito frequentemente um documento JSON inteiro como um único valor de string, com cada aspa de dentro em escape. O documento de fora é perfeitamente válido, então a ferramenta o embeleza e o relata válido — e a parte que você veio ler continua uma longa linha de barras invertidas. Nada deu errado: são dois documentos, um embrulhado dentro de uma string do outro.

{
  "event": "order.created",
  "payload": "{\"id\":42,\"total\":19.99}"
}

Ler isso exige, portanto, duas passadas. Formate aqui o documento de fora, copie o que está entre as aspas da string que você quer, desfaça o escape e cole o resultado de volta. A ferramenta Escape / unescape de strings JSON faz esse passo do meio: a direção de unescape dela transforma \" de novo em " e a linha de novo em um documento que esta página consegue formatar. Se você controla o que produziu o arquivo, a correção melhor está mais acima: envie o payload como objeto aninhado em vez de string, e nenhuma passada é necessária.

Um objeto por linha não é um documento

Arquivos de log, exportações de API e endpoints de streaming costumam guardar um objeto JSON completo por linha; o formato se chama JSON Lines, ou NDJSON. Cada linha é JSON válido por si só, mas o arquivo não é um documento JSON, porque um documento JSON guarda exatamente um valor de nível superior e este guarda vários, um depois do outro e sem nada que os junte.

{"level":"info","msg":"started"}
{"level":"warn","msg":"retrying"}
{"level":"error","msg":"gave up"}

Cole isso aqui e a ferramenta relata a linha 2, coluna 1: o primeiro objeto terminou de forma limpa, e então um segundo começou onde o documento deveria ter acabado. Dali existem dois caminhos. Formate uma linha por vez, que é o que você quer quando está lendo uma única entrada de log. Ou transforme o arquivo em um documento — embrulhe as linhas em colchetes e ponha uma vírgula no fim de cada linha menos a última — que é o que você quer quando está a ponto de carregar tudo em algo que espera um array.