Como formatar e validar JSON: o guia do desenvolvedor

JSON está em todo lugar: respostas de API, arquivos de configuração, logs, filas de mensagens, payloads de requisições, colunas de banco de dados. Para um formato tão simples, é surpreendente a frequência com que encontramos problemas com ele — uma vírgula faltando quebra um deploy, um espaço em branco a mais faz com que dois arquivos sejam “diferentes” quando deveriam ser idênticos, uma estrutura profundamente aninhada é impossível de depurar porque ninguém a indentou.

O que o JSON realmente permite

A especificação JSON é deliberadamente minúscula. Um documento JSON é um de:

• Um objeto: { "key": value, ... }
• Um array: [ value, ... ]
• Uma string: "text" (sempre com aspas duplas, nunca simples)
• Um número: 42, 3.14, -2.5e10
• Um booleano: true ou false
• null

Só isso. Sem comentários. Sem vírgulas finais. Sem chaves sem aspas. Sem strings com aspas simples. Sem undefined. Sem NaN ou Infinity. Sem funções.

Se você já se perguntou por que um parser JSON rejeitou seu arquivo “obviamente válido”, geralmente é um destes:

{
  "name": "Alice",
  "age": 30, // ← comentário: NÃO é JSON válido
  "email": 'alice@...', // ← aspas simples: NÃO é JSON válido
  role: "admin", // ← chave sem aspas: NÃO é JSON válido
  "active": true, // ← vírgula final: NÃO é JSON válido
}

Os formatos que permitem essas flexibilizações são o JSON5 (comentários, vírgulas finais, chaves sem aspas) e o JSONC (JSON with Comments, usado pelos arquivos de configuração do VS Code). São supersets do JSON, mas exigem parsers especializados.

Regras de formatação que tornam o JSON legível

JSON minificado parece isto:

{"users":[{"id":1,"name":"Alice","roles":["admin","editor"]},{"id":2,"name":"Bob","roles":["viewer"]}]}

JSON formatado parece isto:

{
  "users": [
    {
      "id": 1,
      "name": "Alice",
      "roles": ["admin", "editor"]
    },
    {
      "id": 2,
      "name": "Bob",
      "roles": ["viewer"]
    }
  ]
}

Os mesmos dados, legibilidade completamente diferente.

As regras que importam: indentação de 2 espaços (de longe a convenção mais comum — alguns projetos usam 4, tabulações são raras, mas seja consistente). Uma chave por linha dentro de objetos, um item por linha em arrays de conteúdo não trivial. Espaço após os dois-pontos, sem espaço antes: "key": value. Arrays de primitivos curtos podem ficar em uma linha; arrays de objetos sempre em várias.

Nosso Formatador JSON aplica tudo isso automaticamente quando você clica em Formatar.

Validando JSON: o que procurar

1. Vírgula faltando ou a mais

De longe a mais comum. JSON sintaticamente inválido quase sempre tem um problema de vírgula.

{
  "a": 1,
  "b": 2 ← vírgula faltando
  "c": 3
}

O parser culpa a linha depois da vírgula faltante, o que pode ser enganoso.

2. String não fechada

Uma quebra de linha solta dentro de uma string, ou uma aspa de fechamento faltando:

{ "name": "Alice
}

JSON não permite quebras de linha literais dentro de strings. Você precisa escapá-las como \n.

3. Colchetes/chaves incompatíveis

Um } ou ] a mais em qualquer lugar do arquivo:

{
  "users": [{"name": "Alice"}]}
}

A maioria dos parsers reporta o primeiro colchete que não casa, que pode estar longe do erro real.

4. Número inválido

Números JSON seguem regras estritas: sem + inicial, sem zeros à esquerda (exceto 0.x), sem 1. sem dígito final, sem .5 sem zero inicial.

{ "a": +5, "b": 07, "c": 1., "d": .5 } ← todos inválidos

5. Caracteres escapados em strings

Barras invertidas e aspas dentro de strings precisam ser escapadas:

{ "path": "C:\Users\Alice" }   ← inválido (barra invertida não escapada)
{ "path": "C:\\Users\\Alice" } ← válido

6. Chaves duplicadas

A especificação JSON diz que chaves duplicadas são “permitidas, mas desaconselhadas”. Na prática, a maioria dos parsers silenciosamente pega o último valor. Isso quase sempre é um bug.

{ "name": "Alice", "name": "Bob" }

Como formatar e validar na prática

O fluxo mais rápido:

1. Cole o JSON suspeito em um formatador
2. Clique em Formatar
3. Se aceitar, leia a saída formatada para entender a estrutura
4. Se rejeitar, leia a mensagem de erro — o número da linha geralmente está perto (mas não exatamente) do problema real

Nosso Formatador JSON usa o JSON.parse embutido do navegador — o mesmo parser usado por toda API Node.js e serviço web. Qualquer mensagem de erro que você vê é a mesma que uma API real emitiria.

O toggle minificar / formatar

Formatadores geralmente têm dois botões:

• Formatar (ou Beautify, Pretty-print): adiciona espaço em branco e indentação para leitura humana
• Minificar (ou Compact): remove todo espaço em branco desnecessário

JSON minificado é usado quando você se importa com tamanho em bytes — envio pela rede, armazenamento em banco, embutir em uma URL. Funcionalmente idêntico ao JSON formatado, mas notavelmente menor para documentos grandes.

Formatado: 1.240 bytes
Minificado: 680 bytes (-45%)

Para respostas de API em produção, sempre minifique. Para arquivos de configuração, logs e qualquer coisa que humanos leem, sempre formate.

Ferramentas além do formatador

Uma vez que seu JSON está formatado e válido, você frequentemente precisa fazer mais com ele:

JSON schema — uma forma de definir quais campos um documento válido deve ter, com tipos e restrições. Se você tem uma forma de JSON que quer impor em múltiplos documentos, escreva um schema e valide contra ele.

JMESPath / jq — linguagens de consulta para extrair ou transformar JSON. O jq é a ferramenta de linha de comando de facto.

JSON diff — ferramentas que mostram o que mudou entre dois documentos JSON, de forma mais útil que um diff de texto.

Geralmente não são necessárias para formatação do dia a dia, mas se você trabalha com JSON regularmente, vale conhecer.

Cheatsheet de referência rápida

Necessidade	O que fazer
Tornar JSON legível	Formatar com indentação de 2 espaços
Reduzir para transporte	Minificar
Encontrar um erro de sintaxe	Colar em um formatador, anotar local do erro
Verificar se dois documentos são “iguais”	Minificar os dois e comparar byte a byte, ou usar um diff JSON
Adicionar validação de estrutura	Usar JSON Schema
Armazenar em uma URL ou cookie	Minificar e codificar como URI

---

Um hábito que vale construir: nunca cole JSON bruto em um e-mail, mensagem de chat ou issue tracker sem antes formatar. JSON minificado em uma issue do GitHub é praticamente ilegível e desperdiça o tempo do leitor. Trinta segundos num formatador transformam um muro de texto em uma estrutura legível.

E quando depurar uma resposta real de API, passe-a por um formatador antes de tentar entendê-la. Esse hábito sozinho economiza horas de apertar os olhos olhando para saída sem indentação.

Nosso Formatador JSON roda no seu navegador — sem uploads, sem idas e vindas a servidor, nada é registrado. Cole JSON, clique em Formatar ou Minificar, copie, pronto. Para consertar JSON quebrado, as mensagens de erro coincidem exatamente com o parser nativo do navegador, então o que você vê corresponde ao que seu código vai ver quando chamar JSON.parse().