O que é JSON e como se usa
O JSON (JavaScript Object Notation) é o formato que move boa parte da web em português hoje. Quando abre o app do Itaú, acompanha um pedido no Mercado Livre ou consulta o saldo do Multibanco pelo MB WAY, é quase certo que existe um pequeno documento JSON a viajar entre o seu telemóvel e um servidor.
Este guia foi pensado para que perceba o JSON sem rodeios: o que é, como se escreve, que erros toda a gente comete no início e como validar em segundos.
Uma definição sem jargão
O JSON é um formato de texto para representar dados estruturados. Surgiu a partir da sintaxe de objetos do JavaScript, mas hoje é entendido por todas as linguagens sérias: Python, Java, PHP, Ruby, C#, Go, Rust e claro JavaScript.
A ideia é simples: pares "chave": valor, agrupados entre chavetas. Um produto de loja online ficaria assim:
{ "id": 12345, "nome": "T-shirt em algodão", "tamanhosDisponiveis": ["S", "M", "L"], "stock": 42, "emPromocao": true }
Sem tags como em XML, sem separadores estranhos. Apenas chaves, dois pontos e valores. Foi por isso que o JSON substituiu o XML para a maior parte das trocas de dados.
Os tipos de dados aceites
O JSON só conhece seis tipos de valor: cadeia de texto entre aspas duplas, número (sem distinção entre inteiro e decimal), booleano (true ou false), null para ausência, array entre parênteses retos e objeto entre chavetas. Mais nada.
Não existe tipo data nativo. Para guardar a data de um pedido, use uma string no formato ISO 8601: "2025-03-14T18:30:00Z". Também não há comentários. Se vir comentários // ou /* */ num ficheiro .json, é na verdade JSON5 ou JSONC, variantes que nem todas as bibliotecas aceitam.
Os erros típicos de quem começa
O mais comum é usar aspas simples em vez de duplas. O JSON exige aspas duplas, tanto nas chaves como nos valores de texto. Outro clássico é deixar uma vírgula a sobrar depois do último elemento de um array ou objeto. Em JSON padrão isso quebra o parsing.
As chaves vão sempre entre aspas. Em JavaScript pode escrever { nome: "Mariana" } mas em JSON tem de ser { "nome": "Mariana" }. Para números muito grandes, como um NIF ou um CPF de identificação interna, prefira string: inteiros acima de 2^53 perdem precisão.
Validar JSON em segundos
Quando uma API devolve um erro críptico, a culpa costuma ser de uma vírgula mal colocada. A forma rápida de a encontrar é colar o JSON num validador. O nosso formatador online indica a linha exata do problema e reescreve o documento com indentação legível.
Na linha de comandos, o jq é a referência: jq . pedido.json deteta problemas de sintaxe e mostra o resultado a cores. Em Python existe o json.tool, e em Node o JSON.parse lança uma exceção a apontar o caractere problemático.
JSON e desempenho em apps reais
Um JSON grande não sai de graça. Se a sua API devolve dez mil produtos de uma vez, o browser tem de fazer o parsing de tudo antes de mostrar fosse o que fosse. Vale a pena paginar (?pagina=1&porPagina=50), ativar gzip ou brotli no servidor e devolver apenas os campos necessários ao cliente.
Para dados muito repetitivos, formatos como NDJSON (um JSON por linha) ou MessagePack podem ser mais eficientes. Mas para 95 % dos casos, JSON bem estruturado e gzip ativo no servidor chega e sobra.
Ferramentas relacionadas
Perguntas frequentes
- Qual a diferença entre JSON e objeto JavaScript?
- Um objeto JavaScript vive em memória e pode conter funções, datas ou referências. JSON é apenas texto que representa dados: sem funções, sem data nativa, sem undefined. Para enviar um objeto pela rede, converte-se com JSON.stringify.
- JSON é sensível a maiúsculas?
- Sim. "Nome" e "nome" são chaves distintas. A convenção no ecossistema JavaScript é camelCase ("dataCriacao"). Em Python vê-se muito snake_case ("data_criacao"). Escolha uma convenção e mantenha-a no projeto inteiro.
- Como guardo acentos e caracteres especiais como "ç" ou "ã"?
- O JSON aceita UTF-8 nativamente, por isso pode escrever "São Paulo", "ação" ou "informação" sem rodeios. Por vezes vê sequências como \u00e3: é a forma escapada, significa o mesmo. Verifique que o seu servidor envia Content-Type: application/json; charset=utf-8.
- Posso usar JSON para configurar a minha aplicação?
- Pode, mas pondere o que precisa. Se quer comentários ou variáveis, YAML ou TOML são mais confortáveis. Para pares chave-valor simples, JSON funciona perfeitamente e qualquer linguagem o lê sem dependências.
- Existe um tamanho máximo recomendado?
- Não há limite oficial. Acima de 1 MB, o parsing começa a notar-se em telemóveis modestos. Se a resposta passar dessa marca, quase sempre vale a pena paginar ou devolver apenas os campos efetivamente usados pelo cliente.