Como converter JSON para CSV: achatar arrays de objetos em linhas e colunas

Por que a forma do seu JSON importa

O CSV é um formato plano e bidimensional: linhas e colunas, nada mais. O JSON é uma árvore que pode aninhar objetos dentro de objetos e arrays dentro de arrays. O caso ideal para a conversão é um array de objetos de nível superior, onde cada objeto vira uma linha e cada chave uma coluna. Tudo mais profundo tem de ser remodelado antes de caber numa grelha.

Como objetos diferentes podem ter chaves diferentes, a linha de cabeçalho deve ser a união de todas as chaves vistas, não apenas as do primeiro objeto. Se ler apenas o primeiro registo, as colunas seguintes desaparecem em silêncio e o ficheiro fica desalinhado.

Achatar objetos e arrays aninhados

O truque padrão é a notação de ponto. Um objeto como {"address":{"city":"Lagos"}} vira uma coluna chamada address.city com o valor Lagos. O aninhamento pode ir tão fundo quanto quiser: user.address.city é perfeitamente válido. Os arrays são indexados por posição, portanto tags com ["api","web"] vira duas colunas, tags.0 e tags.1.

O achatamento funciona bem quando os arrays são curtos e de comprimento fixo. Quando um array pode crescer, as colunas indexadas explodem: um registo com cinquenta etiquetas produz cinquenta colunas. Nesse caso, costuma ser mais limpo manter o array como uma única cadeia unida, como "api;web;csv", ou dividir os dados numa segunda tabela relacionada.

Casos-limite que quebram conversores ingénuos

A falha mais comum são as aspas. Se um valor contém o delimitador (normalmente uma vírgula), aspas duplas ou uma quebra de linha, tem de ir entre aspas duplas, e quaisquer aspas duplas internas devem ser duplicadas. Assim o valor She said "hi" torna-se "She said ""hi""". Ignorá-lo corrompe todas as linhas seguintes.

Outras armadilhas: null versus cadeia vazia (ambos costumam surgir como célula vazia), booleanos e números que uma folha de cálculo pode reinterpretar (um código com zero à esquerda como 007 pode perder os zeros), e a codificação. Escreva sempre em UTF-8 e considere uma marca de ordem de bytes inicial se o ficheiro tiver de abrir corretamente em folhas de cálculo antigas.

Perguntas frequentes

E se o meu JSON for um único objeto e não um array?

Coloque-o num array para obter um CSV de uma linha. Se preferir cada chave na sua própria linha, transponha-o em duas colunas chave,valor.

Que delimitador devo usar, vírgula ou ponto e vírgula?

A vírgula é o padrão da norma CSV. Algumas configurações regionais de folha de cálculo esperam ponto e vírgula; se os seus valores já contêm vírgulas, um ponto e vírgula ou tabulação reduz o escape.

Como impeço que os zeros à esquerda desapareçam?

Os zeros estão no ficheiro CSV; a folha de cálculo remove-os ao tratar a coluna como número. Importe a coluna como texto, ou a folha reformata-a ao abrir.

Posso reconverter o CSV de volta em JSON?

Em parte. As colunas planas reconvertem-se limpo, mas as chaves com notação de ponto precisam de ser re-aninhadas e o CSV perde os tipos, pelo que números e booleanos voltam como cadeias se não os reanalisar.