O que é o JSON? Erros comuns e como os corrigir

Um guia direto sobre JSON: como está estruturado, as regras de sintaxe que apanham toda a gente e uma forma rápida de encontrar e corrigir erros.

Desenvolvimento 6 min de leitura

Se já trabalhou com uma API, um ficheiro de configuração ou uma exportação de dados, já se cruzou com o JSON. Parece simples, mas uma única vírgula fora do sítio torna o ficheiro inteiro inválido e gera uma mensagem de erro enigmática.

Neste guia vai perceber o que é o JSON, que tipos de valor aceita, as regras de sintaxe, os erros mais comuns com exemplos de antes e depois e como validar, formatar e minificar os seus dados em segundos.

Valide e formate o seu JSON agora Cole o seu JSON para encontrar erros, formatar ou minificar. Tudo corre no seu navegador e nada é enviado. Abrir o formatador de JSON

O que é o JSON?

O JSON (JavaScript Object Notation) é um formato de texto leve para guardar e trocar dados. Os dados organizam-se em pares de chave e valor, por exemplo {"nome": "Ana", "idade": 30}. É fácil de ler para pessoas e fácil de interpretar para programas.

Apesar de ter nascido no JavaScript, o JSON não depende de nenhuma linguagem. É o padrão usado pelas APIs web para enviar dados entre servidores e aplicações, e é também muito comum em ficheiros de configuração, registos e exportações.

Os seis tipos de valor

Todos os valores em JSON são de um destes seis tipos:

  • String: texto entre aspas duplas, como "olá".
  • Número: inteiro ou decimal, como 42 ou 3.14, sem aspas.
  • Booleano: true ou false, em minúsculas e sem aspas.
  • Nulo: a palavra null, que significa "sem valor".
  • Array: lista ordenada entre parênteses retos, como [1, 2, 3].
  • Objeto: conjunto de pares chave e valor entre chavetas, como {"cidade": "Porto"}. As chaves são sempre strings.

Os arrays e os objetos podem conter outros arrays e objetos, por isso é possível descrever dados com qualquer profundidade.

As regras de sintaxe a recordar

O JSON é muito mais rígido do que o JavaScript. A maioria dos erros vem de quebrar uma destas regras:

  • As strings e as chaves têm de usar aspas duplas. Não são permitidas aspas simples.
  • Sem vírgula no fim: o último item de um array ou objeto não pode ser seguido de vírgula.
  • Sem comentários: nem // nem /* */ são válidos.
  • Existem apenas os seis tipos: undefined, NaN, Infinity e funções não são válidos.
  • Os pares separam-se por vírgulas e a chave separa-se do valor por dois pontos.
  • Cada chaveta ou parêntese reto aberto precisa do respetivo fecho.

Os erros mais comuns e como os corrigir

Estes cinco deslizes causam a grande maioria das mensagens de "JSON inválido":

  • Vírgula a mais. Antes: {"a": 1, "b": 2,}. Depois: {"a": 1, "b": 2}. Remova a vírgula a seguir ao último item.
  • Aspas simples. Antes: {'nome': 'Ana'}. Depois: {"nome": "Ana"}. Substitua todas as aspas simples por aspas duplas.
  • Chave sem aspas. Antes: {nome: "Ana"}. Depois: {"nome": "Ana"}. Coloque todas as chaves entre aspas duplas.
  • Parêntese reto ou chaveta em falta. Antes: {"itens": [1, 2, 3}. Depois: {"itens": [1, 2, 3]}. Feche todos os arrays e objetos que abrir.
  • Escape errado das aspas. Antes: {"texto": "Ele disse "olá""}. Depois: {"texto": "Ele disse \"olá\""}. As aspas duplas dentro de uma string precisam de uma barra invertida. O mesmo vale para a própria barra invertida, escrita \\.

Atenção também às aspas "inteligentes" coladas de processadores de texto: parecem aspas, mas não são válidas em JSON.

Como ler a mensagem de erro do JSON

A maioria dos interpretadores diz onde se perdeu, com mensagens como "Unexpected token } in JSON at position 25" ou "Expected double-quoted property name at line 3 column 5". A posição é a contagem de carateres desde o início, enquanto a linha e a coluna indicam o ponto exato.

O erro verdadeiro está muitas vezes um pouco antes da posição indicada. Uma chaveta de fecho inesperada costuma indicar uma vírgula a mais mesmo antes dela, e um fim de dados inesperado indica um parêntese reto por fechar. Veja a linha indicada e a anterior.

Como validar, formatar e minificar JSON

  1. Abra o formatador de JSON gratuito. Corre inteiramente no seu navegador, por isso os seus dados não saem do seu dispositivo.
  2. Cole o seu JSON. Se for inválido, a ferramenta mostra o erro com a linha e a coluna para o poder corrigir.
  3. Use a formatação para indentar e tornar legível, ou minifique para remover espaços e reduzir o tamanho antes de enviar.
  4. Copie o resultado. Se alterou um ficheiro e quer ver exatamente o que mudou, compare as duas versões com a ferramenta de diferenças de texto.

JSON vs XML vs YAML

O XML é mais extenso, com etiquetas de abertura e fecho, mas suporta atributos e continua comum em sistemas mais antigos. O YAML é mais limpo para humanos e permite comentários, por isso é popular em ficheiros de configuração, mas a indentação é fácil de errar.

O JSON fica a meio caminho: compacto, sem ambiguidade e suportado por praticamente todas as linguagens, o que o torna a escolha habitual para APIs. A sua principal desvantagem é a ausência de comentários.

Dicas práticas

  • Valide sempre o JSON antes de o enviar ou de o guardar num ficheiro de configuração.
  • Use um editor com realce de sintaxe para JSON, que mostra de imediato aspas e parênteses desequilibrados.
  • Não escreva JSON à mão quando o pode gerar por código: as bibliotecas fazem o escape correto dos carateres.
  • Se um parâmetro de URL transporta JSON, codifique-o antes com o codificador de URL para que os carateres especiais não estraguem o pedido.
  • Nunca coloque palavras-passe ou tokens em JSON colado em ferramentas online que enviam os dados. Prefira ferramentas que funcionam localmente.

Conclusão

O JSON é simples quando se conhecem as regras: seis tipos de valor, aspas duplas, sem vírgula a mais e sem comentários. Quando algo falhar, leia a linha e a coluna do erro, verifique o ponto imediatamente anterior e deixe um validador fazer o trabalho pesado. Alguns segundos num formatador poupam muito tempo de depuração.

Perguntas frequentes

Para que serve o JSON?

Serve para trocar dados entre aplicações, sobretudo APIs web, e para guardar configurações e dados estruturados em ficheiros. Quase todas as linguagens de programação conseguem ler e escrever JSON.

O JSON pode ter comentários?

Não. O JSON padrão não permite comentários. Se precisar de notas, use um campo normal como "comentario" ou um formato como o YAML para ficheiros de configuração.

Porque é que o meu JSON mostra "unexpected token"?

O interpretador encontrou um carácter inesperado, normalmente uma vírgula a mais, aspas simples, uma chave sem aspas ou um parêntese reto em falta. Verifique a posição indicada e a linha imediatamente acima.

Qual é a diferença entre formatar e minificar JSON?

Formatar acrescenta quebras de linha e indentação para facilitar a leitura. Minificar remove todos os espaços desnecessários para reduzir o ficheiro. Os dados mantêm-se exatamente iguais.

É seguro usar um formatador de JSON online?

É seguro quando a ferramenta funciona no navegador e não envia o conteúdo para um servidor. O nosso formatador de JSON processa tudo localmente no seu dispositivo.

Ferramentas gratuitas referidas neste artigo

Continue a ler

Todos os artigos