Como converter JSON para CSV quando seus dados são aninhados

Um array JSON de objetos vira um CSV pegando como coluna cada chave que aparece em qualquer lugar do array e escrevendo uma linha por objeto, então [{"id":1,"name":"Ada"}] sai como uma linha de cabeçalho id,name e uma linha 1,Ada. Cole o array no conversor desta página e é esse o arquivo que você recebe de volta, com as aspas do jeito que a RFC 4180 pede. A parte chata é tudo o que o JSON consegue expressar e um retângulo não: objetos aninhados, arrays, tipos e a diferença entre null e uma string vazia.

Como fica de verdade o arquivo convertido

Pegue um array com um objeto aninhado e um array dentro, como a maioria das respostas de API:

[
  { "id": 1, "name": "Ada Lovelace", "address": { "city": "London" }, "tags": ["maths"] },
  { "id": 2, "name": "Hopper, Grace", "address": { "city": "New York" }, "tags": [] }
]

O CSV é este:

id,name,address.city,tags
1,Ada Lovelace,London,"[""maths""]"
2,"Hopper, Grace",New York,[]

Três coisas aconteceram aí. O objeto aninhado address virou uma coluna com ponto. O array tags continuou como texto JSON em uma única célula. E o nome que tem uma vírgula acabou entre aspas, porque senão teria se partido em duas colunas e empurrado tudo o que estava à direita dele.

As colunas são a união de todas as chaves de todos os objetos, na ordem em que cada uma aparece pela primeira vez. Uma linha à qual falta uma chave ganha uma célula vazia em vez de uma linha curta, então os dados irregulares continuam alinhados em vez de escorregar para o lado no meio do arquivo.

O seu JSON tem linhas dentro?

Um array de objetos é o caso para o qual isso funciona. Um objeto sozinho também converte e te dá uma linha. Um array de valores simples vira uma tabela de uma coluna só.

Muito JSON não tem linha nenhuma dentro, e forçá-lo para dentro de uma planilha te dá algo válido e inútil. Um arquivo de configuração, uma árvore de preferências ou o payload decodificado de um token viram, cada um, uma linha larga de colunas com pontos. Os claims dentro de um JWT se leem bem melhor como JSON do que como quarenta colunas que você rola para o lado.

Se o texto é uma única linha longa minificada e você não consegue saber qual é o formato dele, passe antes por um formatador de JSON. Ele aponta os dois problemas que fazem parse sem erro e ainda assim machucam: chaves duplicadas, em que a última vence em silêncio, e inteiros grandes demais para o JavaScript guardar com exatidão. O conversor não menciona nenhum dos dois. Ler JSON minificado cobre o resto disso.

O que acontece com objetos e arrays aninhados

Esta é a parte que não dá para fazer certo, só para decidir. Três casos, três concessões.

Objetos aninhados: colunas com ponto

{"address":{"city":"London"}} vira uma coluna chamada address.city, e os pontos continuam descendo até onde os seus dados descerem. Um objeto sem nada dentro não tem chave nenhuma para emprestar, então {"address":{}} sai como uma coluna chamada address com o texto {} dentro. Desligue o achatamento e cada objeto cai inteiro em uma célula assim: mais fácil de ler quando quem vai abrir o arquivo é uma pessoa, inútil quando quem precisa fazer o parse é um programa.

Arrays de valores: uma célula, como JSON

["maths","notes"] continua sendo esse texto em uma única célula. A alternativa é uma coluna por posição, e aí uma linha com quarenta tags alarga o arquivo para todas as outras, a maioria delas em branco. Se você prefere maths; notes na célula, junte o array no JSON antes de converter.

Arrays de objetos: escolha de que jeito errar

Pedidos com itens, posts com comentários. O um-para-muitos não tem forma plana que guarde tudo. Deixe o array filho como JSON na célula dele e a planilha não vai conseguir fazer nada com ele. Repita os campos do pai uma vez para cada filho e o arquivo se lê bem até alguém somar uma coluna, momento em que cada total de pedido é contado tantas vezes quantos itens ele tem. Se você precisa da segunda opção, separe o JSON em uma tabela pai e uma tabela filha com um id em comum, e converta as duas separadamente.

Por que alguns campos saem entre aspas

Essas aspas não fazem parte dos seus dados. Elas são o único jeito que o CSV tem de dizer que uma vírgula ou uma quebra de linha dentro de um campo é conteúdo, e não separador, e o próximo parser remove as aspas na entrada. Apagá-las na mão é o que faz um arquivo que funciona parar de funcionar.

Um campo ganha aspas quando contém o delimitador, uma aspa dupla ou uma quebra de linha. Uma aspa dentro de um campo entre aspas é duplicada em vez de escapada com barra invertida, então Alan "Turing" é escrito "Alan ""Turing"""; barras invertidas são outra convenção e a maioria dos importadores não vai entender. Campos com espaços no início ou no fim também ganham aspas aqui, o que as regras não exigem mas te salva dos parsers que cortam em silêncio o espaço em branco que está fora das aspas.

Um campo que guarda uma quebra de linha faz uma linha de CSV ocupar duas linhas do arquivo. Isso é válido, e quebra qualquer coisa que leia o arquivo uma linha por vez — que é a maioria dos scripts rápidos.

As regras vêm da RFC 4180, publicada em 2005 e marcada como informativa: ela registrou o que as pessoas já faziam em vez de dizer a alguém o que fazer, e é por isso que os importadores continuam discordando uns dos outros. As linhas terminam em CRLF, como a RFC pede e como o Excel prefere. As ferramentas Unix leem isso sem reclamar, só que algumas deixam o retorno de carro grudado no último campo de cada linha. Se um importador que você não controla continua recusando o arquivo, colocar aspas em todos os campos é verboso e nunca está errado.

Por que todas as colunas caem na célula A1

Porque a sua planilha espera outro delimitador. O Excel segue o separador de listas do sistema, que é ponto e vírgula em boa parte da Europa e da América Latina, onde a vírgula já é o separador decimal. Abra lá um arquivo delimitado por vírgulas e a linha inteira cai na célula A1. Trocar o delimitador para ponto e vírgula resolve. A tabulação faz o mesmo trabalho com muito menos aspas, já que tabulações quase nunca aparecem dentro de dados reais.

Por que os acentos chegam virados em lixo

Se José abre como José, o arquivo está certo e quem lê está errado. O Excel no Windows ainda abre um .csv comum usando a code page legada do sistema em vez de UTF-8. Uma marca de ordem de bytes — três bytes no começo do arquivo — diz o contrário para ele, e é por isso que o conversor daqui escreve uma no download por padrão.

Deixe-a ligada para o Excel. Desligue quando o arquivo for para um script, um carregador de banco de dados ou um pipeline Unix, onde esses três bytes acabam grudados na frente do nome da sua primeira coluna e produzem um erro desconcertante. O BOM vai só para o arquivo baixado, nunca para o texto que você copia.

O que a planilha muda no instante em que você abre

O CSV pode estar perfeito e a planilha vai editá-lo na entrada assim mesmo, porque dar dois cliques em um arquivo deixa que ela adivinhe em cada coluna.

• Os zeros à esquerda somem. O código postal 01234 vira 1234 e o código de produto 007 vira 7.
• Os números longos perdem o final. O Excel guarda 15 dígitos significativos, então um número de cartão de 16 dígitos ou uma referência de pedido de 19 volta arredondada, muitas vezes exibida em notação científica.
• Tudo o que tem cara de data vira data. No formato da configuração regional, que não é necessariamente aquele em que os seus dados foram escritos.

A solução é parar de dar dois cliques. No Excel, use Dados e depois De Texto/CSV, e marque as colunas problemáticas como Texto durante a importação. No Google Sheets, use Arquivo e depois Importar, e desligue a opção que converte texto em números, datas e fórmulas. Nada disso é culpa do arquivo; o estrago acontece do outro lado.

Por que uma célula que começa com = é um problema de segurança

Uma célula cujo texto começa com =, +, @, uma tabulação ou um sinal de menos que não seja o começo de um número é avaliada como fórmula em vez de ser exibida. Quando os dados vieram de usuários, essa fórmula roda na máquina de quem abrir a exportação. Isso tem nome — CSV injection — e é uma rota de ataque real, não uma curiosidade.

O conversor conta esses campos e te diz quantos são. Ele não os neutraliza, e isso é de propósito: a correção usual é colocar um apóstrofo na frente, o que corrompe o valor para todo leitor do arquivo que não seja uma planilha. Se essa troca vale a pena depende de para onde o arquivo vai.

O que a conversão perde

Os tipos. O CSV não tem nenhum. 42, "42" e true viram todos texto puro, e o que ler o arquivo depois tem que adivinhá-los de volta. É nessa adivinhação que converter um CSV de volta para JSON dá errado, e é por isso que a ida e volta de JSON para CSV para JSON não devolve o que você tinha no começo.

O null. null e uma string vazia saem os dois como uma célula vazia; o CSV não consegue distinguir um do outro.

Os inteiros muito grandes. Passando de 9007199254740991, o JavaScript não consegue mais guardar todo número inteiro com exatidão, então um ID desse tamanho pode ter sido arredondado quando o JSON foi parseado — antes de o CSV existir, e sem nada no CSV para mostrar isso. IDs desse tamanho precisam ser strings no JSON.

O tamanho. Não existe streaming. O texto, o valor parseado e o CSV pronto ficam todos na memória ao mesmo tempo, então alguns megabytes funcionam bem e cem não. Passado esse ponto — ou passada a segunda vez que você faz isso — escreva o script.

Última atualização 19 de setembro de 2026