JavaScript JSON

JavaScript Object Notation (JSON) é a espinha dorsal da troca de dados na web. Quase toda API que você consome retorna JSON, todo arquivo de configuração que você lê provavelmente é JSON, e toda vez que o navegador se comunica com um servidor, JSON costuma ser o formato utilizado. Este guia cobre tudo o que você precisa para trabalhar com JSON de forma segura em JavaScript: a sintaxe, os dois métodos principais (JSON.parse e JSON.stringify), como formatar e filtrar a saída, como lidar com datas e cópias profundas, e as armadilhas que causam problemas em produção.

O que é JSON e por que ele é importante

JSON é um formato de dados leve, baseado em texto, fácil de ler e escrever por humanos e fácil de analisar e gerar por máquinas. Ele é independente de linguagem — mesmo que sua sintaxe seja derivada do JavaScript (Standard ECMA-262), praticamente todas as linguagens (Python, Java, C#, Go, Rust, PHP) conseguem ler e escrever JSON. Essa universalidade é exatamente o motivo pelo qual ele se tornou o formato padrão para REST APIs, arquivos de configuração (package.json, tsconfig.json) e localStorage.

O ponto-chave a entender: JSON é uma string, não um object. Uma string JSON só se torna um objeto JavaScript utilizável após você analisá-la (parse), e um objeto JavaScript só se torna JSON após você serializá-lo (stringify). A maior parte do trabalho com JSON consiste em transitar entre esses dois estados.

Sintaxe básica do JSON

A sintaxe JSON é um subconjunto estrito da sintaxe de literais de object do JavaScript:

• Os dados são escritos como pares "chave": valor
• Os pares são separados por vírgulas
• Chaves {} delimitam objetos e colchetes [] delimitam arrays
• As chaves devem ser strings com aspas duplas (aspas simples e chaves sem aspas são inválidas)
• Os valores podem ser string, número, boolean, null, object ou array — mas não undefined, uma função ou um Date

{
  "name": "John",
  "age": 30,
  "isDeveloper": true,
  "languages": ["JavaScript", "Python", "Rust"]
}

Analisando JSON com JSON.parse()

JSON.parse() converte uma string JSON em um objeto JavaScript (ou array, número etc.) que você pode ler e manipular. Em código real — especialmente quando o JSON vem de uma requisição de rede ou de entrada do usuário — sempre envolva-o em um try...catch, pois JSON malformado lança um SyntaxError.

Acessando dados aninhados

O JSON analisado se comporta como qualquer outro object, portanto você acessa valores aninhados com notação de ponto ou de colchetes. Essa é a operação mais comum ao lidar com uma resposta de API.

Transformando valores com um reviver

JSON.parse() aceita uma função reviver opcional como segundo argumento. Ela é chamada para cada par chave/valor, e o que ela retornar se torna o valor final — muito útil para converter tipos durante a análise. Um uso clássico é restaurar objetos Date (JSON não tem tipo de data, portanto datas chegam como strings).

Serializando objetos com JSON.stringify()

JSON.stringify() faz o inverso: converte um valor JavaScript em uma string JSON, pronta para ser enviada pela rede ou salva em armazenamento.

Formatação com indentação

O terceiro argumento controla o espaçamento. Passe um número (espaços) ou uma string para produzir JSON legível e indentado — útil para logs, arquivos de configuração e depuração.

Filtrando propriedades com um replacer

O segundo argumento é um replacer. Como um array de chaves, ele define uma lista branca de quais propriedades manter — uma maneira rápida de remover campos sensíveis, como senhas, antes de enviar dados.

Como uma função, o replacer é chamado para cada chave e permite transformar ou descartar valores. Retornar undefined a partir dele omite aquela propriedade.

Serialização personalizada com toJSON

Você pode controlar como um object específico é serializado adicionando um método toJSON() a ele. Quando JSON.stringify() encontra um object com esse método, chama toJSON() e serializa o que ele retornar. (É exatamente assim que objetos Date produzem strings ISO — eles têm um toJSON embutido.)

O que o stringify descarta silenciosamente

JSON.stringify() é intencionalmente com perda de dados. Conhecer o que ele ignora evita bugs confusos:

• Valores undefined, funções e Symbol são omitidos de objetos (e se tornam null dentro de arrays).
• Objetos Date se tornam strings ISO (via seu toJSON).
• NaN e Infinity se tornam null.
• BigInt lança um TypeError.
• Referências circulares lançam um TypeError.

Técnicas avançadas e padrões comuns

Além dos dois métodos principais, o trabalho diário com JSON envolve cópias profundas, manipulação de datas e processamento de arrays de registros.

Cópias profundas de objetos

O truque JSON.parse(JSON.stringify(obj)) cria uma cópia profunda — um clone cujos objetos aninhados são totalmente independentes do original, de modo que modificar um nunca afeta o outro.

É rápido e independente de dependências, mas herda todas as limitações do stringify: descarta funções, undefined e Symbols, converte Dates em strings e lança exceção em referências circulares. Para um clone fiel, prefira o built-in structuredClone(), que lida com datas, maps, sets e ciclos.

Trabalhando com datas

JSON não possui tipo de data, portanto datas são transmitidas como strings ISO 8601. JSON.stringify as escreve automaticamente, mas ao analisar você recebe de volta uma string simples — você deve reconstruir o Date por conta própria, seja com new Date(...) ou com um reviver (mostrado anteriormente).

Processando arrays de registros

As respostas de API geralmente são arrays de objetos. Após a análise, os métodos padrão de array (forEach, map, filter) fazem o restante.

JSON e o navegador: fetch e localStorage

Dois lugares onde o JSON aparece no dia a dia:

• fetch: response.json() lê o corpo e o analisa para você, portanto raramente você chama JSON.parse diretamente em um resultado de fetch — const data = await response.json();. Consulte o guia da Fetch API.
• localStorage: ele armazena apenas strings, portanto serialize ao salvar e analise ao recuperar: localStorage.setItem('user', JSON.stringify(user)) e depois JSON.parse(localStorage.getItem('user')).

Conclusão

JSON é o formato que você mais utilizará como desenvolvedor JavaScript, e tudo se resume a dois métodos: JSON.parse() para converter uma string em um valor utilizável, e JSON.stringify() para converter um valor de volta em uma string. Adicione os argumentos reviver e replacer para conversão de tipos e filtragem, indentação para saída legível, e toJSON para serialização personalizada, e você poderá lidar com quase qualquer tarefa de troca de dados.

Tenha em mente os casos extremos com perda de dados — undefined/funções descartados, datas convertidas em string e erros de referência circular — e recorra ao structuredClone() quando precisar de uma cópia verdadeira em vez de uma ida e volta pelo JSON. Com essas ferramentas, você pode mover dados com confiança entre sua aplicação, o servidor e o armazenamento do navegador.

Prática