アイキャッチ画像: デスクでチャートをもとにメモと計算をする様子。写真提供: Jakub Zerdzicki on Pexels(無料利用可)
APIはJSONを話します。人間はスプレッドシートでデータをレビューします。この2つの間にあるのが、ソフトウェアで最も一般的なデータ作業の一つ——JSON配列のCSV変換です。そして、簡単に見える作業には必ず鋭い角があります。Excelで非英語文字をすべて文字化けさせるエンコーディング、[object Object] に静かに潰れるネストオブジェクト、カンマを含む値が全列を右にずらす事故。本ガイドは、正しい変換方法と、そもそもCSVが間違った行き先だった場面をカバーします。
実際の変換は、当サイトの無料JSON to CSV変換がヘッダー検出・エスケープ・Excel対応UTF-8出力をすべてブラウザ内で処理します。
CSVとは実際何か
CSV(comma-separated values)はRFC 4180で標準化されたテキスト表形式です。行は改行で区切り、フィールドはカンマで区切り、特殊文字を含む値には3つのルール:
- カンマ・引用符・改行を含む値は二重引用符で囲む
- 引用符付きの値の中の引用符は二重化する:
"→"" - ヘッダー行は任意だが慣例
この形式は現場では欺くほど過小仕様です。セミコロンを使うツール(Excelの欧州ロケールのデフォルト)、タブを使うツール、全部を引用符で囲むツール。RFC 4180版が共通語です——これを作れば、あらゆるスプレッドシートがパースできます。
重要な変換ルール
JSONのオブジェクト配列のCSV変換は3ステップで、各ステップに罠があります:
1. ヘッダーの検出。 ヘッダー行は全オブジェクトのキーの和集合です。罠は形の不揃いなオブジェクト。{"name":"A"} と {"name":"B","age":30} が同じ配列にあれば、ヘッダーは name,age になり、最初の行の age セルは空。それ自体は問題ありません——ただし、10,000オブジェクトの最後にだけ現れるキーは、先頭行だけをサンプリングする変換器だと見落とされ、列が消えたり並びが狂ったりします。正しい変換器は全キーを和集合します。
2. 値のエスケープ。 数値と真偽値はテキストとして通ります。カンマ・引用符・改行を含む文字列はRFC 4180に従って引用符で囲みます。罠は null と undefined。慣例は空セルですが、リテラル文字列 "null" を出力する変換器もあり——静かに生き残るデータ破損バグです。
3. エンコーディングの処理。 痛みの本丸。ExcelがUTF-8を認識するにはファイル先頭のUTF-8 BOM(\uFEFF)が必要です。BOMがないと、Excelはシステムのコードページで非ASCIIテキストを開き、日本語・中国語・アクセント文字が文字化けします。対策は機械的——BOMを先頭に付ける——ですが、知っていなければできません。当サイトの変換ツールは自動で付与します。
ネストデータ:まずフラット化
CSVは二次元、JSONは木構造です。オブジェクト値がさらにオブジェクトや配列の場合、フラット化か文字列化が必要です:
{"user": "ada", "address": {"city": "Tokyo", "zip": "100-0001"}}優先順に3つの選択肢:
- ドット記法でフラット化 —
address.city、address.zipを独立した列に。ネストの形が一貫しているとき最良 - 1セルに文字列化 —
{"city":"Tokyo",...}をリテラルJSONテキストとして。ネスト部がスプレッドシートでほとんど参照されないとき - 捨てる — ネスト部が分析に無関係なとき
素朴な String(value) でネストオブジェクトを文字列化すると [object Object] が生まれます——このステップを忘れた変換器の署名です。CSVに [object Object] を見たら、JSONが正しく扱われていません。
CSVが誤った行き先である場面
CSVの単純さは、データがそれを超えて育つまでは美徳です。次の場合は別のものを:
- 深い/不規則なネスト。 3段のネストを40列のドット記法ヘッダーにフラット化するのは、元のJSONより悪い。ドキュメントストアかParquetを使いましょう
- 数百万行。 スプレッドシートは100万行よりはるかに手前で詰まります。CSVにはスキーマも型も圧縮もない。規模の行き先はParquetかデータベースです
- 精度が重要なとき。 数値はCSVをテキストとして往復し、開いたツールが再パースします——64ビット整数IDはExcelで静かに精度を失います(JSONガイドで述べた2⁵³問題と同じ)
- ストリーミング/差分更新。 CSVはファイル全体の形式で、行を安全に追記するにはデータベースなら無料の再書き込みロジックが必要です
最も恩恵を受けるワークフロー
APIエクスポート。 すべてのREST APIがJSON配列を返し、すべてのビジネスユーザーがスプレッドシートを欲しがる。小さな変換ステップが「エクスポート機能を作って」チケットを代替します。
LLMバッチ出力。 構造化出力やバッチジョブのレスポンスはJSON配列で届きます。CSVに変換すればレビュー可能な表になり、その出力のトークンコストはトークン・コスト計算機で測れます。
ログ分析。 JSON Linesログは1行1JSONオブジェクト——配列まであと一歩の形式です。パース→変換→スプレッドシートでピボットは、小規模なら正当なクイック分析経路です。
全体パイプライン
- JSONフォーマッターで検証——不正な入力を理由に失敗する変換ツールは、紛らわしい方法で時間を浪費させます
- JSON to CSV変換で変換——キー和集合、エスケープ、UTF-8 BOM付与
- Excel/Sheetsで開いて非ASCIIテキストの生存を確認——BOMチェックがエンコーディング戦いのすべてです
- CSVをアーカイブするか先へ。別のペイロードに載せるならBase64エンコーダーが包みます
ネストJSONからCSVへ:実例で学ぶ
実際のAPIレスポンスがフラットであることは稀です。usersエンドポイントを例に:
[
{"id": 1, "name": "Ada", "profile": {"city": "Tokyo", "plan": "pro"},
"roles": ["admin", "editor"]},
{"id": 2, "name": "Alan", "profile": {"city": "London", "plan": "basic"},
"roles": ["viewer"]}
]フラット化ルールを適用すると:
| id | name | profile.city | profile.plan | roles |
|---|---|---|---|---|
| 1 | Ada | Tokyo | pro | ["admin","editor"] |
| 2 | Alan | London | basic | ["viewer"] |
ここに示された判断:
profileはドット記法でフラット化——形が一貫したオブジェクトなので、profile.cityとprofile.planが独立した列に値しますrolesは文字列化——長さの変わる配列には安定した列の形がないため、1セルにJSON文字列として。必要な人はパースできますidはテキストで通過——もしこのIDが2⁵³を超える64ビット整数なら、ここが精度トラップに噛まれる場所です。安全策はIDを最初から最後まで文字列で通すこと
フラット化まで行う変換器には2つの判断を明示する必要があります:ネスト戦略(ドット記法対文字列化対破棄)とエンコーディング(BOMの有無)。当サイトのJSON to CSV変換はネスト値に文字列化、BOMは常時オン——大多数のAPIエクスポートに効く実用的デフォルトです。
CSVとAI:バッチ出力・ログ・LLMデータパイプライン
JSON→CSV変換がAI周りの仕事で特に多いのは、次の3箇所です:
構造化出力のレビュー。 LLMが構造化出力モードでJSON配列を返すとき——たとえば抽出された500エンティティ——最速の人間レビューループは:JSONフォーマッターで検証→CSV変換→スプレッドシートで開く→スポットチェック。表でのレビューは、JSONを目視していては永遠に見つからないパターンエラー(1行だけフィールド欠落、カテゴリラベルの誤字)を捉えます。
バッチジョブの検査。 OpenAI流のバッチジョブは .jsonl ファイル——1行1JSONオブジェクト——を返します。行ごとにパースして変換すれば、ジョブ全体が監査可能な表になります。行ごとのトークン使用量はペイロード内にあり、トークン・コスト計算機がその数を金額に変えます。
データセット準備。 逆方向も重要です。表形式の学習データはスプレッドシートから始まり、CSVになり、ファインチューニングやRAGパイプラインのためにJSONへパースされます。両方向のエスケープ規則を知っていれば、「14,207行目の引用符がエスケープされずインポート全体がずれた」という古典的事故を防げます。
共通項:CSVはレビュー形式、JSONは輸送形式、そして信頼できる変換器がその往復を「退屈」にしてくれます——データパイプラインのステップが持ちうる最高の性質です。
よくある質問
CSV規則はRFC 4180に基づく。ExcelのUTF-8 BOM動作はMicrosoft Excelの文書化されたファイル形式動作に基づく。JSONの文字列化・精度動作はECMAScript仕様に基づく。
