Como Converter JSON Aninhado para CSV: O Que a Opção de Achatamento Realmente Faz (Guia 2026)

Por que o JSON resiste ao achatamento: árvores versus tabelas

Um CSV é uma tabela: linhas e colunas, com cada célula guardando um único valor simples. O JSON é uma árvore: objetos dentro de objetos, listas dentro de objetos, objetos dentro de listas. Achatar é a tradução entre essas duas formas, e é a única etapa da conversão de JSON para CSV em que o conversor precisa tomar decisões por você — porque não existe uma única resposta "correta".

Pegue o registro aninhado mais simples possível: um objeto com id 1 e um customer que contém name "Ana" e city "Madrid". Uma tabela não tem como acomodar um "customer" que guarda duas coisas ao mesmo tempo. Então o conversor precisa escolher: dar ao customer uma coluna própria e enfiar o objeto nela como texto, ou explodir o objeto em colunas customer.name e customer.city. Todo conversor faz essa escolha com o mesmo punhado de regras — e quando você as conhece, dá para prever o seu CSV antes mesmo de apertar o botão de converter.

É por isso que dois conversores diferentes podem produzir CSVs diferentes a partir do mesmo JSON: cada um define as próprias regras para os casos ambíguos. As regras que você vai ver aqui são as do motor real deste site, verificadas uma a uma contra saídas de verdade. Elas seguem o que a maioria dos bons conversores faz, então o que você aprender aqui serve para julgar qualquer ferramenta — inclusive para decidir se ela está fazendo um bom trabalho ou inventando estrutura onde não deveria.

O arquivo de exemplo que vamos converter de JSON aninhado para CSV

Tudo neste guia é demonstrado com um único arquivo — três pedidos com três níveis de aninhamento, uma lista de valores simples, uma lista vazia, um objeto vazio, um null e uma lista de objetos. Passamos esse arquivo, exatamente como está, pelo motor de conversão real deste site (o mesmo JavaScript que roda quando você aperta Converter), e cada saída mostrada abaixo é o que o motor realmente produziu, sem retoques:

orders-nested.json

[
  { "orderId": "A-101", "customer": { "name": "Ana Ruiz", "contact": { "email": "ana@example.com", "city": "Madrid" } }, "items": ["book", "pen"], "tags": [], "meta": {} },
  { "orderId": "A-102", "customer": { "name": "Ken Sato", "contact": { "email": "ken@example.com", "city": "Osaka" } }, "items": ["lamp"], "tracking": [{ "code": "TX-1", "status": "shipped" }, { "code": "TX-2", "status": "pending" }] },
  { "orderId": "A-103", "customer": { "name": "Lina Noor", "contact": { "email": null, "city": "Berlin" } }, "items": ["mug", null, "plate"] }
]

Regra 1: objetos aninhados viram colunas com notação de ponto

A primeira regra — e a mais importante: cada nível de aninhamento de um objeto vira parte do nome da coluna, com os níveis unidos por pontos. customer.contact.email não são três colunas: é uma única coluna cujo nome é o caminho completo descendo pela árvore. Aqui está a saída real do motor com o achatamento ativado:

CSV output — flattening ON (verified against the real engine)

orderId,customer.name,customer.contact.email,customer.contact.city,items,tags,meta,tracking
A-101,Ana Ruiz,ana@example.com,Madrid,book; pen,,{},
A-102,Ken Sato,ken@example.com,Osaka,lamp,,,"[{""code"":""TX-1"",""status"":""shipped""},{""code"":""TX-2"",""status"":""pending""}]"
A-103,Lina Noor,,Berlin,mug; ; plate,,,

A profundidade do aninhamento não tem limite prático nesta regra — também testamos um objeto de quatro níveis, com a chave d valendo "deep" dentro de a, b e c, e o motor produziu uma única coluna chamada a.b.c.d com o valor deep. Nomes de coluna pontilhados ordenam e filtram normalmente em qualquer planilha; se customer.contact.city ficar longo demais para o seu gosto, renomeie os cabeçalhos depois em uma única passada.

Um detalhe que vale ouro na prática: como cada caminho aninhado vira uma coluna independente, você consegue filtrar, ordenar e montar tabelas dinâmicas diretamente sobre qualquer nível da hierarquia — algo impossível quando o objeto inteiro está preso dentro de uma célula de texto. É essa granularidade que faz o modo achatado ser o padrão para análise de dados.

Regra 2: listas de valores simples se unem em uma célula

Quando uma lista contém apenas valores simples — strings, números, booleanos, nulls — a lista inteira colapsa em uma única célula, com os valores unidos por "; " (ponto e vírgula seguido de espaço). Repare na coluna items da saída acima: a lista com "book" e "pen" virou a célula book; pen, e a lista com "mug", null e "plate" virou mug; ; plate — o null virou um segmento vazio, não foi pulado.

Duas consequências práticas. Primeira: se você depois escolher o ponto e vírgula como delimitador do CSV, essa célula unida é colocada entre aspas automaticamente, para que o separador dentro da célula não consiga dividi-la — o motor aplica as regras de aspas do CSV célula por célula, como verificado no teste acima. Segunda: unir perde a informação das fronteiras — depois do achatamento, book; pen é texto puro, não mais uma lista. Se você precisar separar os itens de volta em linhas individuais, veja a Regra 3.

Regra 3: listas de objetos colapsam em uma célula de texto JSON

Esta é a regra que mais surpreende. Quando uma lista contém objetos — como o array tracking, com suas entradas de código e status — ela não pode virar colunas (objetos têm estrutura, não apenas valores) e também não pode ser unida como valores simples. Então o motor guarda a lista inteira como uma célula de texto JSON entre aspas. Acima, a coluna tracking do pedido A-102 contém o array JSON completo como texto, escapado conforme as regras do CSV.

Isso é uma limitação? Sendo honesto: sim, para esse formato de dado. Não existe neste conversor uma opção de expandir em linhas — ele nunca cria uma linha de CSV por item da lista. Se você realmente precisa de uma linha por evento de rastreio, reestruture antes de converter: extraia o array interno e converta-o sozinho, e você obtém linhas limpas de código e status. Uma coluna de texto JSON é a alternativa honesta a inventar silenciosamente linhas que você não pediu.

Regra 4: valores vazios e nulls seguem regras exatas

Nulls e vazios são onde começa a maior parte da confusão do tipo "por que meu CSV saiu estranho" — então aqui estão os comportamentos verificados, sem achismo:

Um valor null vira uma célula vazia. O email null de Lina Noor produziu uma célula vazia em customer.contact.email — sem o texto "null", sem aspas.
Uma lista vazia vira uma célula vazia. A lista tags vazia do pedido A-101 deixou a célula em branco. (Observação: este é o comportamento com o achatamento ATIVADO; com o achatamento desligado, a mesma lista aparece como o texto literal [].)
Um objeto vazio vira o texto {}. O meta vazio do pedido A-101 produziu uma célula contendo {} — o motor não tem nada para expandir, então escreve a forma literal do objeto.
Um null dentro de uma lista vira um segmento unido vazio — mug; ; plate acima — em vez de ser pulado ou escrito como "null".

São decisões de design, não leis universais — mas são consistentes: null significa "nada aqui", e o CSV não diz nada. Quando você entende essa lógica, para de suspeitar de erro toda vez que vê uma célula em branco.

Converter JSON aninhado para CSV: achatamento ativado versus desativado, byte por byte

O mesmo arquivo, agora com o achatamento desligado. Cada chave de nível superior mantém sua própria coluna, e as estruturas aninhadas são guardadas como texto JSON entre aspas:

CSV output — flattening OFF (verified against the real engine)

orderId,customer,items,tags,meta,tracking
A-101,"{""name"":""Ana Ruiz"",""contact"":{""email"":""ana@example.com"",""city"":""Madrid""}}","[""book"",""pen""]",[],{},
A-102,"{""name"":""Ken Sato"",""contact"":{""email"":""ken@example.com"",""city"":""Osaka""}}","[""lamp""]",,,"[{""code"":""TX-1"",""status"":""shipped""},{""code"":""TX-2"",""status"":""pending""}]"
A-103,"{""name"":""Lina Noor"",""contact"":{""email"":null,""city"":""Berlin""}}","[""mug"",null,""plate""]",,,

Repare nos detalhes do modo desligado: as colunas encolhem para as chaves de nível superior (customer, items, tags, meta, tracking), cada valor aninhado é convertido para JSON bruto com duplicação de aspas do CSV, e a lista vazia e o objeto vazio aparecem como texto literal [] e {}. O modo desligado é a representação honesta, porém feia — correta quando você precisa preservar a estrutura aninhada exata (por exemplo, antes de devolver as linhas para um sistema que espera campos em formato JSON). Para análise — filtros, tabelas dinâmicas, gráficos — o achatamento ativado é a escolha certa, e é por isso que ele vem como padrão.

De onde vêm as linhas: arrays, respostas de API e JSON Lines

O achatamento decide as colunas; outra coisa decide as linhas. O motor olha o valor de nível superior do seu JSON e segue três casos:

Caso um: o nível superior é um array de objetos — cada objeto vira uma linha. É o exemplo dos pedidos acima: três objetos, três linhas. Caso dois: o nível superior é um único objeto — você obtém uma única linha. O caso três é o mais útil: o nível superior é um objeto que envolve um array, como fazem as respostas de API — um objeto com a chave data contendo o array e um total. O motor detecta o array interno (ele verifica chaves comuns de invólucro como data, results, users e items) e transforma cada elemento em uma linha, descartando os campos do invólucro. Verificamos isso na prática: um objeto com data contendo dois registros e total igual a 2 produziu exatamente as duas linhas de dados com as colunas dos registros — o total desapareceu.

Mais um formato de entrada que vale conhecer: o motor também aceita JSON Lines (NDJSON) — um objeto JSON por linha. Se a sua exportação são dez mil linhas em vez de um único array gigante, cole como está; a conversão funciona do mesmo jeito.

Dados irregulares: chaves ausentes viram apenas células vazias

Exportações reais são irregulares: o pedido A-102 tem tracking mas não tem meta, o A-101 tem meta mas não tem tracking, e o A-103 não tem nenhum dos dois. O motor monta a lista de colunas como a união de todas as chaves encontradas em todas as linhas, em ordem — por isso a linha de cabeçalho acima tem as oito colunas — e qualquer linha sem uma determinada chave simplesmente recebe uma célula vazia nela.

É por isso que os cabeçalhos saem em ordem de inserção (orderId primeiro, depois as chaves aninhadas vistas primeiro) em vez de ordem alfabética: as colunas seguem a forma dos seus dados à medida que o motor os percorre. Se uma linha posterior introduzir um caminho aninhado totalmente novo, a coluna aparece mesmo assim — nada é descartado em silêncio.

Três casos de borda que mordem

Primeiro: chaves que já contêm pontos. Se o seu JSON tem tanto uma chave literal "user.name" quanto um objeto user aninhado com a chave name, os dois disputam a mesma coluna. Testamos: o valor aninhado vence e o valor da chave literal se perde — o teste produziu uma única coluna user.name contendo o valor aninhado. Renomeie as chaves com pontos antes de converter se os dois valores forem importantes.

Segundo: listas de tipos mistos. Uma lista que mistura número, string e objeto não é "toda de primitivos", então o motor a trata como lista de objetos e converte tudo para uma célula de texto JSON — mesmo que a maior parte fosse simples. Mantenha as listas homogêneas se quiser o comportamento de união com "; ".

Terceiro: aninhamento profundo funciona bem, mas fique de olho nos nomes das colunas. Dez níveis de aninhamento geram um nome de coluna pontilhado de dez partes — tecnicamente correto, praticamente ilegível. Achate tudo e depois renomeie apenas as três colunas que você realmente usa.

O checklist de 30 segundos para converter JSON aninhado para CSV

Se você não lembrar de mais nada: deixe o achatamento ativado para análise e desligue apenas para preservar a estrutura; espere colunas com notação de ponto e listas unidas com "; "; extraia listas de objetos e converta-as separadamente quando precisar de uma linha por item; e trate células vazias como a representação honesta de nulls — não como erros. A opção é um clique só, mas agora você sabe exatamente o que esse clique faz.

Guias relacionados

Perguntas frequentes

O que significa achatar JSON para converter em CSV?

Achatar é a etapa que transforma JSON aninhado em uma tabela de planilha plana: objetos aninhados viram colunas com notação de ponto (customer.contact.city), listas de valores simples se unem em uma célula com "; ", e listas de objetos colapsam em uma única célula de texto JSON. Sem o achatamento, os valores aninhados são guardados como texto JSON bruto entre aspas, um por coluna.

Como transformo objetos JSON aninhados em colunas de CSV?

Use um conversor com opção de achatamento e deixe-a ativada — os objetos aninhados são expandidos automaticamente em colunas com notação de ponto, em qualquer profundidade (customer.contact.email, ou até a.b.c.d). No conversor deste site, o achatamento é o padrão: cole ou suba o seu JSON, converta, e cada caminho aninhado vira sua própria coluna ordenável e filtrável.

O que acontece com os arrays ao converter JSON aninhado para CSV?

Depende do que o array contém. Listas de valores simples (strings, números) se unem em uma única célula com "; " — uma lista com "book" e "pen" vira book; pen. Listas de objetos são guardadas como uma célula de texto JSON entre aspas, porque objetos não podem virar valores planos. Listas vazias viram células vazias. Listas mistas são convertidas inteiras para texto, então mantenha as listas homogêneas para resultados previsíveis.

Por que meu CSV achatado tem tantas células vazias?

Células vazias são normais e honestas: um valor null vira uma célula vazia, uma lista vazia vira uma célula vazia, e quando as linhas têm chaves diferentes (dados irregulares), as chaves ausentes deixam espaços em branco. Verifique se os vazios batem com os nulls do seu JSON de origem — se baterem, a conversão está correta.

Devo deixar o achatamento ativado ou desligado ao converter JSON para CSV?

Deixe ativado para análise — colunas com notação de ponto são o que tabelas dinâmicas, filtros e gráficos precisam. Desligue apenas quando precisar preservar a estrutura aninhada exata, por exemplo antes de devolver as linhas para um sistema que espera campos em formato JSON. No modo desligado, cada valor aninhado é guardado como texto JSON bruto entre aspas, o que é correto, mas inutilizável para planilhas.

Consigo obter uma linha de CSV por item em um array aninhado de objetos?

Este conversor não expande listas de objetos em linhas — ele as guarda como uma célula de texto JSON. A solução confiável: extraia o array interno e converta-o sozinho (por exemplo, converta apenas uma lista com dois objetos de código e status) para obter uma saída limpa de uma linha por item. Faça a extração antes de converter, não depois.

Existe uma ferramenta gratuita que converte JSON aninhado para CSV online?

Sim — o conversor deste site é gratuito, não pede cadastro e achata JSON aninhado por padrão (colunas com notação de ponto, listas unidas com "; ") inteiramente no seu navegador, então os seus dados nunca saem do seu dispositivo. Suba um arquivo ou cole o JSON, deixe o achatamento ativado, escolha o delimitador e baixe o CSV.

Tem JSON aninhado? Achate agora — nada para instalar

Cole o seu JSON aninhado ou suba o arquivo: objetos viram colunas com notação de ponto, listas se unem direitinho, e a conversão roda inteiramente no seu navegador. Grátis, sem cadastro.

Abrir o conversor de JSON para CSV

Todos os guias