JSON na prática: formatar, validar e converter sem dor de cabeça

A sintaxe do JSON em cinco minutos

JSON quer dizer JavaScript Object Notation. Apesar do nome, ele deixou de ser coisa de JavaScript há muito tempo: hoje é o formato em que quase toda API troca dados, em que apps guardam configuração e em que um sistema conversa com outro. A grande sacada é que ele é, ao mesmo tempo, legível por gente e trivial de processar por máquina.

A estrutura inteira se apoia em dois blocos. O objeto, entre chaves { }, é uma coleção de pares "chave": valor. O array, entre colchetes [ ], é uma lista ordenada de valores. É só isso que dá para aninhar à vontade.

{
  "nome": "Ana",
  "idade": 29,
  "ativo": true,
  "saldo": 1540.50,
  "tags": ["pix", "premium"],
  "endereco": {
    "cidade": "Recife",
    "uf": "PE"
  },
  "telefone": null
}

Os valores possíveis são só seis: string (sempre entre aspas duplas), número (inteiro ou decimal, sem aspas), booleano (true ou false), null, objeto e array. Repare no que não existe: não há tipo de data (uma data vira string, tipo "2026-06-30"), não há comentários e as chaves são sempre strings entre aspas duplas. Aspas simples não valem. Essas três regras explicam a maioria dos erros que você vai ver a seguir.

Os erros de sintaxe mais comuns (vírgula sobrando, aspas)

Quase todo erro de JSON cai em meia dúzia de categorias. Vale decorar a lista, porque a mensagem do parser costuma ser críptica — um genérico Unexpected token apontando para a linha errada.

• Vírgula sobrando (trailing comma): a vírgula depois do último item. ["a", "b",] é inválido. JavaScript moderno aceita; JSON, não.
• Aspas simples: {'nome': 'Ana'} parece certo, mas JSON exige aspas duplas em chaves e strings.
• Chave sem aspas: {nome: "Ana"} é objeto de JavaScript, não JSON. A chave precisa virar "nome".
• Comentários: // isto quebra. JSON não tem comentários, ponto.
• Vírgula faltando entre dois pares, ou vírgula a mais entre eles.
• Aspas não escapadas: uma aspa dentro de uma string precisa virar \", e a barra invertida vira \\.

Há ainda pegadinhas mais sutis. NaN e Infinity não são números válidos em JSON. Zeros à esquerda (012) são proibidos. E um caractere invisível no começo do arquivo, o famoso BOM, derruba parsers que não o ignoram. Em vez de caçar a vírgula errada no olho, cole o texto no Validador JSON: ele aponta a linha e a coluna exatas do problema e descreve o que o parser esperava encontrar ali.

Formatar (pretty-print) vs minificar

O mesmo JSON pode ser escrito de duas formas opostas, e cada uma serve a um momento. Formatar (ou pretty-print) adiciona quebras de linha e indentação para um humano ler. Minificar tira todo espaço em branco supérfluo para a máquina transmitir mais rápido.

O mesmo objeto, minificado, vira uma linha só:

{"nome":"Ana","idade":29,"tags":["pix","premium"]}

Para os olhos, indentado com 2 espaços:

{
  "nome": "Ana",
  "idade": 29,
  "tags": ["pix", "premium"]
}

Em JavaScript, isso é literalmente o terceiro parâmetro do JSON.stringify: JSON.stringify(obj, null, 2) indenta com 2 espaços; sem o terceiro argumento, sai tudo grudado. A regra prática: minifique em produção (resposta de API, arquivo que viaja pela rede) e formate para depurar. Num payload grande a economia é real — tirar espaços e quebras pode encolher o arquivo em 10% a 20% antes mesmo do gzip. Quando você recebe um JSON espremido numa linha só e precisa entendê-lo, o Formatador JSON reorganiza tudo com indentação e ainda destaca a estrutura aninhada.

Convertendo para CSV, YAML e XML

JSON raramente vive sozinho. Cedo ou tarde alguém vai pedir os dados numa planilha, num arquivo de configuração ou num sistema legado que só fala XML. As conversões mais comuns têm armadilhas próprias.

JSON ↔ CSV

CSV é uma tabela plana: linhas e colunas, nada de aninhamento. Por isso a conversão limpa só funciona quando seu JSON é um array de objetos com as mesmas chaves. Veja:

[
  {"nome": "Ana",   "idade": 29, "cidade": "Recife"},
  {"nome": "Bruno", "idade": 34, "cidade": "Curitiba"}
]

vira, em CSV:

nome,idade,cidade
Ana,29,Recife
Bruno,34,Curitiba

As chaves viram o cabeçalho; cada objeto vira uma linha. O problema aparece quando um campo é, ele mesmo, um objeto ou um array — não há coluna óbvia para ele, e a ferramenta precisa "achatar" (ex.: endereco.cidade) ou serializar o campo inteiro. Vírgulas e quebras de linha dentro de um valor obrigam aspas no CSV. O Conversor JSON ↔ CSV resolve as duas direções e cuida desse escape para você.

JSON ↔ YAML

YAML é o formato preferido de arquivos de configuração (Docker Compose, GitHub Actions, Kubernetes) justamente porque é mais limpo de ler: ele troca chaves e aspas por indentação. O mesmo objeto fica assim:

nome: Ana
idade: 29
ativo: true
tags:
  - pix
  - premium
endereco:
  cidade: Recife
  uf: PE

YAML é um superconjunto de JSON — todo JSON válido é YAML válido. A conversão de ida usa o JSON para YAML; a volta, quando você editou o config e quer devolver para uma API que só aceita JSON, usa o YAML para JSON. Cuidado com a indentação no YAML: ele usa espaços, nunca tabulações, e um espaço a mais muda o significado da estrutura inteira.

JSON → XML

XML é mais verboso porque cada valor mora entre tags de abertura e fechamento. O par "nome": "Ana" vira <nome>Ana</nome>. Como XML não tem o conceito de array, a conversão costuma repetir a mesma tag para representar a lista — uma decisão de design que a ferramenta toma por você.

JSON Schema: validando a estrutura, não só a sintaxe

Há uma diferença grande entre um JSON estar bem-formado e estar correto. O texto abaixo é sintaticamente perfeito — qualquer parser aceita:

{ "idade": "vinte e nove", "ativo": "talvez" }

Mas se o seu sistema espera que idade seja um número e que nome exista, esse documento está errado mesmo passando no validador de sintaxe. É aí que entra o JSON Schema: um JSON que descreve o formato que outro JSON deve seguir. Um esquema simples:

{
  "type": "object",
  "required": ["nome", "idade"],
  "properties": {
    "nome":  { "type": "string" },
    "idade": { "type": "integer", "minimum": 0 },
    "ativo": { "type": "boolean" }
  }
}

Esse esquema diz: precisa ser um objeto, nome e idade são obrigatórios, idade tem de ser inteiro e não negativo. Validar contra esquema é o que separa uma API robusta de uma frágil: você rejeita o dado ruim na porta de entrada, antes que ele contamine o banco. Para o dia a dia, primeiro garanta a sintaxe no Validador JSON; o esquema entra depois, como segunda camada de checagem.

Perguntas frequentes

JSON pode ter comentários?

Não, a especificação não permite. Se você precisa comentar um arquivo de configuração, considere usar YAML (que aceita # para comentário) ou variantes como JSON5 e JSONC, lembrando que essas não são JSON puro e nem todo parser as entende. Antes de enviar para uma API, converta de volta para JSON limpo.

Qual a diferença entre formatar e minificar?

São operações opostas sobre o mesmo conteúdo. Formatar adiciona espaços e quebras de linha para um humano ler; minificar remove tudo isso para a máquina transmitir mais rápido. Nenhuma altera os dados em si — só a apresentação. Use o Formatador JSON para alternar entre as duas.

Por que números grandes "quebram" no JSON?

JSON não distingue inteiro de decimal — tudo é número de ponto flutuante de dupla precisão. Isso significa que inteiros acima de 2^53 (cerca de 9 quatrilhões) perdem precisão. IDs muito longos, por isso, costumam viajar como string no JSON, não como número.

Posso converter qualquer JSON para CSV?

Só com ressalvas. CSV é plano; JSON é hierárquico. A conversão é direta para um array de objetos rasos, mas estruturas aninhadas precisam ser achatadas ou serializadas em uma coluna. Se o seu JSON tem objetos dentro de objetos, espere alguma perda de fidelidade na ida e teste o resultado no Conversor JSON ↔ CSV.

JSON e YAML são intercambiáveis?

Quase. Como YAML é um superconjunto de JSON, todo JSON válido também é YAML válido, e dá para ir e voltar sem perder dados com o JSON para YAML e o YAML para JSON. A diferença prática é o uso: JSON domina APIs e troca de dados; YAML domina arquivos de configuração que pessoas editam à mão.