Um formatador JSON (formatter / beautifier / pretty printer / validator) nao e decoracao — e infraestrutura de legibilidade para depurar APIs, gerenciar arquivos de configuracao, troca de dados e decodificacao de payloads JWT. O habito de formatacao da maioria dos desenvolvedores e “pressionar o atalho de formato da IDE”, o que resolve 30% do problema. Os 70% restantes (virgulas finais, escape Unicode, perda de precisao em inteiros grandes, caracteres BOM, aspas simples, serializacao de NaN / Infinity / undefined, efeitos secundarios de ordenar chaves) nao podem ser resolvidos com a IDE.

O valor principal de um formatador JSON nao e “fazer o JSON ficar bonito” — e fazer os dados serem legiveis por humanos durante a depuracao de APIs, revisao de configuracao, analise de logs, decodificacao de JWT. Isso e infraestrutura, nao embelezamento. Este artigo cobre 8 erros reais no formato “sintoma + por que + como corrigir”, depois apresenta o Formatador JSON Piick — destaque de sintaxe + ordenar chaves + parse tolerante (JSON5 / aspas simples / comentarios) + clique-para-pular para posicao de erro + 5 metricas (chaves / arrays / profundidade maxima de aninhamento / bytes), 100% local, tudo em 1 minuto.

Resumo em 30 Segundos

  • Formatacao JSON != embelezamento: o primeiro e infraestrutura de legibilidade para API / configuracao / inspecao de logs; o segundo e apenas “fazer o codigo ficar arrumado”
  • O padrao JSON tem 4 restricoes rigidas: virgulas finais nao permitidas, strings devem usar aspas duplas, comentarios nao permitidos, NaN / Infinity / undefined nao permitidos (4 erros obrigatorios)
  • 3 usos incorretos comuns do ecossistema JS: virgula final (legal em ES2017+), literais de objeto com aspas simples, template strings aninhadas em JSON (desastre de escape)
  • 8 erros comuns: virgula final / escape Unicode / precisao de inteiros grandes / indentacao != aninhamento / caracteres BOM / aspas simples / serializacao NaN-Infinity-undefined / efeito secundario de ordenar chaves
  • Direcao da correcao: sempre valide com uma ferramenta (especialmente a configuracao de API de producao), sempre parse tolerante (desenvolvimento), sempre preserve inteiros grandes como strings (Snowflake ID), nunca ordene chaves automaticamente (afeta Git diff)
  • Use o Formatador JSON Piick online para formatar / validar / embelezar, parse tolerante + destaque de sintaxe + clique-para-pular para posicao de erro + 5 metricas, tudo processado em local

8 Erros Comuns

Erro 1: Virgula Final Rejeitada pelo Padrao JSON

Sintoma: Do Chrome DevTools “Copy as fetch”, voce copia o corpo da resposta, cola no formatador JSON e ele reporta “Unexpected token”. Voce pensa que e um bug da ferramenta — na verdade o JSON copiado pelo DevTools tem virgula final (virgula extra apos a ultima chave), que o padrao JSON nao permite.

Por que: ECMAScript 2017+ permite virgulas finais em literais de objeto, entao o JSON copiado pelo Chrome / Firefox DevTools frequentemente inclui uma virgula final. Os dicionarios do Python 3.7+ tambem permitem. A especificacao JSON RFC 8259 secao 5 estabelece claramente “trailing commas are not allowed”. O JSON.parse ingenuo segue estritamente a especificacao, ve {"a": 1,} e reporta erro.

Correcao: O JSON de producao nao deve ter virgulas finais. No desenvolvimento voce pode usar a opcao “parse tolerante” da ferramenta (Formatador JSON Piick suporta estilo JSON5, aceitando virgula final + aspas simples + comentarios), mas deve passar por lint antes de commit em arquivos de API / configuracao. CI executa prettier --check ou eslint --rule no-trailing-commas como rede de seguranca.

Cenario real: Frontend faz fetch a API do backend, Chrome DevTools “Copy as fetch”, cola em jq .response.users[0].id, falha. Motivo: a saida do DevTools tem virgula final, jq e parse estrito. Sempre lint antes de jq, ou use diretamente o modo tolerante de jq jq -R ..

Erro 2: Caracteres Unicode Sem Escape

Sintoma: O backend retorna {"name":"张三"}, o frontend JSON.parse funciona bem. Mas as vezes os mesmos dados colados em uma ferramenta reportam “Unexpected token”, ou algumas bibliotecas ao fazer stringify tem o chines convertido para ?. Isso e escape Unicode inconsistente.

Por que: A especificacao JSON estabelece caracteres nao-ASCII em strings podem aparecer diretamente como UTF-8 (porque o documento JSON em si requer UTF-8), e tambem podem ser escapados como \uXXXX. Ambos formatos sao legais. Mas o comportamento padrao de algumas bibliotecas difere:

  • Python json.dumps padrao ensure_ascii=True, escapando todo nao-ASCII para \uXXXX
  • JavaScript JSON.stringify padrao preserva o Unicode original
  • Java ObjectMapper padrao escapa
  • Go encoding/json padrao escapa

O backend em Python produz {"name":"\u5f20\u4e09"}, o frontend em JS parseia para 张三, mas se voce copia a resposta crua do backend para vim para compartilhar com um colega, o colega ve {"name":"\u5f20\u4e09"} confuso. Esta e a inconsistencia entre UTF-8 e escape \u.

Correcao: Garanta sempre que o JSON de producao seja UTF-8. O backend em Python usa json.dumps(..., ensure_ascii=False) para formato legivel (com Content-Type: application/json; charset=utf-8). Ao depurar, use o parse tolerante da ferramenta, tratando \uXXXX como entrada legal.

Cenario real: O backend em Python faz dump {"msg":"\u4f60\u597d"}, o frontend fetch e response.json() obtem {msg:"你好"}, correto. Mas se voce copia a resposta crua do backend para vim, da para um colega, o colega ve {"msg":"\u4f60\u597d"} confuso. Esta e a inconsistencia entre UTF-8 e escape \u.

Erro 3: Perda de Precisao em Inteiros Grandes (Ultimos Bits do Snowflake ID se Tornam 0)

Sintoma: O backend retorna {"user_id": 1234567890123456789}, o frontend JSON.parse faz user_id ser 1234567890123456800, os ultimos 3 digitos sao todos 0. O ID do backend esta correto, o ID extraido pelo frontend esta errado, a consulta ao banco de dados da 404.

Por que: O Number do JavaScript e IEEE 754 de dupla precisao, o intervalo de inteiros seguros e 2^53 − 1 = 9007199254740991 (aproximadamente 9 × 10^15). Inteiros que excedem este intervalo perdem precisao. O Snowflake ID e um inteiro de 19 digitos (aproximadamente 10^18), JSON.parse perde precisao diretamente. O int do Python / long do Java nao tem este problema, mas JS e a linguagem frontend mais comum.

Correcao:

  • Backend: serialize bigint como string ("1234567890123456789"), nao numero
  • Frontend: use a biblioteca json-bigint ao parsear, ou trate tudo como strings
  • Visualizacao: ao exibir UI, BigInt(id).toString(), ao calcular use tipo bigint
  • Design de API: ao retornar ID, considere diretamente UUID (36 chars) ou ULID (26 chars), ambos formato string

Ao validar resposta de API com o Formatador JSON Piick, primeiro verifique o placeholder, cole e verifique se a saida coincide; se o comprimento do ID > 15 digitos, alerta para problemas de precisao em inteiros grandes.

Cenario real: O Snowflake ID do Twitter e um inteiro de 64 bits, aproximadamente 1770000000000000000, muito acima de 2^53. O frontend faz fetch do tweet id 1234567890123456789, na verdade obtem 1234567890123458000, nao encontra. O Snowflake ID deve ser serializado como string.

Erro 4: Indentacao != Estrutura de Aninhamento

Sintoma: Seu codigo usa indentacao de 2 espacos, o do seu colega usa 4 espacos, a revisao do PR parece JSON completamente diferente, mas o resultado do parse e exatamente o mesmo. Voce pensa que e profundidade de aninhamento diferente, na verdade {"a":{"b":{"c":1}}} e {"a": { "b": { "c": 1 } }} sao o mesmo objeto.

Por que: A sintaxe JSON nao se importa com espacos em branco, desde que as regras lexicas de RFC 8259 sejam atendidas, qualquer numero de espacos / tabs / quebras de linha e equivalente. A indentacao e apenas “legibilidade para o olho humano”, nao tem nada a ver com o aninhamento real. Esta e tambem a razao pela qual os arquivos JSON em git diff parecem que tudo mudou quando voce adiciona/remove um unico campo (porque a indentacao e reordenada).

Correcao: Unifique o estilo de indentacao (recomenda 2 espacos, economiza largura de linha) + use prettier / jq para auto-formatacao, evite formatacao manual. Use a opcao “indent” da ferramenta (Formatador JSON Piick suporta 2 espacos / 4 espacos / tab / minify), equipe unificada.

Cenario real: Configuracao JSON com 100 campos, 2 espacos vs 4 espacos:

  • 2 espacos: {"a":1,"b":2,"c":{"d":3}} compacto
  • 4 espacos: {"a": 1, "b": 2, "c": { "d": 3 }} amplo

5+ niveis de aninhamento, 4 espacos por nivel, 5 niveis = 20 caracteres de margem esquerda, tela de 80 caracteres so tem 60 caracteres de conteudo. 2 espacos melhor para aninhamento profundo.

Erro 5: Caracteres BOM Ignorados

Sintoma: O arquivo JSON parece normal no VSCode, cole na ferramenta / Node.js JSON.parse reporta erro “Unexpected token”. Clique direito → Ver Codificacao → UTF-8 with BOM. Motivo: o arquivo tem um caractere invisivel \ufeff (BOM, byte order mark) no inicio.

Por que: Windows Notepad / alguns editores antigos salvam arquivos UTF-8 com BOM por padrao (3 bytes EF BB BF). JS / Python / a maioria dos parsers JSON veem \ufeff como token JSON e reportam erro. A especificacao JSON nao permite BOM no texto JSON (exceto dentro de strings do documento JSON, como caractere de escape).

Correcao:

  • Salvar sem BOM: VSCode canto inferior direito → UTF-8 with BOM → UTF-8 (padrao)
  • Transcoding por linha de comando: sed '1s/^\xef\xbb\xbf//' input.json > output.json
  • Leitura em Python: use encoding='utf-8-sig' para auto-remover
  • Node.js: use fs.readFileSync(path, 'utf-8').replace(/^\ufeff/, '')

Ao usar o Formatador JSON Piick, colar JSON com BOM reporta “Unexpected token”, remova manualmente o BOM ou use sed para pre-processar.

Cenario real: Um colega no Windows escreve configuracao JSON → salva → commit → CI executa JSON.parse → falha. CI nao remove BOM automaticamente, precisa mudar a configuracao do editor na fonte. Adicione insert_final_newline = true e “encoding UTF-8 sem BOM” no .editorconfig, equipe unificada.

Erro 6: Aspas Simples Tratadas como JSON

Sintoma: O dict do Python {'a': 1, 'b': 2} diretamente colado no formatador JSON reporta erro. A saida padrao do dict do Python se parece com JSON, mas usa aspas simples, que nao e JSON legal.

Por que: A especificacao JSON estabelece claramente strings devem usar aspas duplas, aspas simples nao funcionam. O repr() do dict do Python produz aspas simples, a saida de string JSON produz aspas duplas:

Iniciantes facilmente tratam print(d) como JSON, colam na ferramenta e reportam erro.

Correcao:

  • Ao depurar Python, use print(json.dumps(d, indent=2)) em vez de print(d)
  • A opcao “parse tolerante” da ferramenta aceita aspas simples (Formatador JSON Piick suporta estilo JSON5)
  • Eduque a equipe “Python dict != JSON, Python str usa aspas simples, JSON usa aspas duplas”

Cenario real: Um iniciante em Python depurando resposta de API, print(response) produz {'code': 200, 'msg': 'ok'}, pensa que e JSON, copia para um colega do backend, o JSON.parse do colega falha. Primeira armadilha de depuracao do iniciante.

Erro 7: Serializacao de NaN / Infinity / undefined

Sintoma: O objeto JS {a: NaN, b: Infinity, c: undefined} serializado com JSON.stringify se torna {"a":null,"b":null} (NaN e Infinity se tornam null), os campos undefined desaparecem diretamente. Se o backend usa um parser JSON estrito (por exemplo, Python json.dumps depois json.loads), o comportamento difere: json.dumps do Python serializa float('nan') como NaN (nao padrao), json.loads('NaN') reporta erro.

Por que: A especificacao JSON nao permite NaN / Infinity / undefined, mas JS e a linguagem de uso diario para estes:

  • NaN / Infinity: sao constantes globais do JS, produzidas em erros de calculo numerico
  • undefined: sinalizador do JS “variavel nao definida”
  • JSON.stringify: trata todos como null (undefined descarta campos diretamente)
  • JSON.parse('NaN'): JS e permissivo, aceita como NaN (nao padrao)
  • json.dumps(float('nan')): Python produz NaN (nao padrao)
  • json.loads('NaN'): Python por padrao e estrito, reporta erro

Ao trocar dados entre linguagens, o comportamento de serializacao de NaN / Infinity / undefined e inconsistente, bugs sao faceis.

Correcao:

  • Especificacao de API: nunca use NaN / Infinity, use null ou omita para valores invalidos
  • Limpeza de dados: antes de serializar, manualmente if (x === undefined || Number.isNaN(x)) x = null
  • Validacao estrita do backend: Python json.dumps(..., allow_nan=False), fail-fast em erro
  • Biblioteca: validacao JSON Schema na entrada da API, rejeitar NaN / Infinity

Ao usar o Formatador JSON Piick, colar JSON com NaN / Infinity reporta “Unexpected token n” (porque NaN nao e um token legal), substitua manualmente por null.

Cenario real: Frontend faz fetch a API do backend, resposta {score: NaN} (bug do backend), frontend JSON.parse obtem score: NaN, consulta SQL WHERE score > 0 nao retorna linhas (NaN > 0 e false), UI mostra “sem dados”, depurando meio dia para descobrir que e NaN. Nunca passe NaN, o backend faz validacao defensiva.

Erro 8: Ordenar Chaves Altera Git Diff / Semantica da Linguagem

Sintoma: Voce ativa a opcao “sort keys” da ferramenta, o JSON fica ordenado, depois de git commit os colegas na revisao veem 100 linhas de diff, todas sao mudancas de ordem de campos, sem mudanca real de conteudo. Ou mais serio: Go map / Python 3.7+ dict em alguns casos limite sao sensiveis a ordem de chaves, a semantica muda depois de ordenar.

Por que: O objeto JSON e um mapa nao ordenado por definicao da especificacao, mas RFC 8259 na verdade permite que as implementacoes preservem a ordem (porque os literais de objeto JS, os dict do Python 3.7+ sao ordenados). A opcao sort keys da ferramenta e para mostrar ordem, mas:

  1. Ruido no Git diff, afeta a qualidade da revisao
  2. Protocolos JSON Canonicalization Scheme sensiveis a ordem de chaves falham
  3. O Object.keys(obj) de algumas bibliotecas depende da ordem de insercao, depois de ordenar a ordem de forEach muda

Correcao: O JSON de producao nao ordena chaves automaticamente. Durante o desenvolvimento use a ferramenta para ver a estrutura, antes do commit use jq ou prettier para reformatar (preserva a ordem original). Se a equipe realmente precisa de uma ordem unificada, use lint para forcar (sort-package-json para package.json), nao confie na ordenacao em tempo de execucao da ferramenta.

Ao usar o Formatador JSON Piick, sort keys desativado por padrao, so ative manualmente quando “quero ver a estrutura”.

Cenario real: Um colega ativa sort keys, faz commit de 1000 linhas de package.json todas reordenadas, o revisor olha o diff e ve 800 linhas sao mudancas de ordem, 200 linhas sao dependencias novas, 2 horas de revisao desperdiçadas. Nao use sort keys em configuracao de producao.

Decisoes de Selecao de Ferramenta

Opcao A: Formatacao Integrada na IDE (VSCode / WebStorm)

Melhor para: Escrever JSON diariamente, ja usa uma IDE.

Vantagens: Formatacao em tempo real, sem sair do editor, integra com schema (auto-completar chaves). Desvantagens: Apenas JSON local, nao sincroniza entre ferramentas (o formato da IDE difere do formato do jq), sem processamento em lote (auto-formato em CI requer setup separado).

Opcao B: Ferramentas de Linha de Comando (jq / python -m json.tool)

Melhor para: Auto-formatacao em CI / pipeline de build, projetos com ambiente shell.

Vantagens: Scriptavel, em lote, combinado com lint, integracao CI. Desvantagens: Nao intuitivo (saida de texto sem cores), sem destaque de sintaxe, sem parse tolerante (JSON5 / aspas simples / comentarios).

Opcao C: Formatador JSON Piick

Melhor para: Depuracao cross-ferramenta (resposta API + arquivo de configuracao + payload JWT), nao quer pacote npm extra (projeto puramente frontend), dados sensiveis (configuracao API de producao / JSON com PII) nao quer passar por nenhum servidor de terceiros.

Vantagens: Zero dependencia (frontend puro JSON.parse + tokenizer), destaque de sintaxe + ordenar chaves + parse tolerante (JSON5 / aspas simples / comentarios) + clique-para-pular para posicao de erro + 5 metricas (chaves / arrays / profundidade maxima de aninhamento / bytes), dados locais. Desvantagens: Nao integra em CI (use Opcao B para complementar), nao pode auto-salvar (ferramenta puramente frontend).

Arvore de decisao:

  • Ja escreve JSON → Opcao A (plugin IDE)
  • Integracao CI + ambiente shell → Opcao B (jq)
  • Depuracao cross-ferramenta + dados sensiveis + nao instala nada → Opcao C (Piick)

5 Cenarios Reais

Cenario 1: Depuracao de Resposta de API

Frontend chama a API do backend, a resposta e JSON minificado comprimido, cole na ferramenta para auto-embelezar + dobrar / expandir + + mostrar estatisticas (chaves / arrays / profundidade).

Passos:

  1. fetch API → response.text() → cole no Formatador JSON Piick
  2. Auto destaque de sintaxe (5 tipos de token)
  3. Ver estatisticas acima: {keys: 47, arrays: 12, maxDepth: 4, bytes: 1024}
  4. Clique-para-pular para posicao de erro: JSON.parse falha, clique no banner de erro, pula para a posicao do caractere que falha
  5. Copiar resultado formatado / dobrar niveis de aninhamento

Sugestao real: Sempre use a ferramenta para ver a resposta da API, nao veja diretamente JSON minificado em console.log, o olho humano nao consegue ler.

Cenario 2: Validacao de package.json / Arquivos de Configuracao

Ao escrever package.json, typo (virgula extra / falta colchete direito / string sem fechar), CI npm install falha, mas o editor nao falha (IDE tolerante). Execute validacao com ferramenta.

Passos:

  1. Copiar conteudo de package.json → cole na ferramenta
  2. A ferramenta reporta erro → ver “Line X, column Y” posicao de erro → clique-para-pular → corrigir
  3. Especialmente verificar: "scripts", "dependencies", "devDependencies" tres lugares (mais provavel de typo)
  4. Antes do commit execute npm install --dry-run para dupla confirmacao

Sugestao real: Use a opcao “parse tolerante” do Formatador JSON Piick (tolerant) para ver “erro de sintaxe mas perto de correto” durante desenvolvimento, mais amigavel que o parser estrito.

Cenario 3: Decodificacao de Payload JWT

JWT e JSON codificado em base64url, tres partes header.payload.signature. Ao decodificar o payload para ver os claims, primeiro use o Decodificador JWT Piick (mesmo cluster doc) para dividir o base64, depois use o Formatador JSON para verificar se o JSON decodificado e legal.

Passos:

  1. JWT eyJhbG...sw5c
  2. Decodificador JWT Piick divide tres partes
  3. o payload e {"sub":"1234567890","name":"John Doe","iat":1516239022} ← JSON minificado
  4. Cole no Formatador JSON Piick embelezar + ver campos de timestamp (iat / exp / nbf para tempo legivel)
  5. Verificar se exp expirou

Sugestao real: Cadeia de depuracao JWT: Decodificador JWT → Formatador JSON → Conversor de Unix Timestamp (mesmo cluster doc), conjunto de 3 pecas cobre o fluxo completo.

Cenario 4: Serializacao de Snowflake ID / ID de Inteiro Grande

O backend usa int64 para retornar ID, o frontend faz fetch e id.toString() os ultimos bits se tornam 0. Tratamento de string.

Passos:

  1. Backend Python json.dumps({"id": int(2**60)}) → saida {"id": 1152921504606846976} ← os ultimos bits podem perder precisao
  2. Correcao: backend json.dumps({"id": str(2**60)}) → saida {"id": "1152921504606846976"} ← string, frontend trata como string
  3. Frontend BigInt(id).toString() para operacoes matematicas
  4. UI mostra id.slice(0, 4) + "..." + id.slice(-4) (como visualizacao de numero de cartao bancario)

Sugestao real: Especificacao de API: IDs de inteiros grandes sempre usam string. Frontend nunca assume que ID e Number.

Cenario 5: Arquivos de Recursos i18n / Dicionarios Multilingues

Arquivos JSON de i18n contem chines / japones / emoji, trata corretamente o escape Unicode. Desenvolvimento usa a ferramenta para visualizacao, producao usa UTF-8 + saida de formato legivel ensure_ascii=False.

Passos:

  1. Arquivo i18n zh.json: {"hello":"你好,世界!🌏"} ← UTF-8 direto
  2. Cole no Formatador JSON Piick verifica que os caracteres UTF-8 se mostrem normalmente
  3. Saida do backend usa json.dumps(..., ensure_ascii=False) (Python) ou JSON.stringify (JS padrao)
  4. Cabecalho de resposta: Content-Type: application/json; charset=utf-8
  5. CI adiciona lint: eslint-plugin-unicorn ou script personalizado verifica a configuracao ensure_ascii

Sugestao real: Nunca escreva escape \uXXXX em strings JSON, durante o desenvolvimento escreva diretamente caracteres legiveis com UTF-8. Durante producao deixe o framework / biblioteca decide como serializar, configure voce mesmo ensure_ascii=False.

Praticas Recomendadas

  • Sempre valide JSON com ferramenta (especialmente a configuracao de API de producao), nao confie na tolerancia da IDE
  • Sempre parse tolerante durante desenvolvimento (modo tolerante da ferramenta), producao lint sem virgula final + sem comentarios + sem aspas simples
  • IDs de inteiros grandes sempre serialize como string (Snowflake ID / chave primaria distribuida), nao assuma que o Number do frontend e seguro
  • Nao ordene chaves automaticamente (afeta Git diff e linguagens sensiveis a ordem de chaves), so ative manualmente quando “vejo estrutura”
  • Unifique a indentacao (recomenda 2 espacos) + use prettier / jq para auto-formatacao, evite a formatacao manual
  • Sempre use UTF-8 + Content-Type charset=utf-8, nao use escape \uXXXX (legibilidade de desenvolvimento pobre)
  • CI executa validacao JSON Schema, na entrada da API rejeita NaN / Infinity / falta de campos em modo estrito
  • Editor de Windows fecha BOM, .editorconfig equipe unificada, evita que o caractere BOM falhe em CI
  • Use o Formatador JSON Piick online para formatar / validar / embelezar, destaque de sintaxe + parse tolerante + clique-para-pular para posicao de erro + 5 metricas + dados locais sem envio. Combina com o Decodificador JWT Piick para dividir base64, Formatador SQL Piick para formatar SQL, Codificador/Decodificador de URL Piick para lidar com parametros URL, Gerador de Cron Piick para gerar expressoes cron, Testador de Regex Piick para testar regex de valores de campos JSON — conjunto de 5 pecas cobre todos os cenarios dev de JSON upstream / downstream

A formatacao JSON nao e embelezamento, e infraestrutura de legibilidade para API / configuracao / logs. O verdadeiro “formato correto” = JSON padrao + UTF-8 + inteiros grandes como strings + sem ordenar + sem virgula final + equipe com indentacao unificada. Salve nos os o Formatador JSON Piick — ao depurar API / validar configuracao / parsear payload JWT, abra-o, 1 minuto, eficiencia diaria de desenvolvimento +30%.