Se você já abriu uma resposta de API, um arquivo de configuração ou o retorno de uma ferramenta de IA, provavelmente viu um texto cheio de chaves, colchetes e aspas. Era JSON. Aprender a lê-lo é uma das habilidades mais úteis para quem programa ou automatiza, e leva menos de uma hora.
O que é JSON
JSON (JavaScript Object Notation) é um formato de texto para guardar e trocar dados. É leve, fácil de ler por humanos e fácil de processar por programas, e por isso virou o padrão das APIs (veja o que é API e para que serve).
Pense em um objeto que descreve um cliente:
- o objeto começa com uma chave aberta e termina com uma chave fechada;
- dentro dele, cada informação é um par: o nome entre aspas duplas, dois-pontos e o valor;
- os pares são separados por vírgulas.
Em palavras: um objeto com “nome” igual a “Ana”, “idade” igual a 34, “ativo” igual a verdadeiro e “telefones” igual a uma lista com dois números.
Os blocos de construção
O JSON tem poucos elementos:
- Objeto: conjunto de pares nome e valor, entre chaves. Representa uma “coisa”, como um cliente ou um produto.
- Lista (array): sequência de valores entre colchetes, separados por vírgula. Representa vários itens, como todos os pedidos.
- Texto (string): sempre entre aspas duplas. Aspas simples não valem.
- Número: inteiro ou decimal, sem aspas, com ponto como separador decimal.
- Booleano: true ou false, em minúsculas e sem aspas.
- Nulo: null, indica ausência de valor.
Esses elementos podem se aninhar: um objeto pode conter uma lista de objetos, que contêm listas, e assim por diante. Ler JSON complexo é só seguir os níveis, de fora para dentro.
Como ler um JSON complicado
Quando o texto é longo, estas dicas ajudam:
- Formate o JSON. Ferramentas online e editores de código têm a função de “formatar” ou “embelezar”, que quebra linhas e recua cada nível. Se o JSON contém dados de clientes, prefira um editor local em vez de colar em sites de terceiros.
- Identifique o que abre e fecha. Chaves indicam objeto, colchetes indicam lista.
- Procure o campo que importa. Em respostas grandes, muitas informações são irrelevantes para você.
- Siga o caminho. “O preço do primeiro item do pedido” é: objeto, campo itens, primeira posição da lista, campo preço.
O VS Code, por exemplo, formata e acusa erros de JSON (veja configurar o VS Code).
JSON em Python e JavaScript
As duas linguagens têm suporte pronto:
- Python: o módulo json tem json.loads (texto para estrutura de dados), json.load (de um arquivo), json.dumps (estrutura para texto) e json.dump (para arquivo). Objetos viram dicionários, listas viram listas.
- JavaScript: JSON.parse converte texto em objeto, e JSON.stringify converte objeto em texto.
Depois de convertido, você acessa os campos pelo nome. Em Python, por exemplo, o campo nome de um dicionário chamado cliente é acessado como cliente seguido do nome entre colchetes e aspas.
Se você está começando a praticar, o artigo Python para iniciantes é um bom complemento.
Erros comuns de sintaxe
O JSON é rigoroso. Um caractere fora do lugar invalida tudo. Os erros mais frequentes:
- Vírgula sobrando no final do último item de um objeto ou lista.
- Falta de vírgula entre dois itens.
- Aspas simples no lugar das duplas.
- Nomes sem aspas, como em objetos JavaScript, que aceitam isso (JSON não).
- Comentários, que o formato não permite.
- Aspas ou barras sem escape dentro de textos. Uma aspa dupla dentro de um texto precisa ser escrita com uma barra invertida antes.
- Valores como True ou None, que são de Python. Em JSON são true e null.
- Chaves ou colchetes não fechados.
Mensagens como “Unexpected token” ou “Expecting property name” indicam a posição do problema. A linha e a coluna informadas geralmente apontam para onde procurar, e o erro real pode estar um pouco antes. Mais dicas em como ler mensagens de erro e depurar código.
Boas práticas ao criar o seu JSON
- Use nomes consistentes para os campos (sempre minúsculas ou sempre o mesmo padrão).
- Escolha o tipo certo: número como número (34) e não como texto (“34”).
- Para datas, adote um formato padrão e fixo, como ano-mês-dia.
- Evite aninhar além do necessário.
- Não guarde segredos em arquivos JSON versionados (veja variáveis de ambiente e arquivo .env).
- Valide o JSON antes de usar, sobretudo se vem de fora: nunca confie que os campos esperados existem.
Um exemplo para treinar a leitura
Imagine um pedido em JSON, descrito em palavras: um objeto com o número do pedido, os dados do cliente (um objeto interno com nome e e-mail), uma lista de itens (cada item com produto, quantidade e preço) e o status do pagamento.
Para saber o nome do segundo item, você segue o caminho: pedido, lista de itens, posição 1 (a contagem começa no zero), campo produto. Para saber o e-mail, vai ao objeto do cliente e lê o campo e-mail.
Treine fazendo esse tipo de perguntas com respostas reais de APIs. Em poucas tentativas, você passa a bater o olho numa estrutura e saber onde cada informação está.
JSON e IA
Muitas APIs de IA permitem pedir respostas em JSON, o que facilita usar o resultado em código. Mesmo assim, valide: o modelo pode devolver um campo faltando ou texto extra. Em integrações de produção, trate o caso de resposta inválida e tente novamente, e veja o panorama de APIs de IA para iniciantes.
Treine abrindo um JSON de verdade: baixe a resposta de uma API pública sem chave, formate no editor e tente descobrir onde está cada informação. Depois de ler alguns, a estrutura passa a parecer natural.