Converter JSON em CSV sem perder o significado dos dados

JSON e CSV resolvem problemas diferentes. JSON preserva objetos, listas e tipos; CSV organiza valores em linhas e colunas. A conversão é útil para abrir um extrato em uma planilha, mas nunca é uma operação neutra. Antes de converter, decida o que uma linha representa, quais campos viram colunas, quais tipos serão texto e que informação não poderá ser reconstruída.

Tratar CSV como “JSON sem chaves” produz exportações ruins. A RFC 8259 permite estruturas aninhadas, null, booleanos, números e strings. A RFC 4180 descreve registros separados por vírgulas: campos com vírgula, aspas ou quebra de linha são colocados entre aspas, e aspas nos dados são duplicadas. Nenhum padrão determina como um cliente com vários pedidos cabe em uma única linha. Essa decisão pertence ao contrato da exportação.

O problema

O problema começa quando uma exportação combina dados de cardinalidades diferentes. Um registro pode ter um cliente e endereço, mas muitos pedidos; cada pedido pode ter muitos itens. Se cada cliente ocupa uma linha, onde entram dois pedidos? Se cada item ocupa uma linha, dados do cliente e do pedido devem se repetir? As duas respostas podem ser adequadas para usos distintos, mas produzem arquivos com significados diferentes.

Os tipos também trazem risco. O identificador "00073" não é o número 73: os zeros podem fazer parte do código. Uma célula com true pode ser booleano ou texto literal, conforme o importador. null quer dizer ausência de valor, enquanto uma string vazia pode significar valor conhecido, porém vazio. Se todos esses casos viram uma célula vazia, a planilha parece organizada mas perde informação para uma importação futura.

Delimitadores não eliminam a necessidade de escape. Uma nota como Entregar em Madrid, porta 4 contém vírgula e precisa ficar entre aspas. Uma nota de duas linhas deve manter a quebra dentro de um campo entre aspas. Abrir corretamente em um programa não prova que outro leitor aplicará o mesmo delimitador, codificação ou regra de fim de linha.

Exemplo prático

Use um exemplo pequeno e sintético, não dados reais de clientes. Este JSON contém um cliente, dois pedidos, uma lista de etiquetas, nulo, booleano, códigos com zeros iniciais, vírgula e quebra de linha.

{
  "customer": {
    "id": "00073",
    "name": "Lucía, S.A.",
    "marketingAllowed": false,
    "phone": null,
    "tags": ["atacado", "prioridade"],
    "address": { "city": "Madrid", "postalCode": "08001" }
  },
  "orders": [
    { "id": "ORD-001", "paid": true, "note": "Ligar antes da entrega\na tarde", "items": [{ "sku": "A-01", "qty": 2 }, { "sku": "B-02", "qty": 1 }] },
    { "id": "ORD-002", "paid": false, "note": "Entrega em Valência, recepção", "items": [{ "sku": "C-03", "qty": 4 }] }
  ]
}

Uma exportação com uma linha por item de pedido pode ter as colunas customer.id, customer.name, customer.marketingAllowed, customer.phone, customer.address.city, customer.address.postalCode, order.id, order.paid, order.note, item.sku e item.qty. Na primeira linha ficam "00073", "Lucía, S.A.", false, uma célula vazia, Madrid, "08001", ORD-001, true, uma nota entre aspas com duas linhas, A-01 e 2. Os dados do cliente se repetem porque a linha representa um item, e não um cliente.

Procedimento

Primeiro defina o grão da linha com uma frase verificável: “uma linha é um item de pedido” ou “uma linha é um pedido”. Em seguida liste os caminhos JSON que serão colunas, usando nomes estáveis como customer.address.postalCode. Evite cabeçalhos genéricos como id; eles se tornam ambíguos quando identificadores de cliente e pedido coexistem.

Depois decida como tratar cada array. Para orders e items, uma estratégia normalizada emite uma linha para cada combinação pedido-item e repete campos superiores. Isso ajuda a filtrar quantidades e somar vendas. Se o destino precisa de uma linha por pedido, items pode ser serializado como JSON em uma célula, mas CSV deixa de expor todas as propriedades. Para tags, documente se vai unir valores por ;, criar colunas numeradas ou uma tabela separada. Não invente um separador se uma etiqueta pode contê-lo.

Defina também a representação de tipos. Preserve identificadores e códigos postais como texto; ao importar na planilha, escolha a coluna de texto antes que 00073 vire 73. Represente booleanos com true e false, ou outro par acordado, sem misturar Sim, 1 e true. Escolha uma regra explícita para null, como célula vazia acompanhada de especificação que a diferencie de string vazia. Teste acentos, vírgulas, aspas e quebras de linha.

Por fim, valide com um leitor CSV que siga o formato combinado. Confira a quantidade de linhas: o exemplo tem três itens de pedido. Verifique que uma aspa de dados é duplicada dentro de campo entre aspas e que a quebra de linha não cria registro extra. A ferramenta pode gerar o arquivo; o contrato de integração continua sendo responsabilidade de quem o mantém.

Explicação técnica

O achatamento transforma caminhos de uma árvore em nomes de colunas. customer.address.city preserva o caminho, mas não torna uma hierarquia reversível por si só. Caminhos de objetos são diretos porque um objeto tem um valor por chave. Arrays mudam a relação: uma lista possui zero, um ou muitos valores, enquanto uma tabela precisa escolher entre repetir linhas, unir valores ou criar outra tabela.

A estratégia de linhas repetidas se parece com tabelas relacionadas de banco de dados. Para cada entrada de orders[0].items, o exportador copia valores de customer e orders[0]. Assim é possível somar quantidades sem analisar JSON dentro de uma célula. O custo é duplicação. Se alguém altera o nome do cliente em apenas uma linha, as linhas entram em conflito. Por isso CSV costuma ser formato de troca ou análise, não a única fonte de verdade.

A RFC 4180 exige aspas para campos com vírgulas, aspas ou quebras de linha; uma aspa no dado é escrita duas vezes. Não substitua simplesmente vírgulas por ponto e vírgula: isso altera o conteúdo e falha se o consumidor espera vírgulas. Especifique codificação e fins de linha, pois CSV não carrega metadados confiáveis para todas as decisões de importação.

Erros frequentes

Uma falha comum é escolher o primeiro elemento de uma lista e descartar o restante. Exportar uma linha por pedido guardando apenas o primeiro item parece funcionar, mas perde dados silenciosamente. Outra é unir valores por vírgula sem escape: Lucía, S.A. parece duas colunas. Uma terceira é usar coluna vazia para null e ""; nenhuma reconstrução posterior consegue saber qual valor existia.

Também falha supor que uma planilha preservará tipos. Ela pode converter 00073 em 73, entender ORD-001 como data conforme configuração local ou mostrar números grandes em notação científica. Se o arquivo será importado novamente, entregue uma especificação de colunas e amostra de teste. Guarde o JSON original ou um identificador de lote para localizar a origem.

CSV bem formado também não é automaticamente dado seguro. Uma célula controlada por usuário iniciada por =, +, - ou @ pode ser tratada como fórmula em certos programas. Para exportações destinadas a planilhas, aplique e teste uma mitigação apropriada ao destino. Não modifique dados silenciosamente em integração crítica sem documentar o contrato.

Considerações

Pergunte quem lerá o arquivo antes de desenhar colunas. Para análise rápida, uma tabela larga e repetida pode ser adequada. Para migração, vários CSV relacionados — clientes, pedidos e itens — unidos por identificadores textuais podem ser melhores. Para backup, JSON preserva muito mais a estrutura original. Os mesmos dados podem exigir três exportações diferentes sem que uma seja universalmente correta.

Mantenha uma tabela de mapeamento junto ao exportador: caminho JSON, coluna CSV, tipo esperado, transformação, tratamento de nulo e exemplo. Inclua casos-limite, como array vazio, nota com aspas e cliente sem telefone. Versione o mapeamento quando uma coluna mudar. Um consumidor que depende de customer.id não deveria descobrir por acaso que ele passou a se chamar client_code.

Privacidade também afeta a conversão. Reduzir campos antes de exportar costuma ser mais seguro que escondê-los depois em uma pasta de trabalho compartilhada. O exemplo é inventado para ser reutilizável. Se o arquivo contém dados pessoais, restrinja acesso, evite serviços não avaliados e siga as obrigações aplicáveis à organização responsável.

Limitações

Nenhuma conversão JSON→CSV preserva automaticamente todos os significados de qualquer documento. CSV não diferencia sozinho número de texto, nulo de vazio, objeto ausente de objeto vazio, ou lista de um elemento de texto que parece lista. Uma ida e volta pode reconstruir linhas escolhidas se armazenar regras extras, mas não a árvore original em todos os casos.

Este guia não certifica compatibilidade com uma planilha específica, não substitui contrato de API, testes de integração nem orientação profissional sobre dados regulados. O comportamento de importação depende do programa, configurações regionais e codificação. Teste sempre cópias sintéticas e confirme o destino real antes de processar lote importante.

Lista de verificação

Defina o que uma linha representa e quais caminhos JSON serão colunas. Escolha e documente uma estratégia para cada array e sua duplicação. Preserve identificadores com zeros iniciais como texto. Defina booleanos, nulo e string vazia sem ambiguidade. Faça escape de vírgulas, aspas e quebras de linha segundo CSV. Teste o JSON sintético, conte linhas e leia o arquivo com o consumidor pretendido. Guarde o JSON original quando fidelidade estrutural importar e publique um mapeamento versionado para que outra pessoa reproduza a exportação.