Converter JSON em CSV

Achatando uma árvore em uma grade

JSON é uma árvore e CSV é um retângulo, e toda a conversão é a questão de como um vira o outro. O caso simples é um array de objetos que compartilham as mesmas chaves — cada objeto é uma linha, cada chave uma coluna, e nada se perde. É assim que a maioria das respostas de API e exportações se parece, e é por isso que isto costuma simplesmente funcionar. Tudo o que é complicado vem de documentos que não têm esse formato.

Objetos aninhados são achatados juntando as chaves, então um objeto de endereço dentro de um cliente vira colunas como address.city e address.postcode — uma convenção que toda planilha aceita e nenhum padrão define. Chaves que aparecem em alguns objetos e não em outros viram colunas vazias nas linhas que não as tinham, e essa é a resposta certa: a alternativa é descartar dados que só alguns registros trazem.

Arrays aninhados são onde uma grade realmente não consegue acompanhar. Um registro com três itens de pedido dentro é uma linha contendo uma lista, não três linhas — transformá-lo em três duplicaria todos os outros campos e mudaria, sem avisar, o que os dados significam. Então um array de objetos é expandido em linhas e os demais são gravados na própria célula como texto. Se o que você precisa são os itens do pedido, e não os pedidos, aponte a conversão para esse array; uma árvore com duas listas lado a lado não tem um único retângulo correto, e escolher um é uma decisão que só você pode tomar.

Dois detalhes pegam na saída. Valores que contêm vírgula, aspas ou quebra de linha vão entre aspas para sobreviver — o que é CSV correto e parece estranho se você olhar o arquivo bruto. E um identificador numérico longo é um risco quando o CSV chega a uma planilha: o Excel vai lê-lo como número, arredondá-lo depois de quinze dígitos e tirar qualquer zero à esquerda, o que é um problema causado pela planilha, e não pela conversão.

Quando você precisa de outra coisa

O jq é a ferramenta certa quando o formato precisa ser decidido, e não adivinhado: jq -r '.orders[] | [.id, .customer.name, .total] | @csv' pega exatamente os campos que você quer, exatamente do nível em que você os quer, que é o controle que um achatador automático não consegue oferecer. Ele também processa em fluxo, então o tamanho do arquivo deixa de ser uma preocupação.

Para dados aninhados em geral, o Miller — mlr --ijson --ocsv flatten — e o pandas.json_normalize do Python dão controle explícito sobre até que profundidade achatar e o que fazer com as listas. E, se o JSON é realmente hierárquico, e não tabular, convertê-lo em CSV pode ser simplesmente a ideia errada — um banco de dados ou um arquivo JSON delimitado por linhas mantém a estrutura que uma grade está prestes a descartar.