O que é JSON
JSON (JavaScript Object Notation) é um formato leve de troca de dados. A comunicação entre front-end e back-end, arquivos de configuração e respostas de API usam JSON. Estrutura clara, legível por humanos e analisável por máquinas, é o padrão de fato do desenvolvimento moderno.
Regras de sintaxe do JSON
Tipos de dados
- String: entre aspas duplas, como "hello"
- Número: inteiro ou ponto flutuante, como 42, 3.14
- Booleano: true ou false
- Nulo: null
- Array: entre colchetes, como [1, 2, 3]
- Objeto: entre chaves, pares chave-valor, como {"name": "Tom"}
- Aninhamento: objetos e arrays podem se aninhar
Regras básicas
- As chaves devem usar aspas duplas (não aspas simples)
- As strings devem usar aspas duplas
- Não pode haver vírgula à direita (não pode haver vírgula após o último elemento)
- Não pode haver comentários
- O nível superior só pode ser objeto ou array
As três necessidades de formatação
Validação
Verifica se a sintaxe do JSON está correta. Uma vírgula faltando, uma vírgula a mais ou aspas não fechadas causam falha na análise.
Embelezamento (Pretty Print)
Expande um JSON compactado em uma linha para um formato de várias linhas com recuo, facilitando a leitura.
Forma compactada:
{"name":"Tom","age":20,"tags":["a","b"]}
Embelezado:
{
"name": "Tom",
"age": 20,
"tags": ["a", "b"]
}
Compactação (Minify)
Remove todos os espaços e quebras de linha do formato embelezado, compactando em uma linha para reduzir o tamanho. Usada para transmissão e armazenamento.
Erros comuns de JSON
Erros de aspas
- Usou aspas simples: JSON só permite aspas duplas
- Esqueceu de fechar as aspas
- Nome da chave sem aspas
Errado: {'name': 'Tom'} (aspas simples) Correto: {"name": "Tom"}
Erros de vírgula
- Vírgula à direita: vírgula após o último elemento
- Vírgula faltando: esqueceu a vírgula entre elementos
Errado: {"a": 1, "b": 2,} (vírgula à direita) Correto: {"a": 1, "b": 2}
Erros de tipo de dados
- Usou undefined (JSON não tem undefined, use null)
- Usou NaN / Infinity (JSON não suporta)
- Funções e objetos Date não podem ser serializados diretamente
Erros de escape
Caracteres especiais em strings precisam de escape:
- Aspas: "
- Barra invertida: \
- Nova linha: \n
- Tabulação: \t
- Retorno de carro: \r
Errado: "He said "hello"" (aspas sem escape) Correto: "He said "hello""
Erros de codificação
JSON deve usar codificação UTF-8. Outras codificações podem causar caracteres ilegíveis ou falha na análise.
Aninhamento e níveis
Exemplo de aninhamento
{
"user": {
"name": "Tom",
"address": {
"city": "Lisboa",
"zip": "1000-001"
}
},
"orders": [
{"id": 1, "items": ["A", "B"]},
{"id": 2, "items": ["C"]}
]
}
Recuo
- Recuo de 2 espaços: o mais usado
- Recuo de 4 espaços: mais espaçoso
- Recuo com Tab: algumas equipes usam
Ao embelezar, padronize o estilo de recuo.
Aninhamento profundo
Mais de 5 níveis de aninhamento dificultam a leitura. Considere achatar a estrutura ou dividi-la.
JSON e outros formatos
JSON vs JSONL
- JSON: um único JSON em todo o arquivo (geralmente um objeto ou array)
- JSONL (JSON Lines): um JSON independente por linha, adequado para logs e dados em fluxo
JSON vs JSON5
JSON5 é um superconjunto do JSON, suportando:
- Aspas simples
- Vírgulas à direita
- Comentários
- Números hexadecimais
Mas JSON5 não é JSON padrão, e a compatibilidade dos analisadores é limitada.
JSON vs YAML
- JSON: sintaxe estrita, amigável para máquinas
- YAML: sintaxe flexível (suporta comentários, recuo indica hierarquia), amigável para humanos
- Arquivos de configuração costumam usar YAML; a transmissão de API usa JSON
JSON vs XML
- JSON: leve, sem sobrecarga de tags
- XML: tags verbosas, mas suporta atributos e namespaces
- No desenvolvimento moderno, JSON praticamente substituiu o XML
Dicas práticas
Copiar JSON
Copie o JSON de respostas de API ou logs e cole em uma ferramenta de formatação para embelezar e facilitar a leitura.
Depurar JSON
Quando uma interface retorna erro, formate o JSON da resposta e verifique se os campos estão corretos.
Arquivos de configuração
Escreva arquivos de configuração em JSON e, após formatar, comente o significado de cada campo (note que JSON padrão não suporta comentários; use JSONC ou documentação separada).
Conversão de dados
Em cenários como CSV para JSON, XML para JSON, etc., formate e valide o resultado após a conversão.
Use a ferramenta CSV para JSON para converter dados tabulares em JSON com um clique.
Uso da ferramenta de formatação
Validação
Cole o JSON; a ferramenta verifica a sintaxe. Se houver erro, indica a posição e a causa.
Embelezamento
Cole o JSON compactado, escolha o recuo, clique em embelezar e obtenha o formato de várias linhas.
Compactação
Cole o JSON embelezado, clique em compactar e obtenha uma única linha.
Escape
Escapa caracteres especiais em strings JSON, ou faz o caminho inverso.
Processar JSON com o DocsAll
O JSON envolve codificação e conversão; use as ferramentas relacionadas:
- Ferramenta de codificação/decodificação: trata o escape de strings JSON
- Ferramenta CSV para JSON: converte tabelas em JSON
Processamento no navegador, os dados não são enviados para o servidor.
Perguntas frequentes
Após formatar, caracteres não ASCII viram \uXXXX
Algumas ferramentas escapam caracteres não ASCII por padrão. Para exibir os caracteres originais, desative a opção de escape Unicode.
JSON grande trava
JSON muito grande (vários MB) pode travar ao formatar. Use uma ferramenta de linha de comando (como jq) para maior eficiência.
E os comentários?
JSON padrão não suporta comentários. Se precisar de comentários, use JSONC, JSON5 ou YAML.
Resumo
A formatação de JSON tem três pontos centrais: validar a sintaxe, embelezar para leitura e compactar para transmissão. Os erros mais comuns são de aspas, vírgulas e escape. Para processar JSON, use a ferramenta de codificação/decodificação do DocsAll e a ferramenta CSV para JSON, que rodam no navegador, sem enviar dados para fora.