JSONをCSVに変換

木構造を表に平らにする

JSONは木構造で、CSVは長方形です。変換とは結局、一方をどうやってもう一方にするかという問題です。きれいに収まるのはすべて同じキーを持つオブジェクトの配列です。各オブジェクトが1行、各キーが1列になり、何も失われません。ほとんどのAPIレスポンスやエクスポートデータはこの形をしているので、たいていはそのままうまくいきます。やっかいなことはすべて、この形になっていない文書から生じます。

ネストしたオブジェクトはキーをつなげて平らにするので、顧客の中にある住所オブジェクトはaddress.cityやaddress.postcodeのような列になります。これはどの表計算ソフトでも扱える慣習ですが、標準規格で定められたものではありません。一部のオブジェクトにしか出てこないキーは、それを持たない行では空になる列になります。これが正しい答えです。ほかの選択肢は、一部のレコードにしかないデータを捨てることだからです。

ネストした配列は、表では本当に追いきれない部分です。3つの注文明細を持つ1件のレコードは、リストを含む1行であって、3行ではありません。3行にすればほかの項目がすべて重複し、データの意味が黙って変わってしまいます。そこで、オブジェクトの配列1つだけを行に展開し、それ以外の配列はテキストとしてそのセルに書き込みます。必要なのが注文ではなく注文明細なら、変換の対象をその配列に向けてください。2つのリストが並ぶ木構造には唯一の正しい長方形がなく、どれを選ぶかはあなたにしか決められません。

書き出しの際に効いてくる細かい点が2つあります。カンマ、引用符、改行を含む値は、崩れないように引用符で囲みます。これは正しいCSVですが、生のファイルを見ると奇妙に見えます。また、長い数値の識別子はCSVが表計算ソフトに渡った時点で危険になります。Excelはそれを数値として読み込み、15桁を超えた分を丸め、先頭のゼロを取り除いてしまいます。これは変換ではなく、表計算ソフトが持ち込む問題です。

ほかの目的には

形を推測ではなく決めたいときは、jqが適したツールです。jq -r '.orders[] | [.id, .customer.name, .total] | @csv'は、必要な項目を必要な階層から正確に取り出します。これは自動の平坦化ツールにはできない制御です。ストリーム処理もできるので、ファイルサイズを気にする必要もなくなります。

ネストしたデータ全般には、Miller（mlr --ijson --ocsv flatten）やPythonのpandas.json_normalizeを使えば、どの深さまで平らにするか、リストをどう扱うかを明示的に制御できます。そしてJSONが表形式ではなく本当に階層的なデータなら、CSVへの変換そのものが誤った考えかもしれません。データベースや行区切りのJSONファイルなら、表にすると捨ててしまう構造を保てます。