How to Format JSON: Methods, Tools & Best Practices

Por que a Formatação de JSON é Importante

JSON não formatado é tecnicamente válido, mas é hostil para os humanos. Um bloco de linha única de objetos e arrays aninhados é quase impossível de escanear durante uma sessão de depuração, e transforma revisões de código em jogos de adivinhação.

JSON formatado corretamente oferece três benefícios imediatos: legibilidade — você pode rastrear visualmente a hierarquia de chaves e valores; depuração — ferramentas de diff e mensagens de erro referenciam números de linha que realmente significam algo; e colaboração — colegas de equipe que revisam suas respostas de API ou arquivos de configuração podem entendê-los rapidamente.

A formatação também previne bugs sutis. Quando o JSON é minificado, é fácil perder um colchete deslocado ou uma chave duplicada. Expandir a estrutura faz com que esses problemas se destaquem.

As Regras da Formatação de JSON

Antes de pegar uma ferramenta, é útil entender o que "JSON formatado" realmente significa. A especificação JSON (RFC 8259) não exige nenhuma regra de espaço em branco — a formatação é puramente uma questão de apresentação. Dito isso, a comunidade estabeleceu convenções claras:

• Cada par chave-valor fica em sua própria linha.
• Objetos e arrays aninhados são indentados um nível mais profundo que seu pai.
• Um dois-pontos segue a chave, separado por um único espaço: “chave”: “valor”.
• As vírgulas aparecem no final de cada linha (não no início).
• Chaves e colchetes de abertura ficam na mesma linha que a chave; os de fechamento se alinham com o nível de indentação do pai.

Aqui está um exemplo mínimo. Este JSON minificado:

{"name":"Alice","age":30,"roles":["admin","editor"],"address":{"city":"Portland","state":"OR"}}

Torna-se isto quando formatado com indentação de 2 espaços:

{
  "name": "Alice",
  "age": 30,
  "roles": [
    "admin",
    "editor"
  ],
  "address": {
    "city": "Portland",
    "state": "OR"
  }
}

As 3 Maneiras de Formatar JSON

Cada abordagem se encaixa em um dos três grupos: ferramentas online, utilitários de linha de comando ou formatação programática dentro do código da sua aplicação. A escolha certa depende de onde você está em seu fluxo de trabalho e com que frequência precisa fazer isso.

1. Ferramentas Online

Formatadores baseados em navegador são o caminho mais rápido quando você só precisa formatar um payload uma única vez — cole, clique em um botão, copie o resultado. Não há nada para instalar e nenhuma troca de contexto para um terminal.

Ferramentas online funcionam bem para depuração rápida, compartilhamento de trechos formatados com partes interessadas não técnicas, ou quando você está em uma máquina onde não pode instalar software. A desvantagem é que elas não se integram em pipelines automatizados.

Experimente você mesmo: Cole qualquer JSON em nosso Formatador de JSON para instantaneamente embelezá-lo com sua escolha de indentação.

2. Ferramentas de Linha de Comando

Se você vive no terminal, dois comandos cobrem quase todas as necessidades de formatação:

Módulo json.tool embutido do Python — disponível em qualquer máquina com Python instalado, sem pacotes extras necessários:

echo '{"name":"Alice","age":30}' | python -m json.tool

Isso gera JSON bem indentado no stdout. Você pode passar um arquivo por ele tão facilmente:

python -m json.tool data.json > data-formatado.json

jq — um processador JSON leve e feito sob medida. O comando de formatação mais simples é apenas o filtro de identidade:

cat data.json | jq '.'

jq também adiciona destaque de sintaxe na maioria dos terminais, e você pode encadear filtros para transformar e formatar em uma única passagem. É a escolha preferida para scripts de shell que processam JSON.

Ambos os comandos podem ser encadeados em pipelines de CI. Por exemplo, você pode executar jq --sort-keys . em um hook de pré-commit para garantir que todos os arquivos de configuração JSON em um repositório estejam formatados de maneira consistente.

3. Formatação Programática

Quando você está escrevendo código de aplicação, formatar JSON é uma linha de código na maioria das linguagens.

JavaScript / TypeScript:

const formatted = JSON.stringify(data, null, 2);

O terceiro argumento para JSON.stringify controla a indentação. Passe 2 para 2 espaços, 4 para 4 espaços, ou "\t" para tabs.

Python:

import json

formatted = json.dumps(data, indent=2, ensure_ascii=False)

Go:

formatted, err := json.MarshalIndent(data, "", "  ")

A formatação programática é essencial quando você gera JSON como parte de sua aplicação — escrevendo arquivos de configuração, criando fixtures de resposta da API ou gerando documentação. Você controla completamente a saída.

Comparando Abordagens de Formatação

Aqui está uma referência rápida para ajudá-lo a escolher o método certo para a situação:

Critério	Ferramenta Online	CLI (jq / json.tool)	Programática
Facilidade de uso	Cole e clique	Comando de uma linha	Requer contexto de código
Velocidade para tarefas únicas	Mais rápida	Rápida	Mais lenta (precisa de um script)
Automação / CI	Não adequado	Excelente	Excelente
Personalização	Limitada	Moderada (flags)	Controle total
Funciona offline	Não	Sim	Sim
Lida com arquivos grandes	Limites do navegador	Funciona bem	Depende da implementação

O Debate da Indentação: 2 Espaços vs 4 Espaços vs Tabs

Este é um daqueles debates que gera mais calor do que luz, mas há razões práticas para preferir cada opção.

2 Espaços

A escolha mais comum em JSON. Mantém estruturas profundamente aninhadas compactas, enquanto ainda fornece uma hierarquia visual clara. A maioria das ferramentas do ecossistema JavaScript (ESLint, Prettier, package.json do npm) usa 2 espaços como padrão. Se você está trabalhando com APIs web ou projetos Node.js, este é o padrão seguro.

4 Espaços

Popular em fluxos de trabalho adjacentes ao Python e em algumas empresas que usam Java. A largura extra torna os níveis de aninhamento mais óbvios, o que pode ajudar ao ler grandes arquivos de configuração. O trade-off é que JSON profundamente aninhado rapidamente empurra para a borda direita da tela.

Tabs

Tabs permitem que cada desenvolvedor defina sua própria largura visual em seu editor. Isso soa ideal em teoria, mas na prática a maioria das ferramentas e linters de JSON espera espaços. Tabs também são renderizados de forma inconsistente em visualizadores de diff baseados na web e PRs do GitHub.

Quando usar cada um:

• 2 espaços — projetos web, bases de código JavaScript/TypeScript, payloads de API. O padrão da comunidade.
• 4 espaços — equipes pesadas em Python, grandes arquivos de configuração onde a clareza vence a compactação.
• Tabs — monorepos com preferências de linguagem mistas e requisitos de acessibilidade rigorosos (tabs permitem larguras configuradas pelo usuário).

A coisa mais importante é a consistência dentro de um projeto. Escolha um e faça valer.

Ordenando Chaves

A maioria dos formatadores oferece uma opção de "ordenar chaves" que alfabetiza as chaves dos objetos. Isso não é apenas cosmético — tem benefícios reais para o controle de versão.

Quando as chaves são ordenadas, os diffs se tornam significativos. Sem a ordenação, dois desenvolvedores podem adicionar as mesmas chaves em ordens diferentes, produzindo diffs barulhentos que obscurecem a mudança real. Chaves ordenadas eliminam isso completamente.

Chaves ordenadas também facilitam a varredura de grandes arquivos de configuração. Se você sabe a chave que está procurando, pode pular para sua posição alfabética sem precisar procurar.

A única ressalva: alguns arquivos JSON têm uma ordem de chave intencional (como um package.json onde name e version vêm primeiro por convenção). Nesses casos, preserve a ordem original.

Em jq, ordene as chaves com:

jq --sort-keys '.' data.json

Em JavaScript, passe uma função substituta ou use uma biblioteca como json-stable-stringify para uma ordem de chave determinística.

Auto-Formatar ao Salvar no VS Code

A melhor formatação é aquela da qual você nunca pensa. O VS Code pode formatar automaticamente arquivos JSON toda vez que você salva. Veja como configurá-lo:

Passo 1: Abra suas configurações (Cmd+, no macOS, Ctrl+, no Windows/Linux) e adicione estas entradas:

{
  "editor.formatOnSave": true,
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "editor.tabSize": 2
  }
}

Passo 2: Instale a extensão Prettier - Code formatter se ainda não o fez. Ela lida com a formatação de JSON junto com todas as outras linguagens em seu projeto.

Passo 3: Crie um arquivo .prettierrc na raiz do seu projeto para padronizar as configurações em toda a equipe:

{
  "tabWidth": 2,
  "useTabs": false
}

Agora, cada arquivo JSON no projeto é formatado de maneira idêntica, independentemente de quem o editou. Não há mais diffs apenas de formatação em pull requests.

Lidando com Casos Especiais

A maioria das ferramentas de formatação lida com JSON padrão sem problemas, mas algumas situações podem te atrapalhar:

• Números grandes — JSON não distingue entre inteiros e floats. Alguns formatadores podem reformatar 1.0 como 1 ou perder precisão em inteiros muito grandes. Se a precisão importa, verifique a saída.
• Escapamentos Unicode — Um formatador pode converter \u00e9 para o caractere literal é ou vice-versa. Ambos são JSON válidos, mas a mudança pode causar diffs inesperados.
• Objetos e arrays vazios — Alguns formatadores expandem {} para várias linhas. Outros os mantêm compactos. Isso é uma preferência de estilo, mas esteja ciente de que pode variar entre ferramentas.
• Nova linha final — A convenção POSIX diz que arquivos de texto devem terminar com uma nova linha. A maioria dos formatadores adiciona uma, mas nem todos. Verifique seu .editorconfig se isso for importante para seu CI.

Formatação como Parte do Seu Fluxo de Trabalho

As equipes mais eficazes tratam a formatação de JSON da mesma forma que tratam a formatação de código — como uma parte automatizada e não negociável do processo de desenvolvimento.

Hooks de pré-commit: Use uma ferramenta como husky com lint-staged para executar Prettier ou jq em arquivos JSON antes de cada commit. Isso captura problemas de formatação antes que entrem no código.

Verificações de CI: Adicione uma verificação de formatação ao seu pipeline de CI que falha se algum arquivo JSON não estiver formatado corretamente. O Prettier tem uma flag --check para exatamente esse propósito.

Integração com o editor: Formatar ao salvar elimina completamente a formatação manual. Combinado com um arquivo de configuração compartilhado, garante que cada membro da equipe produza uma saída idêntica.

O objetivo é tornar a formatação invisível — algo que acontece automaticamente, para que os desenvolvedores possam se concentrar no conteúdo real de seus arquivos JSON em vez de como eles parecem.

Experimente você mesmo: Cole JSON não formatado em nosso Formatador de JSON para instantaneamente embelezá-lo. Você também pode validar seu JSON para capturar erros estruturais antes da formatação.