10 de jul. de 2026

Como ler uma resposta JSON: guia prático sem código

Resposta do ViaCEP organizada em campos legíveis após uma consulta — A mesma resposta pode ser apresentada em campos legíveis; no JSON original, cada rótulo corresponde a uma chave e cada informação exibida corresponde ao seu valor.

O que é JSON?

JSON é um formato de texto usado para representar e trocar dados estruturados. A sigla vem de JavaScript Object Notation, mas o formato não pertence apenas ao JavaScript: serviços e programas escritos em várias linguagens conseguem ler e gerar JSON.

Uma resposta JSON não é uma página pronta. Ela descreve dados com pontuação previsível, como nomes, números, estados e listas. O navegador pode exibir o texto com recuos e cores ou em uma linha contínua; a estrutura continua a mesma.

Também existe uma diferença importante entre texto JSON e objeto de um programa. O JSON viaja ou fica salvo como texto. Um programa analisa esse texto e o converte para uma estrutura própria antes de consultar os valores.

A pontuação que orienta a leitura

Símbolo	Função	Como ler
`{ }`	Delimita um objeto	Conjunto de chaves e valores
`[ ]`	Delimita um array	Lista ordenada de itens
`:`	Separa chave e valor	“Esta chave possui este valor”
`,`	Separa membros ou itens	Fim de um valor; começo do próximo
`" "`	Delimita texto	Chaves e strings usam aspas duplas

Observe este trecho fictício:

{
  "produto": "Caderno",
  "preco": 24.9,
  "disponivel": true
}

produto, preco e disponivel são chaves. Depois de cada dois-pontos vem o valor. O nome do produto é texto, o preço é número e a disponibilidade é um booleano.

Os seis tipos de valor do JSON

A RFC 8259 divide os valores em quatro tipos primitivos e dois estruturados:

Tipo	Exemplo	Significado
String	`"Caderno"`	Texto entre aspas duplas
Número	`24.9`	Valor numérico sem aspas
Booleano	`true`	Verdadeiro ou falso, sempre em minúsculas
Nulo	`null`	Ausência intencional de valor
Objeto	`{ "uf": "GO" }`	Chaves associadas a valores
Array	`["azul", "verde"]`	Lista ordenada de valores

As aspas mudam o tipo. 42 é número; "42" é texto. true é booleano; "true" é apenas uma sequência de quatro letras. Essa diferença afeta filtros, contas e comparações.

Primeiro exemplo: um objeto com dados aninhados

JSONPlaceholder oferece registros fictícios para treinamento. Abra o usuário de identificador 1:

Abrir o usuário fictício no JSONPlaceholder

A resposta completa possui nome, usuário, e-mail, endereço e empresa. Este recorte conserva a estrutura necessária para a leitura:

{
  "id": 1,
  "name": "Leanne Graham",
  "address": {
    "street": "Kulas Light",
    "city": "Gwenborough",
    "geo": {
      "lat": "-37.3159",
      "lng": "81.1496"
    }
  }
}

A raiz começa com {, portanto é um objeto. id contém um número e name contém uma string. Já address abre outro objeto, porque seu valor começa com uma nova chave.

Para encontrar a cidade, siga o caminho address.city: primeiro localize address; dentro dele, procure city. Para chegar à latitude, o caminho tem três níveis: address.geo.lat.

Os valores de latitude e longitude aparecem entre aspas nesse serviço. Isso significa que a resposta os representa como texto, mesmo que os caracteres pareçam um número. Leia o tipo que o JSON entrega, não o tipo que você esperava encontrar.

Segundo exemplo: objeto que contém uma lista

A busca da Open Library devolve metadados e uma lista de obras. Abra a consulta limitada a dois resultados de “Dom Casmurro”:

Abrir a busca de Dom Casmurro na Open Library

Na consulta verificada em 10 de julho de 2026, o formato resumido foi este:

{
  "numFound": 43,
  "docs": [
    {
      "author_name": ["Machado de Assis"],
      "first_publish_year": 1900,
      "key": "/works/OL1003040W",
      "title": "Dom Casmurro"
    },
    {
      "author_name": ["Machado de Assís"],
      "first_publish_year": 2013,
      "key": "/works/OL39781935W",
      "title": "Dom Casmurro"
    }
  ]
}

numFound informa quantos registros corresponderam à pesquisa no momento da consulta e pode mudar com atualizações do catálogo. docs começa com [, então contém uma lista. Cada item da lista começa com {, porque cada resultado é um objeto com seus próprios campos.

Para localizar o título do primeiro resultado, siga docs[0].title. Para localizar o primeiro nome de autor desse mesmo resultado, siga docs[0].author_name[0].

Por que o primeiro índice é zero?

Ao descrever um caminho, listas normalmente usam índices a partir de zero:

docs[0]: primeiro item;
docs[1]: segundo item;
docs[2]: terceiro item.

Esse detalhe explica muitos erros de leitura. Se a resposta mostra dois itens, os índices válidos são 0 e 1. O índice 2 procuraria um terceiro resultado que não veio naquela lista.

A ordem importa em arrays. Em objetos, o significado deve vir das chaves, não da posição visual. Mesmo que name apareça antes de address, um programa deve consultar o nome da chave e não contar linhas.

`null`, vazio, lista vazia e campo ausente

Quatro aparências parecidas podem comunicar estados diferentes:

"complemento": null: a chave existe, mas não possui valor definido;
"complemento": "": a chave contém uma string vazia;
"telefones": []: a chave contém uma lista sem itens;
chave ausente: a resposta não enviou aquele campo.

Não transforme automaticamente todos esses casos em “erro”. Uma fonte pode usar null para informação desconhecida, lista vazia para nenhum resultado e ausência de chave para campo não aplicável. A documentação do serviço deve explicar o contrato.

false também não significa ausência. É uma resposta booleana explícita. Da mesma forma, 0 é um número válido e não deve ser confundido com campo vazio.

JSON formatado e JSON minificado têm o mesmo conteúdo

Recuos, quebras de linha e espaços fora das strings servem para leitura humana. Este JSON formatado:

{
  "nome": "Ana",
  "ativo": true
}

representa os mesmos dados que a versão minificada:

{"nome":"Ana","ativo":true}

Um formatador reorganiza a apresentação; não deveria alterar chaves ou valores. Minificação faz o caminho inverso e remove espaços desnecessários para reduzir o texto.

Método de leitura em seis passos

Defina a pergunta: procure “qual é a cidade?” em vez de tentar entender todos os campos.
Identifique a raiz: veja se a resposta começa com objeto { ou lista [.
Localize a chave: encontre um nome relacionado à pergunta, como city, title ou status.
Observe o tipo: confira se o valor é texto, número, booleano, nulo, objeto ou lista.
Desça um nível por vez: registre mentalmente o caminho, como docs[0].title.
Confirme o contexto: leia metadados, unidade, data, página e documentação antes de usar o valor.

Em respostas grandes, use a busca do navegador para localizar a chave exata. Pesquisar pelo valor pode encontrar várias ocorrências iguais; a chave costuma indicar melhor o contexto.

Erros de sintaxe que tornam o JSON inválido

Aspas simples: JSON exige aspas duplas em chaves e strings.
Chave sem aspas: { nome: "Ana" } parece JavaScript, mas não é JSON válido.
Vírgula final: não pode haver vírgula depois do último membro ou item.
Comentário: // observação e /* observação */ não fazem parte do formato JSON.
Maiúsculas em literais: os valores válidos são true, false e null, em minúsculas.
Número incompatível: NaN e Infinity não são números JSON válidos.
Fechamento fora de ordem: cada { fecha com } e cada [ fecha com ].

Chaves duplicadas também devem ser evitadas. A RFC informa que programas podem reagir de maneiras diferentes: alguns conservam apenas o último valor, outros falham e outros mostram todas as repetições.

JSON válido não significa dado verdadeiro

Um validador confirma pontuação e tipos, não a qualidade da informação. {"temperatura":999} pode ser JSON sintaticamente válido e ainda representar um valor errado, uma unidade desconhecida ou um sensor com defeito.

Antes de confiar no conteúdo, confirme quem mantém a fonte, quando ocorreu a atualização, qual unidade foi usada, que região está coberta e se o campo pode ficar incompleto. Em respostas paginadas, confira se você recebeu todos os itens ou apenas a primeira página.

O guia de APIs públicas para navegador oferece respostas reais para praticar. O diretório de APIs do DexBase ajuda a encontrar outras fontes, sempre com a recomendação de conferir a documentação original.

Como usar um visualizador JSON com segurança

Uma visualização em árvore facilita expandir objetos e recolher listas. Ela é útil quando a resposta possui centenas de linhas, mas não cole qualquer conteúdo em uma ferramenta externa.

Remova tokens, senhas, documentos, e-mails e dados pessoais.
Prefira o formatador integrado ao navegador ou uma ferramenta executada localmente para material confidencial.
Confira a política da ferramenta antes de enviar arquivos.
Não suponha que “gratuito” ou “sem cadastro” significa que o texto nunca será transmitido ou registrado.

Se o JSON já aparece formatado na aba, talvez você nem precise copiá-lo. Use a busca do navegador e siga o caminho das chaves no próprio retorno.

Perguntas frequentes

JSON e JavaScript são a mesma coisa?

Não. JSON é um formato textual de dados inspirado na sintaxe de objetos JavaScript. Ele possui regras mais restritas, como aspas duplas obrigatórias nas chaves e ausência de funções, comentários e valores como undefined.

Um arquivo JSON pode começar com uma lista?

Sim. Um array na raiz é JSON válido. Nesse caso, a leitura começa por um índice, como [0], e depois segue pelas chaves do objeto contido naquele item.

Por que o mesmo campo aparece várias vezes?

Objetos diferentes dentro de uma lista podem repetir a mesma chave, como title em cada livro. Isso é normal. O caminho completo, incluindo o índice, identifica de qual item veio o valor.

Como abrir um arquivo `.json`?

Como é texto, o arquivo pode ser aberto em navegador ou editor de texto. Um visualizador em árvore melhora a navegação. Se o conteúdo for sensível, evite enviá-lo a serviços online desconhecidos.