JSON para CSV

JSON é construído para representar dados arbitrariamente aninhados em forma de árvore — objetos dentro de objetos, arrays dentro de objetos, valores de tipos genuinamente distintos lado a lado — enquanto CSV só consegue representar uma tabela plana e uniforme: linhas e colunas, cada linha com o mesmo conjunto de colunas, cada célula um único valor plano. Converter da primeira forma para a segunda necessariamente significa tomar decisões sobre como achatar algo que não se encaixa naturalmente em linhas e colunas, que é onde vive a maior parte da complexidade real desse tipo de conversão — não em ler a sintaxe JSON em si, que é direta, mas em decidir o que uma linha de planilha deveria sequer significar para dados que nunca foram tabulares para começar.

Um objeto aninhado como `{"user": {"name": "Ada", "id": 42}}` não tem uma única coluna óbvia para se tornar em uma tabela plana, então é achatado em duas colunas separadas — `user.name` e `user.id` — com a notação de ponto preservando exatamente de onde cada valor veio na estrutura original. Esta é uma convenção amplamente reconhecida especificamente porque é reversível: uma coluna chamada `user.name` descreve sem ambiguidade um caminho de volta a uma estrutura aninhada, o que importa se o CSV algum dia precisar ser convertido de volta para JSON ou importado em um sistema que entenda caminhos com pontos como campos aninhados.

Arrays aninhados são tratados de forma diferente, e deliberadamente assim: em vez de explodir um array em linhas adicionais — o que mudaria quantas linhas a tabela tem dependendo de quantos elementos aninhados por acaso estão dentro de um registro, um efeito colateral genuinamente surpreendente e frequentemente indesejado — um valor de array é serializado como texto JSON dentro de uma única célula. O número de linhas permanece previsível e corresponde exatamente ao número de registros de entrada, que é quase sempre o que alguém convertendo para uma planilha realmente quer, ao custo de essa célula precisar de análise adicional se seu conteúdo for necessário individualmente.

Respostas de API reais e JSON montado à mão frequentemente contêm registros onde nem todos os objetos têm chaves idênticas — um campo opcional presente em alguns registros e ausente em outros, ou um esquema que evoluiu com o tempo então registros mais antigos e mais novos diferem ligeiramente. CSV não consegue representar essa variação diretamente, já que cada linha precisa se alinhar ao mesmo conjunto fixo de colunas; um programa lendo um arquivo CSV não tem como saber que a uma linha "falta" uma coluna a menos que cada linha tenha explicitamente uma célula para ela. A solução é calcular a união de cada chave vista em cada registro, na ordem em que cada chave foi encontrada pela primeira vez, e preencher uma célula vazia para qualquer registro ao qual falte um campo dado — assim o formato permanece consistente em todo o arquivo sem silenciosamente descartar as colunas de nenhum registro nem desalinhar valores na coluna errada.