Formatar JSON é adicionar as quebras de linha e a indentação que a máquina não se deu ao trabalho de pôr, para que uma linha de 40.000 caracteres ganhe uma forma visível. Todo editor e a maioria dos terminais fazem isso com um único comando. As únicas decisões de verdade são quanto indentar e se vale colar os dados em um site para fazer isso.
A resposta rápida
- No terminal:
jq . file.json, oupython3 -m json.tool file.json. - No VS Code: abra o arquivo e aperte Shift+Alt+F (Shift+Option+F no Mac).
- No navegador: abra a URL do
.jsonno Firefox, que tem um visualizador de JSON embutido, e clique em Pretty Print. - No celular: um app de JSON com o comando Beautify, em vez de colar o texto em um site.
- Não formata de jeito nenhum: ainda não é JSON válido. Conserte isso primeiro; a mensagem de erro do formatador diz onde.
O que a formatação muda e o que não muda
Formatar só adiciona ou remove espaço em branco entre tokens: espaços, tabs e quebras de linha fora das strings. Um formatador correto nunca mexe nos valores. Então estes dois são o mesmo documento:
{"id":7,"tags":["a","b"],"owner":{"name":"Ana"}}
{
"id": 7,
"tags": [
"a",
"b"
],
"owner": {
"name": "Ana"
}
}
Minificar é o inverso: tirar todo espaço e quebra de linha opcional. É o que se manda pela rede ou se cola em um campo de configuração que quer uma linha só. Nenhuma das direções muda o significado dos dados, e por isso é seguro reformatar um arquivo que você não escreveu.
Duas operações ficam ao lado da formatação na maioria das ferramentas e são mudanças, ainda que inofensivas: ordenar as chaves, que reordena cada objeto em ordem alfabética, e escapar, que transforma o documento inteiro em uma única string. Faça isso de propósito, não como efeito colateral.
No terminal
jq é o que vale a pena ter instalado:
jq . data.json # pretty, 2-space indent
jq --indent 4 . data.json # 4 spaces
jq --tab . data.json # tabs
jq -c . data.json # minified, one line
jq -S . data.json # keys sorted A–Z
Para formatar um arquivo no próprio lugar, escreva em um arquivo temporário e
mova de volta. jq . data.json > data.json esvazia o arquivo antes de o jq
lê-lo.
jq . data.json > tmp.json && mv tmp.json data.json
Python já vem com um formatador, então funciona em qualquer máquina que tenha Python 3:
python3 -m json.tool data.json
python3 -m json.tool --indent 4 --sort-keys data.json
python3 -m json.tool --compact data.json
Uma diferença que importa em dados reais: o json.tool lê números como floats
do Python, a menos que sejam inteiros, então um valor como 1.10 sai como
1.1. O jq 1.7 e posteriores mantêm os literais numéricos como foram escritos.
Se o arquivo tem preços, números de versão ou IDs com dígitos iniciais que
importam, confira a saída.
No editor
VS Code: Shift+Alt+F formata o documento inteiro, ou Format
Selection na paleta de comandos formata só uma parte. Defina
"editor.formatOnSave": true para arquivos [json] se você os edita com
frequência. A indentação segue a configuração de tamanho de tab do editor.
Sublime Text, Notepad++ e as IDEs da JetBrains formatam JSON, seja de forma nativa (JetBrains: Code → Reformat Code) ou com um plugin instalado em uma linha (Notepad++: JSON Viewer ou JSTool).
Prettier é a ferramenta certa quando o JSON de um projeto inteiro deve ter a
mesma aparência: npx prettier --write "**/*.json".
No navegador
O Firefox formata qualquer resposta JSON automaticamente, com uma aba JSON recolhível, uma aba Raw Data e um botão Pretty Print. É a forma mais rápida de ler uma resposta de API sem instalar nada.
Chrome e Edge mostram uma caixa Pretty-print acima do JSON bruto nas versões recentes. Qualquer coisa além disso (recolher, buscar por chave) exige uma extensão.
A questão dos formatadores online
Pesquise sobre este assunto e a primeira página são sites com uma caixa de texto enorme. Eles funcionam. A questão é o que você está colando neles.
Uma resposta de API com um token de acesso, um arquivo de configuração com a senha do banco de dados, uma exportação de clientes: tudo isso é colado rotineiramente em formatadores, e você não tem como verificar pela página se o texto fica no seu navegador ou é enviado a um servidor e registrado. Alguns sites também já foram flagrados guardando documentos "compartilhados" em URLs fáceis de adivinhar.
A regra é simples. Se você não colaria em um chat público, formate localmente. Todas as opções acima rodam na sua própria máquina.
Escolhendo a indentação
- 2 espaços é o padrão de fato: jq, Prettier, a maioria das ferramentas de JavaScript, a maioria das docs de API.
- 4 espaços lê melhor em documentos muito aninhados numa tela larga, e é a convenção do Python.
- Tabs deixam cada leitor escolher a própria largura e deixam os arquivos um pouco menores.
Nenhuma está errada. Escolha uma por projeto e deixe um formatador impor, para que um diff mostre mudanças nos dados e não mudanças no espaço em branco.
No iPhone e no iPad
O celular é onde o JSON fica menos legível, porque o iOS mostra um arquivo
.json como texto simples, sem quebras de linha. As formas de abrir um estão
aqui; formatar é o passo seguinte.
No Smart Json, Beautify reformata o documento com indentação consistente, Minify o reduz a uma linha e Sort keys A–Z reordena cada objeto. Desfazer funciona para os três. Se o texto não puder ser analisado, um aviso aponta o problema com linha e coluna em vez de formatar algo meio válido, e Fix conserta os suspeitos de sempre: comentários, vírgulas finais, aspas simples e chaves sem aspas.
Beautify, Minify e Sort keys no iPhone e no iPad, offline, com um erro em linguagem simples quando o JSON está quebrado. Nada é colado em um site.
O que ele fazQuando a formatação falha
Um formatador recusa tudo o que não é JSON válido, e o erro costuma ser uma posição: line 1, column 3,912. Em um documento minificado isso é uma linha só, então a coluna é a pista. As causas de sempre são uma vírgula final, aspas simples, um comentário ou um valor sem aspas. Cada erro comum é explicado aqui, com o que cada mensagem significa.