JSON Toolkit

Arrays e objetos JSON: estrutura e aninhamento para iniciantes

Resumo: O JSON só tem dois contêineres: o objeto para campos nomeados, o array para listas ordenadas. Aprenda a combiná-los, a escolher o certo e a corrigir os três erros mais frequentes: falsos arrays com chaves numéricas, vírgula final e apóstrofos.

Iniciante~6 min de leituraPublicado em 2026-11-20Atualizado em 2026-11-20
Capa de introdução às estruturas de arrays e objetos JSON

O JSON só lhe dá dois contêineres: o objeto carrega campos nomeados, o array carrega listas ordenadas — e quase todo payload quebrado se explica por aspas, vírgulas, ou uma lista escrita como um falso objeto.

Um: o JSON só tem dois contêineres

Por mais complexa que seja uma resposta de API, tudo se reduz a dois contêineres e seis tipos de valor. Um objeto é uma coleção de pares chave/valor entre chaves {}; um array é uma lista ordenada de valores entre colchetes []. Um valor pode ser uma string, um número, true, false, null — ou de novo um objeto ou array. Objetos dentro de arrays, arrays dentro de objetos: essa recursão é toda a poder de expressão do JSON.

{
  "user": { "name": "Ada", "active": true },
  "roles": ["admin", "editor"],
  "lastLogin": null,
  "loginCount": 42
}

Daí vem uma consequência prática: diante de um payload confuso, não o leia caractere por caractere. Verifique primeiro se o caractere mais externo é { ou [. Se for objeto, leia-o como campos nomeados; se for array, leia-o como lista e desça nível por nível. O diagrama de sintaxe do json.org cabe em uma única página justamente porque duas estruturas mais recursão cobrem tudo.

Dois: escrever objetos, quatro regras duras

Objetos são onde iniciantes mais erram, mas as regras se reduzem a quatro:

  1. As chaves devem ser strings entre aspas duplas. {name: "Ada"} e {'name': 'Ada'} são ambos inválidos; é preciso escrever {"name": "Ada"}. Literais de objeto JavaScript permitem chaves nuas e apóstrofos, o JSON não — essa é a confusão mais comum entre os dois.
  2. Separe os pares por vírgulas e nunca deixe vírgula depois do último. {"a": 1, "b": 2,} falha com Unexpected token } na chave de fechamento.
  3. As chaves devem ser únicas. O RFC 8259 formula isso como SHOULD, não MUST: chaves duplicadas não causam erro, mas manter o primeiro ou o último valor depende da implementação, e as linguagens divergem. Nunca confie nisso.
  4. A ordem das chaves não tem significado. {"a":1,"b":2} e {"b":2,"a":1} são o mesmo objeto; ferramentas de diff e funções de comparação ignoram a ordem das chaves. Se a ordem importa, os dados pertencem a um array.

Três: escrever arrays, a ordem é um dado

Arrays guardam valores por posição, e a indexação começa em 0: em ["admin", "editor"], a string "editor" é o [1]. Essa ordem é significativa — é a diferença essencial entre arrays e objetos. Resultados de busca ordenados por relevância, entradas de log ordenadas por data: essa informação vive apenas na sequência, e convertê-la em objeto a destrói.

Duas recomendações práticas. Primeiro, mantenha os elementos homogêneos: [{"id":1},{"id":2}] é muito mais fácil de consumir do que [1, "text", true], que é legal mas obriga todo consumidor a testar tipos em cada passo. Segundo, um array vazio [] é um valor perfeitamente válido — quando um campo de lista ainda não tem conteúdo, emita [] em vez de null, para que o consumidor não precise verificar existência e depois vazio.

[
  { "city": "Tokyo", "population": 13960000 },
  { "city": "Delhi", "population": 16780000 }
]

Quatro: aninhamento, as quatro formas dos payloads reais

Dados reais são apenas esses dois contêineres aninhados um no outro, e os padrões se reduzem a quatro formas:

Forma Como parece Uso típico
Objeto contendo array {"tags": ["a","b"]} Campo de lista de uma entidade
Array de objetos [{"id":1},{"id":2}] Listas de registros, resultados paginados
Objeto contendo objeto {"db": {"host": "..."}} Configuração agrupada, blocos de endereço
Array de arrays [[1,2],[3,4]] Matrizes, linhas de tabela

Uma resposta típica de API usa um objeto como invólucro e um array como conteúdo:

{
  "code": 0,
  "data": {
    "items": [
      { "id": 1, "title": "first" },
      { "id": 2, "title": "second" }
    ],
    "page": 1,
    "total": 2
  }
}

Não aninhe por aninhar. Além de três ou quatro níveis, os caminhos de acesso ficam ilegíveis e o código consumidor cresce em paralelo. Campos que sempre viajam juntos pertencem a um subobjeto: troque addrCity e addrZip por address: {city, zip}.

Cinco: objeto ou array, uma tabela de decisão

Pergunta Resposta Por quê
Cada valor tem um nome? Objeto Acesso por chave; adicionar ou remover campos não quebra nada
É uma lista de registros parecidos? Array A ordem importa; dá para mapear e filtrar
Precisa de busca rápida por chave? Objeto indexado por identificador Acesso O(1) em vez de varredura
Vários atributos de uma mesma entidade? Objeto Atributos não têm ordem própria
Coleção crescente de itens parecidos? Array O comprimento estende-se livremente

Um antipadrão merece menção especial: imitar um array com um objeto cujas chaves são "0", "1", "2". Ele faz parse sem erro, mas você perde a semântica de comprimento e as ferramentas de iteração de um array verdadeiro, e os consumidores precisam ordenar Object.keys antes de ler qualquer coisa. Se as chaves são números sequenciais, escreva um array de verdade. O inverso também vale: uma lista de pares chave/valor como [{"key":"theme","value":"dark"}] é inferior ao objeto {"theme": "dark"} — a menos que as chaves sejam realmente dinâmicas e não possam ser declaradas antecipadamente.

Seis: três erros frequentes e suas mensagens

Forma incorreta Erro típico Correção
Vírgula final {"a":1,} Unexpected token } Remover a última vírgula
Apóstrofos / chaves nuas {name:'Ada'} Unexpected token ' / Expected property name Aspas duplas para chaves e strings, sempre
Literais Python True / None Unexpected token T Substituir por true / null
Falso array com chaves numéricas Sem erro, semântica errada Reescrever como array verdadeiro

Dois hábitos de depuração: os parsers geralmente apontam uma posição depois do caractere problemático, então ao ver position 42, olhe um ou dois caracteres para trás; e um JSON enorme em uma única linha deve ser formatado primeiro — números de linha e coluna vencem offsets de caracteres sempre. O catálogo completo de erros está em a tabela de consulta de erros JSON, e o fluxo de triagem passo a passo em como corrigir erros de parse de JSON.

Sete: depois de escrever, valide a estrutura

Um JSON escrito à mão deve sempre passar por um parser antes da entrega. A verificação mais leve cabe em uma linha de comando:

python3 -m json.tool config.json > /dev/null && echo OK
jq empty config.json && echo OK

Online, cole o conteúdo na página de formatação e validação de JSON — os erros de sintaxe voltam com linha e coluna. Mude para a visualização em árvore para ver o tipo de cada nível de relance: se um número foi interpretado como string, se os comprimentos dos arrays batem. E quando o público não é técnico, um payload array-de-objetos pode ser desdobrado em linhas e colunas na página de JSON para tabela, o que de quebra verifica se seus dados formam mesmo uma lista regular de registros.

Perguntas sobre o campo que deveria ser um array, ou sobre refazer um aninhamento que ficou profundo demais, pertencem à modelagem de tipos — a próxima leitura é seis tipos, precisão numérica e armadilhas de codificação.

Arrays e objetos JSON podem ser convertidos um no outro?

Sim, mas não sem perdas. Converter um objeto em array geralmente significa transformar as chaves em valores e perder o acesso por chave; converter um array em objeto exige inventar uma chave para cada elemento, e a origem dessas chaves é um novo problema de design. Decida pela forma como o consumidor lê os dados, não pela conveniência sintática.

Chaves de objeto podem ser duplicadas?

Sintaticamente sim — o RFC 8259 diz apenas que as chaves DEVEM ser únicas (SHOULD). Mas o JavaScript mantém o último valor enquanto algumas bibliotecas da família C mantêm o primeiro: o comportamento difere entre parsers. Em assinaturas, diffs ou hashes, chaves duplicadas causam divergências diretas. Evite-as no lado produtor e trate duplicatas de uma fonte desconhecida como risco no lado consumidor.

Um array pode conter valores de tipos diferentes?

Sintaticamente sim: [1, "a", true] é um JSON válido. Mas arrays heterogêneos forçam verificações de tipo em cada posição do código consumidor, e são difíceis de expressar em um schema. Exceto em matrizes e tuplas, onde a posição é a semântica, mantenha os arrays homogêneos.

Por que {name:'json'} falha na validação?

Porque o JSON exige aspas duplas em torno de cada chave e de cada valor string. {name:'json'} é um literal de objeto JavaScript, não JSON. Substitua por {"name": "json"} e a validação passa. Apóstrofos, chaves nuas e comentários pertencem a dialetos como JSON5/JSONC, que exigem parsers próprios em vez do JSON.parse padrão.