CSV / JSON 変換

このツールの役割

CSV は表計算ソフト・データベースのエクスポート・分析ダッシュボードが渡してくるもので、JSON は API とコードが求めるものです。このツールは両者を両方向に、ブラウザ内で変換します。CSV を貼り付けると JSON 配列が得られます — ヘッダー行でキー付けされたオブジェクト、あるいはデータにヘッダーがなければ素の配列です。方向を切り替えると JSON 配列が CSV になり、各値が必要なだけちょうど引用符で囲まれます。

作業はお使いの端末で行われます。CSV は顧客リスト・請求書・分析の抽出を人がエクスポートする形式なので、これは重要です。そのどれもどこにもアップロードされません。

カンマで分割するだけでは足りない理由

CSV を読む素朴なやり方 — 各行をカンマで分割する — は本物のファイルで壊れます。形式にエスケープの仕組みがあるからです。二重引用符で囲まれたフィールドは、区切り文字や、2 つ続けて書いた文字どおりの引用符、さらには改行さえ含みえて、その場合 1 つのレコードがファイルの複数行にまたがります。このツールは実際の規則 (RFC 4180) を 1 文字ずつのパーサーで実装しているので、3 つの場合すべてが無事に通ります。

name,note
Grace,"rear admiral, USN"
Ada,"she said ""hello"""
Alan,"two
lines"

この 4 つのレコードは、余分なカンマ・引用符・改行があっても、それぞれ 2 つのフィールドを持ちます。引用が不正なら — フィールドが引用符を開いて決して閉じないなら — 黙って壊れた表ではなく、暴走した引用符が始まった行と列が得られます。

区切り文字はしばしばカンマではない

名前に反して、カンマ区切りの値はしばしばそうではありません。カンマが小数点の区切りである地域 — ヨーロッパ大陸の大半 — では、1,50 がそこでは数値なので、Excel は代わりにセミコロンでエクスポートします。データベースやコマンドラインのツールはしばしばタブ区切りのデータを出し、ログのパイプラインはパイプを好みます。そのどれかをカンマ専用のツールに貼り付けると、非常に幅の広い 1 つの列ができます。最もよくある CSV の苛立ちです。

だから区切り文字は仮定せず検出します。各候補が試され、勝者はすべての行で同じ列数を生むもの — 最も多い数ではなく一貫性です。小数点のカンマだらけのファイルは、そうでなければカンマ区切りに見えてしまうからです。検出した区切り文字は常に表示され、推測が誤っていれば上書きできます。

ヘッダーと出力の形

「先頭行はヘッダー」をオンにすると、その行がキー名を供給し、出力はオブジェクトの配列 — ほぼすべての API が期待する形 — になります。オフにすると、各行が値の配列になり、これはいきなりデータから始まるファイルに欲しいものです。

• ヘッダーよりフィールドの少ない行は、undefined 値のキーではなく、欠けた列に空文字列を得ます。
• 重複するヘッダー名は、互いを上書き (これは黙って列を落とします) せず、一意にされます (id、id_2、id_3)。
• 空のヘッダーセルは column_2、column_3 などになるので、キーが空文字列になることはありません。
• 空行は、表計算ソフトのインポーターがそうするように飛ばされます — 貼り付けたファイルはしばしばはぐれた改行で終わり、そこに空値の行があるとバグに見えます。

データを失えない型変換

CSV のフィールドはすべてテキストです。数値に見えるテキストを JSON の数値に変換するのはたいてい望むことですが — それはデータが黙って壊れる道でもあります。郵便番号 01234 は 1234 になります。20 桁の注文番号は丸められた浮動小数点になります。1.50 と書かれた価格は末尾のゼロを失います。

ここで使う規則は、特別な場合の一覧なしにそのすべてを避けます: 値が数値になるのは、テキストに戻したときに元を正確に再現する場合だけです。42 はそうなるので変換されます。01234 はそうならないので文字列のままです。1.50、+5、1e5、あるいは倍精度が精度を失う点を超えた整数も同じです。文字列の true と false は真偽値になります。空のフィールドは null ではなく空文字列のまま残ります。CSV は「値なし」と「空の値」の違いを表せず、一方をでっち上げることは情報をでっち上げることになるからです。

CSV に戻す

もう一方の向きでは、オブジェクトの配列が、すべてのキーの和集合を最初に現れた順に列とする表になります — なので異なるキーを持つ行も揃い、欠けたキーは空のセルを生みます。配列の配列は行ごとに書き出されます。引用は形式が要求するところにだけ適用されます: 区切り文字・引用符・改行を含む値が囲まれ、内側の引用符が二重にされます。

CSV に表す術のない値 — 入れ子のオブジェクトや配列 — は、平らにしたり落としたりせず、そのセルの中に JSON として書かれるので、変換で何も消えません。null は空のセルになります。