Como Formatar JSON: Guia Completo para Desenvolvedores
JSON (JavaScript Object Notation) é o formato mais utilizado para troca de dados na web. Neste guia completo, você vai aprender o que é JSON, como formatar corretamente, os erros mais comuns e as melhores práticas para trabalhar com dados estruturados.
Índice
- O que é JSON?
- Como funciona o formato JSON
- Como formatar JSON
- Exemplo prático
- Passo a passo
- Boas práticas
- Erros comuns
- Dicas
- Perguntas Frequentes
- Ferramentas relacionadas
- Experimente nossa ferramenta
O que é JSON?
JSON (JavaScript Object Notation) é um formato leve de troca de dados amplamente utilizado em aplicações web modernas. Ele é fácil de ler e escrever para humanos, além de ser simples de interpretar e gerar para máquinas.
Desde APIs REST até arquivos de configuração, o JSON está presente em praticamente todos os projetos de software atuais. Saber como formatar e manipular JSON corretamente é uma habilidade essencial para qualquer desenvolvedor.
Onde o JSON é utilizado
- APIs REST e GraphQL
- Arquivos de configuração (package.json, tsconfig.json)
- Bancos de dados NoSQL (MongoDB, Firebase)
- Comunicação entre microserviços
- Armazenamento local (localStorage)
Como funciona o formato JSON
Um documento JSON válido pode conter os seguintes tipos de dados:
| Tipo | Descrição | Exemplo |
|------|-----------|---------|
| Objeto | Pares chave-valor entre {} | {"nome": "João"} |
| Array | Lista ordenada entre [] | [1, 2, 3] |
| String | Texto entre aspas duplas | "texto" |
| Número | Inteiro ou decimal | 42, 3.14 |
| Booleano | Verdadeiro ou falso | true, false |
| Null | Valor nulo | null |
Regras fundamentais
- Chaves devem ser strings entre aspas duplas
- Strings devem usar aspas duplas (não simples)
- Não é permitido vírgula após o último elemento
- Não são permitidos comentários
- Codificação deve ser UTF-8
Como formatar JSON
Formatar JSON significa transformar um JSON compactado (minificado) em uma versão legível com indentação e quebras de linha.
Por que formatar?
Quando trabalhamos com dados JSON, frequentemente recebemos respostas de APIs em formato compactado. Esse formato é eficiente para transferência, mas ilegível para humanos.
A formatação adequada oferece:
- Legibilidade: Código indentado é mais fácil de entender
- Depuração: Encontrar erros é significativamente mais rápido
- Colaboração: Equipes revisam estruturas com clareza
- Documentação: Serve como referência visual da estrutura
Usando JavaScript
const dados = { nome: "Maria", idade: 28, skills: ["JS", "TS"] };
const formatado = JSON.stringify(dados, null, 2);
console.log(formatado);
O terceiro parâmetro define o número de espaços para indentação. O valor 2 é o padrão mais utilizado.
Exemplo prático
JSON não formatado (minificado)
{"nome":"Maria","idade":28,"habilidades":["JavaScript","TypeScript","React"],"endereco":{"cidade":"São Paulo","estado":"SP"},"ativo":true}
JSON formatado
{
"nome": "Maria",
"idade": 28,
"habilidades": [
"JavaScript",
"TypeScript",
"React"
],
"endereco": {
"cidade": "São Paulo",
"estado": "SP"
},
"ativo": true
}
A diferença é clara: o segundo é legível, organizado e fácil de debugar.
Passo a passo
Como formatar JSON usando o Toolbox Brasil
- Acesse a ferramenta — Abra o Formatador de JSON
- Cole o JSON — Cole ou digite seu JSON no campo de entrada
- Clique em Formatar — O resultado aparece instantaneamente
- Copie o resultado — Use o botão de copiar para obter o JSON formatado
- Corrija erros — Se houver erros de sintaxe, a ferramenta mostra a linha e o tipo do problema
Usando a linha de comando
# Com Python
echo '{"nome":"João"}' | python3 -m json.tool
# Com jq
echo '{"nome":"João"}' | jq .
# Com Node.js
node -e "console.log(JSON.stringify(JSON.parse(process.argv[1]), null, 2))" '{"nome":"João"}'
Boas práticas
Validação
Sempre valide o JSON antes de processá-lo. Um JSON inválido pode causar erros silenciosos difíceis de rastrear.
try {
const dados = JSON.parse(texto);
} catch (erro) {
console.error("JSON inválido:", erro.message);
}
Convenções de nomenclatura
Mantenha consistência nos nomes das chaves:
- camelCase:
nomeCompleto,dataNascimento— padrão em JavaScript/TypeScript - snake_case:
nome_completo,data_nascimento— comum em APIs Python/Ruby
Tamanho e performance
- Evite JSON muito grande (> 5MB) em uma única resposta
- Use paginação para listas longas
- Considere compressão (gzip) para transferência
Segurança
- Nunca confie em JSON vindo do cliente sem validação
- Use bibliotecas de parsing seguras
- Evite
eval()para processar JSON
Erros comuns
Os erros mais frequentes ao trabalhar com JSON são:
| Erro | Exemplo incorreto | Correto |
|------|-------------------|---------|
| Vírgula no último elemento | {"a": 1,} | {"a": 1} |
| Aspas simples | {'nome': 'João'} | {"nome": "João"} |
| Chaves não fechadas | {"a": 1 | {"a": 1} |
| Comentários | {"a": 1 // valor} | {"a": 1} |
| Valores sem aspas | {nome: "João"} | {"nome": "João"} |
| Trailing comma em arrays | [1, 2, 3,] | [1, 2, 3] |
Como identificar erros
Quando receber um erro como SyntaxError: Unexpected token, verifique:
- Se todas as aspas são duplas
- Se não há vírgula após o último elemento
- Se todas as chaves e colchetes estão fechados
- Se não há caracteres invisíveis (BOM, zero-width spaces)
Dicas
✔ Utilize sempre codificação UTF-8
✔ Evite JSON gigante em uma única requisição
✔ Valide antes de enviar para APIs
✔ Padronize a indentação (2 espaços é o padrão)
✔ Use ferramentas de linting no CI/CD
✔ Prefira JSON Schema para validação estrutural
✔ Minifique JSON em produção para economia de banda
Perguntas Frequentes
JSON aceita comentários?
Não. A especificação JSON (RFC 8259) não permite comentários. Se precisar de comentários, considere usar JSONC (JSON with Comments) ou YAML para configurações — veja JSON vs YAML: quando usar cada um.
JSON aceita vírgula no final?
Não. Trailing commas (vírgulas após o último elemento) causam erro de parsing. Diferente de JavaScript, o JSON segue a especificação estritamente.
Qual a diferença entre JSON e XML?
JSON é mais leve, mais fácil de ler e de processar. XML é mais verboso, mas oferece schemas, namespaces e atributos. Para APIs modernas, JSON é o padrão. Para documentos complexos com metadados, XML ainda é utilizado.
JSON aceita aspas simples?
Não. Apenas aspas duplas (") são válidas para strings e chaves em JSON. Aspas simples (') causam erro de parsing.
Qual o tamanho máximo de um JSON?
Não existe limite na especificação. Na prática, depende do parser e da memória disponível. A maioria dos frameworks web limita o body a 1MB por padrão (configurável).
JSON é case-sensitive?
Sim. "Nome" e "nome" são chaves diferentes. Os valores literais true, false e null devem ser em minúsculas.
Ferramentas relacionadas
- Formatador de JSON — Formate e embeleze JSON instantaneamente
- Validador de JSON — Verifique se seu JSON é válido
- Base64 Encoder/Decoder — Codifique e decodifique Base64
- UUID Generator — Gere UUIDs v4 aleatórios
Artigos relacionados
- JSON vs YAML: quando usar cada um — comparação prática entre os dois formatos
- O que é Regex? — para localizar e extrair trechos dentro de arquivos JSON
Experimente nossa ferramenta
Use gratuitamente o Formatador de JSON do Toolbox Brasil.
- Não precisa instalar nada
- Funciona diretamente no navegador
- Seus dados não saem do seu dispositivo
- Validação e formatação em tempo real