Como formatar JSON: O guia completo para desenvolvedores

JSON (JavaScript Object Notation) é a linguagem universal de troca de dados na web. Seja construindo uma API REST, configurando uma aplicação ou transferindo dados entre serviços, você vai trabalhar com JSON constantemente. Mas o JSON bruto pode ser difícil de ler, e até pequenos erros de sintaxe podem quebrar toda a sua aplicação.

Este guia cobre tudo que você precisa saber sobre formatação JSON — da estrutura básica a dicas avançadas e armadilhas comuns.

O que é JSON?

JSON é um formato de dados leve, baseado em texto, fácil de ler para humanos e de processar para máquinas. Ele se baseia em duas estruturas:

• Pares chave-valor (objetos): { "nome": "Alice", "idade": 30 }
• Listas ordenadas (arrays): [1, 2, 3, "quatro"]

Estas podem ser aninhadas para criar estruturas de dados complexas:

{
  "usuario": {
    "nome": "Alice",
    "funcoes": ["admin", "editor"],
    "configuracoes": {
      "tema": "escuro",
      "notificacoes": true
    }
  }
}

Por que formatar JSON?

Quando o JSON está minificado (sem espaços), ele se torna quase impossível de ler:

{"usuario":{"nome":"Alice","funcoes":["admin","editor"],"configuracoes":{"tema":"escuro","notificacoes":true}}}

A formatação (também chamada de "embelezar" ou "pretty-print") adiciona indentação e quebras de linha para tornar a estrutura visível:

{
  "usuario": {
    "nome": "Alice",
    "funcoes": [
      "admin",
      "editor"
    ],
    "configuracoes": {
      "tema": "escuro",
      "notificacoes": true
    }
  }
}

JSON formatado é essencial para:

• Depurar respostas de API: Identificar rapidamente campos ausentes ou valores inesperados.
• Revisões de código: Tornar arquivos de configuração legíveis para sua equipe.
• Documentação: Incluir exemplos JSON claros na sua documentação.
• Edição manual: Encontrar e corrigir erros sem perder a cabeça.

Boas práticas de formatação JSON

1. Use indentação consistente

O padrão é 2 espaços ou 4 espaços por nível. Escolha um e mantenha em todo o projeto. A maioria dos guias de estilo (incluindo Google e Airbnb) recomenda 2 espaços.

2. Sempre coloque as chaves entre aspas duplas

O JSON exige aspas duplas ao redor de todas as chaves de objeto. Este é um erro comum ao migrar do JavaScript:

// ❌ JSON inválido
{ nome: "Alice" }

// ✅ JSON válido
{ "nome": "Alice" }

3. Use aspas duplas para strings

Strings JSON devem usar aspas duplas, não simples:

// ❌ Inválido
{ 'nome': 'Alice' }

// ✅ Válido
{ "nome": "Alice" }

4. Sem vírgulas finais

Diferente do JavaScript, o JSON não permite vírgulas finais:

// ❌ Inválido
{ "nome": "Alice", "idade": 30, }

// ✅ Válido
{ "nome": "Alice", "idade": 30 }

5. Apenas tipos de dados válidos

O JSON suporta exatamente seis tipos de dados:

Tipo	Exemplo
String	"olá"
Number	42, 3.14
Boolean	true, false
Null	null
Object	{ "chave": "valor" }
Array	[1, 2, 3]

Não existe undefined, Date, function nem Symbol no JSON.

Como formatar JSON programaticamente

JavaScript

const data = { nome: "Alice", idade: 30 };
const formatado = JSON.stringify(data, null, 2);
console.log(formatado);

O terceiro parâmetro (2) define a indentação em 2 espaços.

Python

import json
data = {"nome": "Alice", "idade": 30}
formatado = json.dumps(data, indent=2, ensure_ascii=False)
print(formatado)

Linha de comando (jq)

echo '{"nome":"Alice"}' | jq .

Erros comuns de JSON e como corrigi-los

Erro	Causa	Solução
Unexpected token '	Aspas simples em vez de duplas	Substituir ' por "
Unexpected end of JSON input	Dados truncados ou vazios	Verificar se o JSON está completo
Unexpected token ,	Vírgula final	Remover a última vírgula
Unexpected token u	undefined nos dados	Substituir por null ou remover a chave

Valide antes de formatar

A formatação não corrige JSON inválido. Se seu JSON tem erros de sintaxe, um formatador pode produzir resultados inesperados ou falhar. Sempre valide seu JSON primeiro, depois formate.

Um bom formatador valida e embeleza seu JSON em uma única etapa, destacando erros com números de linha e descrições claras.

Experimente nosso formatador JSON gratuito

Nosso Formatador JSON cuida de tudo para você. Cole seu JSON, e ele vai:

• Detectar e corrigir automaticamente problemas de formatação comuns
• Embelezar seu JSON com indentação configurável
• Validar a sintaxe e destacar erros
• Funcionar inteiramente no seu navegador — seus dados nunca saem do seu dispositivo

Seja para depurar uma resposta de API complicada, limpar um arquivo de configuração ou preparar JSON para documentação, nosso formatador torna tudo instantâneo e sem erros.

JSON vs XML vs YAML

Se você está escolhendo um formato de dados para seu projeto, aqui vai uma comparação rápida:

Critério	JSON	XML	YAML
Legibilidade	Boa	Verboso	Excelente
Tamanho do arquivo	Pequeno	Grande	Médio
Velocidade de análise	Rápido	Lento	Médio
Tipos de dados	Limitados	Nenhum (tudo strings)	Rico
Comentários	Não suportados	Suportados	Suportados

O JSON continua sendo a melhor escolha para APIs e troca de dados web graças ao seu equilíbrio entre simplicidade, velocidade e suporte universal.

Conclusão

Um JSON corretamente formatado economiza tempo, reduz bugs e torna seu código mais manutenível. Siga as boas práticas acima, valide antes de formatar e use as ferramentas certas para acelerar seu fluxo de trabalho.

Experimente o Formatador JSON agora — cole seu JSON e veja a diferença que a formatação faz em segundos.