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 JSONO 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
- Abra o formatador de JSON gratuito. Corre inteiramente no seu navegador, por isso os seus dados não saem do seu dispositivo.
- Cole o seu JSON. Se for inválido, a ferramenta mostra o erro com a linha e a coluna para o poder corrigir.
- Use a formatação para indentar e tornar legível, ou minifique para remover espaços e reduzir o tamanho antes de enviar.
- 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
- Como Criar uma Palavra-passe ForteTamanho, aleatoriedade e unicidade: as regras simples que realmente protegem as suas contas, e como cumpri-las sem ter de decorar nada.
- Técnica Pomodoro: guia completoTrabalhe em blocos de 25 minutos de concentração com pausas curtas. Veja como o método funciona, como começar hoje e como adaptá-lo à sua rotina.
- O que é um hash? MD5, SHA-256 e para que servemUm hash é uma impressão digital curta de qualquer dado. Veja como funciona, que algoritmos usar e como verificar ficheiros e proteger palavras-passe.