O que é JSON: estrutura, tipos e erros comuns

JSON é o formato de dados mais usado na web moderna. APIs trocam respostas em JSON, aplicativos guardam configurações em JSON, bancos de dados armazenam documentos em JSON e sistemas diferentes conversam entre si em JSON o tempo todo. Entender sua estrutura, seus tipos de valor e os erros de sintaxe mais comuns evita boa parte das falhas de integração do dia a dia. Neste guia você vê o que é JSON, a sintaxe completa com exemplos de código, a diferença entre JSON e objeto JavaScript, o que o formato não permite, como ler e gerar JSON em várias linguagens e como tratar datas, números grandes, validação e segurança. Para formatar e validar na hora, use o formatador e validador de JSON.

O que é JSON

JSON (JavaScript Object Notation) é um formato de texto leve para representar e transmitir dados estruturados. Apesar do nome, é independente de linguagem: a sintaxe nasceu de um subconjunto do JavaScript, mas praticamente toda linguagem moderna sabe ler e gerar JSON de forma nativa ou por biblioteca padrão. O formato foi popularizado por Douglas Crockford no início dos anos 2000 e hoje é descrito por duas especificações equivalentes, a ECMA-404 e a RFC 8259, além da referência prática do MDN.

Um documento JSON é apenas texto. No topo dele fica um único valor, que na prática quase sempre é um objeto ou um array, mas pode ser também uma string, um número, um boolean ou null. Essa é uma diferença sutil em relação a versões antigas do formato: desde a RFC 8259 e a ECMA-404, qualquer um dos seis tipos de valor pode ficar sozinho no topo, então 42 ou "texto" também são JSON válido. O tipo de mídia oficial usado no transporte é application/json.

Por que o JSON virou o formato universal de dados

Três características explicam a adoção. A primeira é a leveza: o JSON tem pouca cerimônia de sintaxe, então uma resposta de API em JSON costuma ser bem menor que a mesma informação em XML. A segunda é a legibilidade: uma pessoa consegue ler e editar um JSON sem ferramenta, o que ajuda em depuração e em arquivos de configuração. A terceira é o mapeamento direto: objeto vira dicionário, array vira lista, e os tipos escalares batem com os tipos primitivos de quase toda linguagem.

Na prática, você encontra JSON em três frentes. Em APIs, é o corpo padrão das respostas e requisições REST. Em configuração, arquivos como package.json e tsconfig.json descrevem projetos inteiros. Em armazenamento, bancos de dados de documentos guardam registros como JSON e sistemas de log gravam eventos em JSON. Quando precisa sair do JSON para outro formato, o guia de conversão entre CSV, JSON, YAML e XML mostra as equivalências.

A sintaxe do JSON em poucas regras

A gramática do JSON é curta e sem exceções, o que torna a validação objetiva. As regras que valem para todo documento são estas:

• Um objeto fica entre chaves e contém pares de "chave": valor separados por vírgula. A chave é sempre uma string com aspas duplas, seguida de dois-pontos.
• Um array fica entre colchetes e lista valores separados por vírgula, na ordem em que aparecem.
• Uma string fica entre aspas duplas. Aspas simples não são permitidas.
• Não pode haver vírgula depois do último item de um objeto ou array.
• Espaços, tabulações e quebras de linha entre os elementos são ignorados. Você pode indentar para ler melhor ou remover tudo para transmitir, sem mudar o significado.

Dentro de uma string, alguns caracteres precisam de escape com barra invertida: aspas duplas (\"), a própria barra invertida (\\), quebra de linha (\n), tabulação (\t) e o formato unicode \uXXXX. Isso permite guardar aspas e quebras de linha dentro do texto sem quebrar o documento.

Os seis tipos de valor

Todo valor em JSON pertence a um destes seis tipos. Objetos e arrays são containers e podem guardar qualquer um dos outros, inclusive outros objetos e arrays, o que permite aninhar estruturas complexas.

Repare no que falta nessa lista: não há tipo de data, tipo de dinheiro nem inteiro separado de decimal. Número é número. Data é string. Valores monetários costumam ir como número ou como string, conforme a necessidade de precisão. Essa simplicidade é intencional e é o que faz o formato ser interoperável.

Objetos, arrays e aninhamento

Um objeto simples descrevendo uma pessoa combina vários tipos. Cada par é separado por vírgula, o objeto fica entre chaves, as chaves vêm entre aspas duplas e não pode haver vírgula depois do último par:

{
  "nome": "Ana Souza",
  "idade": 30,
  "ativo": true,
  "tags": ["dev", "design"],
  "telefone": null
}

A força do JSON aparece no aninhamento. Um objeto pode conter outros objetos e arrays de objetos, o que descreve estruturas do mundo real como um pedido com cliente e itens:

{
  "pedido": 4837,
  "cliente": {
    "nome": "Ana Souza",
    "email": "ana@exemplo.com"
  },
  "itens": [
    { "produto": "Teclado", "preco": 199.9, "quantidade": 1 },
    { "produto": "Mouse", "preco": 89.5, "quantidade": 2 }
  ],
  "pago": true,
  "cupom": null
}

Aqui cliente é um objeto, itens é um array de objetos e cupom é null. Não há limite formal de profundidade, embora parsers reais imponham um teto para evitar consumo excessivo de memória.

O que o JSON não permite

Boa parte dos erros vem de escrever no JSON algo que é válido em JavaScript, mas não no formato. O JSON padrão não aceita:

• Comentários de qualquer tipo (// ou /* */).
• Vírgula sobrando (trailing comma) depois do último item.
• Aspas simples em strings ou chaves. Só aspas duplas.
• Chaves sem aspas, como idade: 30.
• Funções e o valor undefined, que existem em JavaScript mas não no JSON.
• NaN e Infinity: não são números válidos em JSON.
• Números com zero à esquerda (007), sinal de mais na frente (+5) ou notação hexadecimal.

Este exemplo reúne os erros mais frequentes. Nenhuma das linhas comentadas passa num validador de JSON:

{
  'nome': 'Ana',      // aspas simples: invalido
  idade: 30,          // chave sem aspas: invalido
  "saldo": .5,        // falta o zero antes do ponto: invalido
  "tags": ["dev",],   // virgula sobrando: invalido
  // este comentario tambem e invalido
}

Os erros de sintaxe mais comuns e o "Unexpected token"

Quando o parser encontra algo fora da gramática, ele lança um erro que no JavaScript costuma começar com Unexpected token seguido do caractere e da posição. A mensagem indica onde a leitura travou, que nem sempre é onde está o erro de fato: um objeto que ficou sem fechar só é notado quando o parser chega ao fim do texto. A lista abaixo cobre as causas mais comuns:

• Usar aspas simples em vez de aspas duplas.
• Deixar vírgula depois do último item de um objeto ou array.
• Esquecer de fechar uma chave, um colchete ou uma aspa.
• Escrever chaves sem aspas.
• Colocar comentários, que não existem no JSON padrão.
• Colar um valor a mais ou de menos, deixando duas vírgulas seguidas ou um par sem valor.

Um formatador ajuda a achar o problema porque indenta a estrutura e aponta a linha exata. É mais rápido colar o texto no validador de JSON do que caçar a vírgula no olho. Para comparar duas versões de um mesmo documento e ver o que mudou, o comparador de texto e o guia de comparar textos e JSON mostram as diferenças lado a lado.

JSON x objeto JavaScript

Os dois parecem iguais, e é justamente aí que mora a confusão. Um objeto JavaScript é uma estrutura viva na memória do programa; um JSON é texto que representa dados. O JSON é estrito: chaves sempre com aspas duplas, sem funções, sem comentários, sem undefined e sem vírgula final. O objeto JavaScript é flexível: aceita aspas simples, chaves sem aspas, métodos, comentários e o valor undefined.

A consequência prática é que copiar um objeto direto do código e tratar como JSON quase sempre gera erro de sintaxe. E, no caminho contrário, ao transformar um objeto em JSON, tudo que não existe no formato desaparece: propriedades com valor undefined e funções são descartadas, e uma data vira string. Todo JSON válido consegue ser lido como valor JavaScript, mas nem todo objeto JavaScript é um JSON válido.

JSON x XML

Antes do JSON dominar a web, o XML era o formato padrão de troca de dados. Os dois representam estruturas, mas com filosofias diferentes. A tabela resume a comparação para a mesma informação:

Nenhum dos dois é melhor em absoluto. O JSON venceu nas APIs web pela leveza e pelo encaixe com JavaScript. O XML segue forte onde documentos e validação por esquema pesado importam mais que o tamanho. Para converter entre eles rapidamente, use o conversor de dados.

Como ler e gerar JSON: parse e stringify

Trabalhar com JSON envolve dois movimentos: transformar texto em estrutura de dados (parse) e transformar estrutura em texto (stringify). No JavaScript, isso é feito por JSON.parse e JSON.stringify:

const texto = '{"nome":"Ana","idade":30}';

const obj = JSON.parse(texto);       // texto -> objeto
console.log(obj.nome);               // "Ana"

const devolta = JSON.stringify(obj); // objeto -> texto
// '{"nome":"Ana","idade":30}'

// terceiro argumento de stringify indenta a saida:
JSON.stringify(obj, null, 2);

Toda linguagem de porte tem os equivalentes. Em Python, são json.loads e json.dumps do módulo padrão; para aprender a lidar com esses dados em código, veja o material de Python e o guia sobre algoritmos. Em PHP existem json_decode e json_encode; em Java, bibliotecas como Jackson e Gson. O conceito é sempre o mesmo: um lado serializa para texto, o outro desserializa de volta para objeto.

Datas em JSON: a convenção ISO 8601

Como o JSON não tem tipo de data, cada sistema precisa combinar como representar tempo. A convenção consolidada é a string no formato ISO 8601, com data, hora e fuso, por exemplo 2026-06-02T10:00:00Z (o Z indica UTC). Ao serializar, o JavaScript já converte um objeto de data para ISO 8601 automaticamente. Ao ler de volta, porém, o valor continua sendo texto:

JSON.stringify({ criado: new Date() });
// '{"criado":"2026-06-02T10:00:00.000Z"}'

const dado = JSON.parse('{"criado":"2026-06-02T10:00:00.000Z"}');
typeof dado.criado; // "string", nao "object"
// e preciso converter na mao: new Date(dado.criado)

Por isso a documentação da API precisa dizer em que formato as datas chegam. ISO 8601 é a escolha segura porque é sem ambiguidade e ordenável como texto. Para trabalhar com marcas de tempo numéricas (segundos desde 1970), o conversor de timestamp Unix faz a ponte entre número e data legível.

Números grandes e a precisão do double

A especificação não limita a magnitude dos números, mas avisa que a interoperabilidade depende do parser. Na prática, a maioria guarda número em ponto flutuante de 64 bits (o double do padrão IEEE 754). Isso representa inteiros com segurança até 9007199254740991, que é dois elevado a 53, menos um. Acima disso, dígitos se perdem:

JSON.parse('{"id": 9007199254740993}');
// { id: 9007199254740992 }  <- perdeu o ultimo digito

Esse é um problema real com IDs de banco de dados, números de telefone e valores financeiros longos. A solução consagrada é transmitir esses valores como string e converter para um tipo de precisão arbitrária do lado que recebe, como o BigInt do JavaScript ou o inteiro nativo de outras linguagens. Decimais também sofrem: como o double é binário, frações como 0.1 não têm representação exata, então dinheiro é melhor tratado em centavos inteiros ou como string decimal.

JSON Schema: validar a estrutura dos dados

Validar a sintaxe garante que o texto é JSON, mas não garante que ele tem os campos certos. Um objeto pode ser JSON perfeitamente válido e ainda assim estar faltando o campo email ou trazer idade como texto onde deveria ser número. O JSON Schema resolve isso: é um próprio documento JSON que descreve a forma esperada, quais campos são obrigatórios, os tipos de cada um, limites de valor e padrões de string.

Com um schema, dá para rejeitar automaticamente uma requisição malformada antes de processá-la, o que reduz erros e reforça a segurança da API. Bibliotecas de validação existem para todas as linguagens principais. Vale separar os dois papéis: o validador de sintaxe diz se o texto é JSON; o JSON Schema diz se aquele JSON serve para o seu caso.

Segurança ao processar JSON

Alguns cuidados evitam falhas conhecidas ao consumir JSON de fora:

• Nunca use eval para parsear. Em ambientes antigos era comum transformar texto em objeto com eval, mas isso executa qualquer código na string e abre porta para injeção. Use sempre o parser dedicado (JSON.parse e equivalentes), que só lê dados.
• Cuidado com JSON injection. Montar JSON concatenando texto do usuário na mão pode gerar documentos corrompidos ou maliciosos. Sempre gere JSON pela função de serialização da linguagem, que escapa os caracteres especiais corretamente.
• Trate profundidade e tamanho. JSON muito aninhado ou gigantesco pode consumir memória e derrubar o processo. Parsers sérios impõem limites; ao expor uma API, defina um teto de tamanho de corpo.
• Nunca renderize JSON de terceiros como HTML sem escapar. O conteúdo é dado, não marcação.

Ferramentas de JSON também devem processar tudo localmente. No ValorFinal, o conteúdo que você cola no validador de JSON não sai do seu navegador. Para tarefas próximas, veja o codificador Base64, o URL encoder/decoder, o testador de regex, o gerador de hash e o guia o que é JWT, já que o payload de um JWT é justamente JSON.

JSONL, NDJSON e codificação UTF-8

Para grandes volumes existe uma variante prática: o JSONL (também chamado NDJSON), em que cada linha do arquivo é um documento JSON completo e independente, separado por quebra de linha. Isso permite processar logs e exportações em fluxo, um registro por vez, sem carregar o arquivo inteiro na memória:

{"id":1,"nome":"Ana"}
{"id":2,"nome":"Bruno"}
{"id":3,"nome":"Carla"}

Cada linha é JSON válido, mas o arquivo inteiro não é um único JSON, e sim uma sequência deles. Sobre codificação, a RFC 8259 determina que o JSON trocado entre sistemas que não fazem parte de um mesmo ecossistema fechado seja gravado em UTF-8. É o que garante que acentos, cedilha e emojis cheguem íntegros do outro lado. Salvar em outra codificação costuma virar caractere corrompido na leitura.

Ferramentas para validar e formatar JSON

No dia a dia, duas operações resolvem quase tudo. Formatar (embelezar) adiciona indentação e quebras de linha para leitura humana. Minificar remove todos os espaços e deixa o JSON em uma linha compacta, o que reduz o tamanho na transmissão por API. Um bom editor faz as duas coisas e ainda aponta o erro de sintaxe na linha exata:

• Formatador e validador de JSON: valida, indenta, minifica e aponta o erro, tudo local no navegador.
• Conversor de dados: converte entre JSON, CSV, YAML e XML.
• Comparador de texto: mostra o que mudou entre duas versões de um JSON.
• Guia de conversão entre formatos: entende as equivalências e os limites de cada um.

Limitações deste guia

O conteúdo é educativo e cobre o JSON padrão descrito por RFC 8259 e ECMA-404. Variantes como JSON5, JSONC e formatos de streaming têm regras próprias fora desse padrão. Detalhes de implementação de cada parser (limites de profundidade, tratamento de chaves duplicadas, precisão numérica) variam por linguagem e biblioteca, então em produção confira a documentação da ferramenta que você usa. Veja também como validamos os cálculos.

Fontes oficiais

• ECMA-404: especificação da sintaxe de troca de dados JSON.
• RFC 8259: padrão IETF do formato JSON, incluindo a exigência de UTF-8.
• MDN Web Docs (JSON): referência prática de JSON.parse, JSON.stringify e uso no navegador.

Conclusão

JSON é simples de descrever e exige rigor de sintaxe: string sempre com aspas duplas, sem vírgula sobrando, sem comentários e sem funções. Dominar os seis tipos de valor, a diferença para um objeto JavaScript e os cuidados com datas, números grandes e segurança evita a maior parte das falhas de integração. Para validar, formatar e minificar na hora, use o formatador e validador de JSON, aprofunde no guia de conversão entre CSV, JSON, YAML e XML e no guia sobre JWT, e conheça as demais ferramentas de tecnologia.