how to flatten the JSON data：ネストを展開・結合・そのまま残す判断ガイド（2026年）

JSONデータをフラット化するとはどういうことか

how to flatten the JSON dataとは、木構造のJSONを、情報を失わずに表に変える作業です。CSVはフラットです。行と列しかありません。JSONは木です。オブジェクトの中にオブジェクトがあり、オブジェクトの中にリストがあり、リストの中にオブジェクトがあります。フラット化とは、この木を表に変えることです。すべてのフラット化ツールは同じ3つの操作を行います。その3つを名前で呼べるようになれば、どのツールも予測できるようになります。

3つの操作とは次の通りです。ネストしたオブジェクトはドット記法の列になります（customerはcustomer.nameとcustomer.cityになります）。プレーンな値のリストは1セルに結合されます（itemsはbook; penになります）。そして、分析したいリストは1アイテム1行に展開されます。これをエクスプロードと呼びます。どのリストにどの操作を適用するか。それがこの作業の全体であり、これはデフォルトではなく判断です。

何よりも先に、1つの区別が重要です。JSONをCSVにフラット化することについての以前のガイドでは、このサイトのコンバーターのフラット化トグルが実際に何をするのかを、セル単位で、端的なケースも含めて記録しています。このガイドは作業そのものについてです。ネストしたJSONデータがあり、フラットな表がほしい。トグルがあるかどうかに関わらず、どのツールでも、各部分をどうフラット化するかを自分で選べます。

実例：ネストした3件の注文

このガイドのすべての例は、同じ小さな実例データを使います。ネストしたcustomerオブジェクトとitemsリスト、そして3件目の注文にある空のリストを持つ、3件の注文です。手で確認できるほど小さく、すべての判断を示せるほどネストしています。

orders.json、実例で使うデータ

[
  { "orderId": "A-101", "customer": { "name": "Ana", "city": "Madrid" }, "items": ["book", "pen"], "total": 19.99 },
  { "orderId": "A-102", "customer": { "name": "Ken", "city": "Osaka" }, "items": ["lamp"], "total": 42.50 },
  { "orderId": "A-103", "customer": { "name": "Lina", "city": "Berlin" }, "items": [], "total": 7.25 }
]

Move 1：ネストしたオブジェクトをドット記法の列に変える

ネストしたオブジェクトには名前付きのフィールドがあるので、フラット化は機械的です。木を下へたどり、キー名をドットでつなぎます。customer.nameにはAnaが入り、customer.cityにはMadridが入ります。元のネストは消えますが、何も失われません。ドット付きの名前が、元の場所への完全なパスを記録しているからです。

これはすべてのツールが一致する操作です。オンラインコンバーターも行いますし、pandasのjson_normalizeも行いますし、jqもパスを明示的に指定すれば行います。判断が必要なのは深さだけです。1段や2段のドットなら読みやすいままです。4段（a.b.c.d）になると、通常は表の行になるはずのなかった構造をフラット化しているサインです。そのケースは下の深さのセクションで扱います。

Move 1を適用：オブジェクトをドット記法に、リストを結合

orderId,customer.name,customer.city,items,total
A-101,Ana,Madrid,book; pen,19.99
A-102,Ken,Osaka,lamp,42.50
A-103,Lina,Berlin,,7.25

Move 2：短いリストを1セルに結合する

プレーンな値のリスト、つまりそれ自体にネストのない文字列や数値のリストは、区切り文字で値を結合することで1セルにフラット化されます。このサイトのコンバーターはセミコロンにスペースを続けたもの（book; pen）で結合します。セミコロンは意図的な選択です。カンマはCSVの区切り文字と衝突しますが、セル内のセミコロンはあいまいでなく、Excelを往復しても残ります。

結合すると1レコード1行が保たれます。これはリストが主題ではなく文脈である場合にほしい形です。記事のタグ、プロフィールのスキル、商品のカテゴリは、読むことはあっても、個々の値を合計したり数えたりすることはありません。そうしたリストは結合します。

リストを結合：注文ごとに1行、リストは1セルに

orderId,items
A-101,book; pen
A-102,lamp
A-103,

Move 3：リストを1アイテム1行に展開する

展開は、ほとんどの人が見逃す操作です。なぜなら、ほとんどのコンバーターがこれを提供していないからです。リストを1セルに押し込める代わりに、1アイテムごとに1行を作り、親のフィールドをすべての行に繰り返します。注文A-101は2つのアイテムがあるので2行になります。bookの行とpenの行で、それぞれにAna、Madrid、19.99が付きます。3件の注文は4行になります。A-103の空のリストもアイテムが空の1行を生むので、その注文自体が黙って消えることはありません。

リスト自体が分析の単位である場合に展開します。合計する明細行、数えるイベント、絞り込む取引です。そうしたリストを代わりに結合すると、アイテム単位の数値はテキストセルの中に閉じ込められ、表計算の数式ではきれいに取り戻せません。経験則はこうです。リスト内の個々の値で絞り込み、数え、合計することがいつかあるなら、展開します。リストを全体として読むだけなら、結合します。

展開すると、実例はヘッダーを含めて5行になります。A-101が2回（book、次にpen）、A-102が1回（lamp）、A-103がアイテム空で1回です。注文のフィールドはすべての行に繰り返されます。冗長に見えますが、それがまさに要点です。各行が今や1つの分析可能な事実になっています。

展開するか結合するか：リストの意味で決める

展開か結合かの判断は、フラット化が静かに間違う唯一の場所です。なぜなら、どちらの出力も正しいCSVに見えるからです。明細行を結合したリストはExcelで問題なく開きますし、アイテム単位の価格がもう回復できないテキストになったことを警告してくれるものは何もありません。フラット化する前に、リストごとに1つの質問をしてください。そうすれば選択は自ずと決まります。

このリスト内の個々の値で、絞り込み、数え、合計をしますか。するなら展開します。明細行、イベント、取引、測定値はすべてここに入ります。
リストを全体として読むだけですか。そうなら結合します。タグ、カテゴリ、スキル、ラベルはすべてここに入ります。
迷いますか。展開します。展開した表はいつでもグループ化して結合セルに戻せますが、結合したセルは確実に行に戻して分割できません。区切り文字が値の中にも現れることがあるからです。
リストにはプレーンな値ではなくオブジェクトが入っていますか。そうなら、どちらの操作も直接は当てはまりません。オブジェクトのリストは、結合するとJSONテキストのセルに潰れてしまいますし、展開する前にフィールドをドット記法にする必要があります。そのケースは深さのセクションを見てください。

どこまで深くフラット化すべきか

葉まで全部フラット化すると徹底しているように感じますが、最悪の表が生まれます。4段のドット付き名前を持つ列が何十もでき、そのほとんどが空で、どれも読みやすくありません。実際に使う深さまでフラット化します。絞り込みや並べ替えをするフィールドには列を与えます。文脈の中で読むだけなら、そのサブツリーは1つのJSONテキストセルとして残します。

実用的な停止規則はこうです。2段から3段の深さまでフラット化し、それより深いものはJSONテキストとして残します。たとえば配送追跡のオブジェクトのリストは本物のデータですが、めったに列に属しません。JSONテキストを保持する追跡セル1つで表は読みやすいままになり、元のJSONファイルに完全な詳細が残ります。フラット化したCSVはデータの派生ビューであり、置き換えではありません。ですから元のJSONファイルは残してください。

不揃いなデータ：欠けたキー、空のリスト、null

実際のJSONは不揃いです。あるレコードにあるフィールドが、次のレコードにはありません。あるリストは空で、ある値はnullです。フラット化はこの3つすべてを同じ退屈な規則で処理します。退屈であることがほしい性質です。ヘッダー行は、データのどこかに現れるすべてのキーの和集合であり、キーが欠けたレコードはそこに空のセルを得ます。エラーなし、行の脱落なし、目に見える空のセルがあるだけです。

空のリストとnullも、どちらの操作でも同じ規則に従います。結合すれば、空のリストは空のセルになります。展開すれば、空のリストでもアイテムが空の1行が生まれるので、親のレコードが残ります。リスト内のnullは、区切り文字の間の空の区間になります。mug、null、plateのリストはmug; ; plateに結合され、nullがあった場所にちょうど隙間が見えます。

nullと空の区間、実際のエンジンで検証済み

orderId,items
A-101,book; pen
A-103,mug; ; plate

レシピ1：Python、json_normalizeとexplode

pandasを使うPythonが最も寛容なルートです。json_normalizeがオブジェクトをフラット化し、explodeがリストを処理するからで、読みやすい2行で済みます。3件の注文の実例で実行すると、json_normalizeはorderId、items、total、customer.name、customer.cityの列を生成し、itemsに対するexplodeで3行が4行になり、空のリストはアイテムが空の1行を残しました。

flatten.py、json_normalizeとexplode（検証済み）

import json
import pandas as pd

rows = json.load(open('orders.json'))
df = pd.json_normalize(rows)
flat = df.explode('items')
flat.to_csv('orders-flat.csv', index=False)

結合の操作がほしくて展開が不要なら、explodeの行を省きます。json_normalizeはリストをリストのまま残し、1行の結合でセミコロン区切りのセルに変えられます。同じスクリプトが両方の判断をカバーするので、フラット化が1回限りでない場合に手に取るべきレシピです。

レシピ2：jq、1コマンドで展開

jqは、スクリプトファイルもjq自体以外の依存関係もなしに、1コマンドでリストを展開します。下のレシピは各注文を変数に束縛し、そのitemsリストが空かどうかを調べ、空ならアイテムが空の1行を出し、そうでなければアイテムごとに1行を出します。実例で実行すると、展開のセクションで説明した通りのちょうど5行の出力が得られました。A-101が2回、A-102が1回、A-103がアイテム空で1回です。

jq：itemsを1アイテム1行に展開（検証済み）

jq -r '. as $rows | (["orderId","name","city","item","total"] | @csv), ($rows[] | . as $o | if (.items | length) == 0 then [$o.orderId, $o.customer.name, $o.customer.city, "", $o.total] | @csv else (.items[] | [$o.orderId, $o.customer.name, $o.customer.city, ., $o.total] | @csv) end)' orders.json

空のリストの分岐は、ネット上のjq展開レシピのほとんどが省略している部分であり、データを失う部分です。これがないと、アイテムのない注文は出力から完全に消えてしまいます。現在のデータに空のリストがなくても残してください。次のファイルにはあるからです。

レシピ3：Excel Power Query、コードなし

行き先がどうせExcelなら、Power QueryはコードなしでJSONをフラット化します。データ、データの取得、ファイルから、JSONからの順にインポートすると、Power Queryは各レコードを行として表示し、ネストした列はまだ折りたたまれたままです。2つの展開操作は、このガイドの2つのリスト操作にちょうど対応します。間違った方を選ぶことは、どのツールでも同じ間違いです。

レコード列（customer）を展開矢印で展開し、ほしいフィールドにチェックを入れます。nameとcityがプレーンな列になります。これがMove 1です。
リスト列（items）を展開矢印で展開し、新しい行に展開を選んで展開します。1アイテム1行になり、親のフィールドが繰り返されます。これがMove 3です。
リスト列を展開し、値の抽出を選び、セミコロンとスペースの区切り文字で1セルに結合します。これがMove 2です。
必要な深さまで表がフラットになるまで、ネストした列ごとに繰り返し、閉じて読み込みます。

レシピ4：オンラインコンバーターは結合するが展開しない

このサイトの無料コンバーターは、フラット化トグルをオンにしてフラット化します。ネストしたオブジェクトはドット記法の列になり、リストはセミコロン区切りのセルに結合します。まさにMove 1とMove 2です。トグルをオフにすると、ネストした値はセルの中のJSONテキストのまま残ります。これがタイトルにあるネストを残す選択肢です。コンバーターがしないことは展開です。1件の注文を1アイテム1行に変える選択肢はありません。

それはバグではなく、正直な制限です。展開は行数を変えます。これはデータモデリングの判断であり、ワンクリックのコンバーターが黙って行うべきではありません。リストを展開する必要があるなら、上のPythonかjqのレシピを使ってください。結合が正しい判断である多くのファイルにはコンバーターを使ってください。

無料のJSON→CSVコンバーターを開く

元に戻すことはできるか

フラット化は、オブジェクトについては簡単に逆向きにでき、展開したリストについては正確に逆向きにするのが難しいので、計画して臨みます。ドット付きの列は小さなスクリプトでネストしたオブジェクトに戻せますし、何も失われません。ドットが完全なパスを記録していたからです。展開した行は、親キーでのグループ化で戻せ、アイテムを再びリストに集められます。ただし、元のアイテムの順序は行インデックスを残した場合にしか残りませんし、元の空のリストは欠けたものと区別できません。

実用的な規則はそこから従います。フラット化したCSVを唯一のコピーとして扱わないことです。元のJSONファイルを残し、CSVは1つの分析のために作られた派生ビューとして扱い、分析が変わったらJSONから再びフラット化します。ストレージは安いです。構造を静かに失ったCSVをデバッグするより、ソースから再び派生させる方が優れています。

フラット化チェックリスト

JSONファイルをフラット化する前に、この6つのチェックを走らせてください。1分で済みますし、このガイドのすべての失敗モードを捉えます。

まず分析の単位に名前を付けます。1行が注文か、アイテムか、イベントか。その答えが、すべてのリストについて展開か結合かを選びます。
オブジェクトは、絞り込みや並べ替えをする深さまでフラット化し、それより深いサブツリーはJSONテキストとして残します。
すべてのリストを確認します。プレーンな値のリストはきれいに結合も展開もできますが、オブジェクトのリストは、どちらの操作も意味を持つ前にフィールドをドット記法にする必要があります。
不揃いなデータを想定します。欠けたキーは空のセルに、空のリストは空の1行かセルに、nullは空の区間になります。
キー名の中のドットに注意します。version.2のようなキーは同じ名前のネストしたパスと衝突し、どちらか一方が黙って勝ちます。
元のJSONを残します。フラット化したCSVは派生ビューであり、真実の源ではありません。

よくある質問

JSONデータをフラット化するとはどういうことですか？

ネストしたJSONの木を、行と列からなるフラットな表に変えることです。ネストしたオブジェクトはドット記法の列になり（customer.name）、プレーンな値のリストは1セルに結合されるか（book; pen）、1アイテム1行に展開され、フラット化しないものはセルの中のJSONテキストとして残ります。

CSVに変換する前にネストしたJSONをフラット化すべきですか？

はい。CSVのセルにJSONテキストがほしい場合を除きます。CSVにはネストがありません。ですからネストしたデータはフラット化するか、結合するか、テキストとして残すかのいずれかが必要です。トグルをオンにしてフラット化すれば、絞り込みや並べ替えができる本物の列が得られます。オフにすると、ネストした値が1セル内の読みやすいJSONテキストとして残ります。

JSON配列を1アイテム1行にフラット化するにはどうすればいいですか？

展開します。Pythonでは、pd.json_normalize(rows)の後にdf.explode('items')です。jqでは、各レコードを変数に束縛し、アイテムごとに1行を出し、アイテムのないレコードが落とされないよう空のリストに対する明示的な分岐を入れます。両方のレシピはこのガイドにあり、実例で検証済みです。

PythonでJSONをフラット化するにはどうすればいいですか？

pandasを使います。ファイルをjson.loadし、pd.json_normalize(rows)でネストしたオブジェクトをドット記法の列にフラット化し、リスト列は区切り文字で結合するか、df.explode('items')で1アイテム1行にします。pandasなしでネストしたオブジェクトだけなら、ドット付きキーを作る小さな再帰フラット化関数でも同じ作業ができます。

ExcelでJSONをフラット化するにはどうすればいいですか？

Power Queryを使います。データ、データの取得、ファイルから、JSONからです。レコード列を展開してネストしたオブジェクトをフラット化し、リスト列は新しい行に展開で展開するか、値の抽出で結合します。ネストした列ごとに繰り返し、閉じて読み込みます。

JSONをフラット化すると空のリストやnullはどうなりますか？

空のセルや空の区間になり、エラーにはなりません。欠けたキーは空のセルになり、空のリストは結合すれば空のセルに、展開すればアイテムが空の1行になり、nullは空のセルになり、リスト内のnullは区切り文字の間の空の区間になります（mug; ; plate）。

何もインストールせずにオンラインでJSONをフラット化できますか？

はい。無料のオンラインコンバーターにJSONを貼り付けるかファイルをアップロードし、フラット化をオンにします。ネストしたオブジェクトはドット記法の列になり、リストは1セルに結合されます。リストを1アイテム1行に展開する必要があるなら、このガイドのPythonかjqのレシピを代わりに使ってください。オンラインコンバーターはリストを結合し、展開はしないからです。

ネストしたJSONですか。ブラウザで無料でフラット化できます

JSONを貼り付けるかファイルをアップロードするだけです。ネストしたオブジェクトはドット記法の列にフラット化され、リストはきれいなセルに結合され、ダウンロードはプレーンなUTF-8です。無料、登録不要、すべてブラウザ内で動作します。

JSON→CSVコンバーターを開く

ガイド一覧