Converter JSON para CSV

Isso é a única coisa que importa entender antes de converter qualquer coisa. JSON descreve uma árvore: um objeto pode guardar outro objeto, que pode guardar um array de objetos, em qualquer profundidade. Um CSV descreve uma grade: linhas e colunas, e nada dentro de uma célula.

Então a conversão não é uma tradução entre duas formas de escrever a mesma coisa. É uma projeção, e alguma coisa precisa ceder. Para dados que são de fato uma lista de registros planos — o que é a maioria das exportações — nada se perde. Para qualquer coisa profundamente estruturada, o CSV é uma aproximação legível e o JSON continua sendo o arquivo de verdade.

Um objeto aninhado é achatado juntando os nomes das chaves, então um registro com um cliente contendo uma cidade produz uma coluna nomeada combinando os dois. Um nível de aninhamento produz uma tabela que qualquer pessoa lê. Dois níveis ainda costuma estar bom.

Além disso a coisa degrada rápido: nomes de coluna ficam longos, a tabela fica muito larga, e a maioria das células na maioria das linhas fica vazia porque registros diferentes aninham de jeitos diferentes. Se uma conversão produz sessenta colunas a partir do que parecia uma exportação simples, isso é a forma dos dados aparecendo, não um defeito da conversão.

Um registro com três etiquetas, quatro itens de pedido ou uma lista de endereços anteriores não tem representação correta numa tabela. Existem três respostas comuns e cada uma está errada para algum propósito: uma coluna por posição, que quebra quando um registro tem cinco; uma coluna com os valores unidos por um separador, ilegível se os valores contêm esse separador; ou uma linha por elemento do array, que duplica o registro pai e muda o que uma linha significa.

Quando o array carrega o significado — um pedido com itens de linha, uma postagem com comentários —, a resposta honesta é não converter. Guarde o JSON, ou produza duas tabelas do jeito que um banco de dados faria: uma para pedidos e uma para itens, ligadas por um identificador.

Registros de uma exportação JSON não são obrigados a ter as mesmas chaves. Uma API retorna os campos que existem e omite os que não existem, então cem registros podem apresentar oitenta formas diferentes.

A conversão resolve isso olhando todos os registros para montar o conjunto completo de colunas, deixando uma célula vazia onde um registro não tem valor. Normalmente é isso que você quer, e explica uma surpresa comum: converter uma amostra de dez registros produz menos colunas do que converter o arquivo inteiro, porque a amostra simplesmente não continha os campos mais raros.

Produzir um CSV correto não protege ele do que acontece depois. O Excel abre um CSV adivinhando um tipo por coluna, o que remove zeros à esquerda de códigos, converte qualquer coisa com formato de data numa data, e trunca identificadores além de quinze dígitos.

O remédio é o de sempre: importar em vez de abrir — Dados, depois De Texto/CSV — e marcar as colunas de identificador como Texto antes de carregar. Se o destinatário é uma pessoa em vez de um programa, converter para XLSX em vez disso elimina a adivinhação por completo, porque os tipos ficam declarados no arquivo.

Converta quando os dados são registros planos e o destino é uma planilha, uma importação de banco de dados, uma ferramenta estatística ou um colega. Isso cobre a maioria das exportações de plataformas de análise, CRMs e APIs de relatório, e o CSV fica mais fácil de usar do que o JSON era em todos esses casos.

Não converta quando a estrutura é o conteúdo — um arquivo de configuração, uma resposta de API que você pretende processar com código, qualquer coisa com array que carrega significado. E guarde o JSON de qualquer forma: é o arquivo que ainda contém tudo, e regenerar um CSV dele leva segundos.

Exportações de dados de serviços de IA hoje são um dos motivos mais comuns de alguém abrir um arquivo JSON, e o arquivo de conversas costuma ser o caso típico. Ele não é uma lista de linhas: é um conjunto de árvores de mensagem, cada nó apontando para o pai, que é como conversas ramificadas e editadas são representadas. Não existe uma grade honesta dentro disso.

Converter isso para CSV produz algo tecnicamente válido e praticamente inútil — uma linha por nó, com a estrutura da conversa perdida. Se o objetivo é ler as conversas, o arquivo HTML exportado junto costuma ser o certo para abrir. CSV é o destino certo para as exportações mais planas ao lado dele, como registros de uso e cobrança, em que cada item de fato é uma linha.

Um array JSON precisa estar completo antes de poder ser interpretado, porque o colchete de fechamento é o que o torna válido. Então um arquivo muito grande precisa ser lido inteiro, e essa é uma propriedade do formato, não de uma ferramenta específica.

Se você controla como os dados são produzidos, peça NDJSON — um objeto JSON completo por linha — em vez de um array grande. Aqui ele ainda precisa ser lido inteiro na memória, igual a um array, mas cada linha é interpretada por conta própria: uma linha corrompida ou truncada falha com seu próprio número de linha em vez de invalidar o documento inteiro. É o que pipelines de log e grandes exportações de dados usam justamente por isso.

A conversão roda no seu navegador, no seu próprio processador. O arquivo nunca é enviado a lugar nenhum, não existe conta nem limite diário, e um arquivo de até 100 MB é processado dentro da aba.

Isso vale mais aqui do que na maioria das conversões. Uma exportação JSON quase sempre é a saída bruta de uma API — registro de cliente, histórico de pedido, cadastro de usuário — e costuma conter campos que ninguém pensou em checar porque ninguém esperava que alguém fosse lê-los. Não enviar para lugar nenhum é a resposta simples.