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.

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:
- 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. - Separe os pares por vírgulas e nunca deixe vírgula depois do último.
{"a": 1, "b": 2,}falha comUnexpected token }na chave de fechamento. - 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.
- 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.