Resposta rápida
- No navegador: cole no JSON Formatter do FormatArc — roda totalmente no lado do cliente, sem upload
- No terminal:
echo '{...}' | jq .oupython3 -m json.tool - No código:
JSON.stringify(data, null, 2)em JavaScript/Node.js
O restante deste guia cobre esses três caminhos com exemplos, erros comuns de parsing e quando escolher cada um.
O que é formatação de JSON?
JSON (JavaScript Object Notation) é um dos formatos de dados mais usados. Você o encontra em respostas de API, arquivos de configuração e na troca de dados entre serviços.
No entanto, o JSON minificado é difícil de ler para humanos, então formatá-lo de maneira legível para revelar a estrutura é uma tarefa rotineira para desenvolvedores.
Erros comuns de sintaxe em JSON
A gramática do JSON é definida por duas especificações oficiais: RFC 8259Abre em uma nova aba (o padrão da IETF, "The JavaScript Object Notation (JSON) Data Interchange Format") e ECMA-404Abre em uma nova aba (o padrão da ECMA, "The JSON Data Interchange Syntax"). Ambas definem a mesma sintaxe, então as regras a seguir não são peculiaridades do formatador: elas vêm diretamente da especificação.
1. Vírgulas sobrando no final
{
"name": "example",
"value": 42,
}
Uma vírgula depois da última propriedade é JSON inválido. O JavaScript permite isso, mas a especificação do JSON não.
2. Aspas simples
{'name': 'example'}
JSON exige aspas duplas ". Aspas simples ' não são válidas.
3. Chaves sem aspas
{name: "example"}
Toda chave em JSON precisa estar entre aspas duplas.
Tabela de correção de erros de sintaxe em JSON
A tabela abaixo relaciona os erros de sintaxe mais comuns com a correção exigida pela RFC 8259 / ECMA-404.
| Erro | Exemplo inválido | Correção |
|---|---|---|
| Vírgula no final | {"a": 1,} | Remova a vírgula após o último valor: {"a": 1} |
| Aspas simples | {'a': 'b'} | Use aspas duplas: {"a": "b"} |
| Chaves sem aspas | {a: 1} | Coloque cada chave entre aspas duplas: {"a": 1} |
| Comentários | {"a": 1} // note | JSON não tem sintaxe de comentário; remova o comentário |
| Zero à esquerda | {"a": 01} | Números não podem ter zero à esquerda: {"a": 1} |
| Sinal de mais em número | {"a": +1} | Remova o + inicial: {"a": 1} |
| Número hexadecimal / octal | {"a": 0x1F} | Apenas a notação decimal é permitida: {"a": 31} |
NaN / Infinity | {"a": NaN} | Não são valores JSON válidos; use um número ou null |
| Valor undefined | {"a": undefined} | undefined não é um valor JSON; use null |
| Caractere de controle sem escape | quebra de linha dentro de "..." | Faça o escape como \n dentro da string |
| Barra invertida sem escape | {"a": "C:\path"} | Faça o escape da barra invertida: {"a": "C:\\path"} |
| Propriedade com aspas simples | {"key": 'value'} | Valores de string também exigem aspas duplas: {"key": "value"} |
Formate JSON com JSON.stringify()
Em JavaScript e Node.js, JSON.stringify() aceita um terceiro argumento para indentação. Essa é a forma mais rápida de formatar JSON no código:
const data = { name: "Alice", age: 30, roles: ["admin", "editor"] };
// Pretty-print with 2-space indent
console.log(JSON.stringify(data, null, 2));
Saída:
{
"name": "Alice",
"age": 30,
"roles": [
"admin",
"editor"
]
}
O segundo argumento (null aqui) é uma função ou um array replacer que filtra quais propriedades incluir. Passe null para manter tudo.
Você também pode usar um caractere de tabulação para a indentação:
JSON.stringify(data, null, "\t");
As armadilhas mais comuns do pretty-print em JavaScript
JSON.stringify() é a ferramenta certa para o caso simples, mas alguns padrões costumam quebrá-la em código de produção. As correções são curtas e vale a pena conhecê-las antes de precisar depurá-las às 2 da manhã.
Referências circulares
Se algum objeto alcançável a partir da sua entrada contém uma referência de volta a si mesmo, JSON.stringify lança TypeError: Converting circular structure to JSON. A correção padrão é passar uma função replacer que rastreia os objetos já serializados e substitui as repetições:
function safeStringify(value, space = 2) {
const ancestors = [];
return JSON.stringify(value, function (_key, val) {
if (typeof val !== "object" || val === null) return val;
while (ancestors.length && ancestors[ancestors.length - 1] !== this) {
ancestors.pop();
}
if (ancestors.includes(val)) return "[Circular]";
ancestors.push(val);
return val;
}, space);
}
Esse é o erro em tempo de execução mais comum ao formatar uma árvore no estilo DOM já parseada, um grafo de uma biblioteca de gerenciamento de estado, ou o payload de um logger que referencia de novo o objeto da requisição.
Personalizando a saída com toJSON()
JSON.stringify verifica se cada valor tem um método toJSON() e usa o retorno dele quando existe. Date já implementa isso (você recebe uma string ISO 8601), mas você pode fazer o mesmo nas suas próprias classes:
class Money {
constructor(amount, currency) {
this.amount = amount;
this.currency = currency;
}
toJSON() {
return `${this.amount.toFixed(2)} ${this.currency}`;
}
}
JSON.stringify({ price: new Money(19.9, "USD") }, null, 2);
// → { "price": "19.90 USD" }
Essa abordagem é mais limpa do que rodar uma etapa de transformação antes da serialização, e a indentação do pretty-print continua funcionando normalmente.
Filtrando ou mascarando chaves com um replacer
Além de detectar referências circulares, o argumento replacer também pode descartar entradas, útil para mascarar segredos ou remover ruído de uma resposta de API antes de registrá-la em log:
const redactKeys = new Set(["password", "apiKey", "authorization"]);
JSON.stringify(response, (key, value) => redactKeys.has(key) ? undefined : value, 2);
Você também pode passar um array com as chaves que quer manter, em vez de uma função:
JSON.stringify(user, ["id", "email", "createdAt"], 2);
Quando usar prettier e quando usar JSON.stringify
O CLI prettier é um formatador de código multi-linguagem (TypeScript, CSS, Markdown, JSON e outros). Para um arquivo .json em um projeto que já usa o Prettier, rode prettier --write file.json para que o arquivo seja reformatado dentro do que a sintaxe JSON permite: o espaçamento e a indentação seguem a configuração do projeto, mas as chaves continuam entre aspas duplas e sem vírgula final, porque é só isso que o JSON padrão permite.
Para um pretty-print pontual, uma saída de debug, a resposta de uma API que você acabou de colar, um valor que quer inspecionar rapidamente, JSON.stringify(data, null, 2) ou o JSON Formatter do FormatArc são mais rápidos e não exigem instalar nada. O Prettier é a escolha certa quando você quer consistência em todo um projeto; JSON.stringify e uma ferramenta de navegador são a escolha certa quando você quer um resultado pontual agora.
Formate JSON no terminal
Usando jq
jq é um processador de JSON leve para a linha de comando. Encaminhe qualquer saída JSON por ele para obter resultados formatados:
echo '{"name":"Alice","age":30}' | jq .
Usando Python
O Python vem com um módulo JSON embutido que funciona como um formatador rápido:
echo '{"name":"Alice","age":30}' | python3 -m json.tool
Usando curl com jq
Ao depurar APIs, combine curl com jq para formatar a resposta:
curl -s https://api.example.com/data | jq .
Formate JSON no seu navegador
O JSON Formatter do FormatArc permite formatar JSON inteiramente no navegador. Seus dados nunca são enviados a um servidor, o que torna o processo seguro para payloads de API e configurações internas.
Como usar
- Cole seu JSON na área de entrada
- Clique em "Run"
- Copie a saída formatada
Três passos simples para um JSON limpo e legível.
Valide o JSON antes de formatar
Se o seu JSON estiver malformado, a formatação vai falhar. As causas mais comuns são vírgulas sobrando no final, aspas simples e chaves sem aspas (vistas acima). Se você precisa de comentários nos seus arquivos de configuração, veja JSONC, JSON5 e outras alternativas. Quando você se depara com um erro de parsing, a mensagem de erro geralmente inclui uma posição de caractere — mas isso pode ser difícil de mapear para o problema real em um arquivo grande.
O JSON Formatter do FormatArc mostra o número aproximado da linha onde o erro ocorreu, facilitando ir direto ao ponto certo. Para um passo a passo mais aprofundado sobre erros comuns de parsing e como corrigi-los, veja Como Corrigir Erros de Parsing em JSON.
Formate JSON automaticamente com uma extensão do Chrome
Se você costuma abrir endpoints de API diretamente no navegador, uma extensão do Chrome pode formatar a resposta automaticamente para você. Veja As Melhores Extensões de JSON Formatter para Chrome Comparadas para uma análise do JSONView, do JSON Formatter e de outras opções populares.
Trabalhando com outros formatos de dados
A formatação de JSON costuma fazer parte de um fluxo de trabalho maior que envolve conversão entre formatos:
- YAML vs JSON — entenda quando usar cada formato
- Converter YAML para JSON — transforme configs do Kubernetes e arquivos de CI em JSON
- Converter CSV para JSON — transforme exportações de planilhas em arrays JSON
- Guia de Sintaxe JSON — os fundamentos para escrever JSON válido
- Usando o formatarc como pacote npm — formate JSON pelo terminal com a CLI do formatarc
- Formatar Respostas JSON do curl — formate respostas de API diretamente do curl com one-liners de jq ou python
Experimente agora
Tem um JSON bagunçado que precisa ser formatado? Abra o JSON Formatter, cole seus dados e obtenha uma saída limpa na hora. Sem cadastro, sem servidor — tudo permanece no seu navegador.
Resumo
- Formatar JSON de forma legível é uma tarefa do dia a dia em desenvolvimento e operações
- Use
JSON.stringify(data, null, 2)para formatar JSON em JavaScript - No terminal, encaminhe o JSON por
jqoupython3 -m json.tool - Os erros de sintaxe mais comuns são vírgulas sobrando no final, aspas simples e chaves sem aspas
- O FormatArc formata JSON com segurança no navegador, sem nenhum servidor envolvido