What does flattening a JSON mean? ネスト解除の意味を解説（2026年ガイド）

結論だけ知りたい方へ

What does flattening a JSON mean? ネストしたJSONデータ、つまりオブジェクトの中のオブジェクトやオブジェクトの中のリストを、何もネストしていない形に書き直すことです。すべての値はトップレベルに、1セル1つの値で収まり、customer.cityのようなドット記法の名前が各値の出所を示します。フラット化されたレコードの深さは1です。値が作られたり消されたりすることはありませんが、形状は変わります。木が表になるのです。CSVとスプレッドシートが必要とするのはまさにこの形であり、だからこそJSONからCSVへの変換は、トグルが何と言おうと、データをフラット化するのです。フラット化を理解すれば、JSONからCSVへの変換で起きていることがすべて説明できるようになります。

「フラット」の意味：データにおける「平ら」の正体

JSONは一度忘れて、言葉の意味から考えてみましょう。平らな面とは、でこぼこも層も隠れた深さもないものです。すべてが同じレベルにあり、一度に見渡せます。データの世界では、このイメージをそのまま借りています。フラットなデータとは、ネストのないデータです。すべての値がトップレベルにあり、1つのスロットに1つの値、他の何かの中に隠れているものは何もありません。表の行や列は、どこを指しても同じ意味を持ちます。見る人全員が同じ情報を得られるのが、フラットの強みです。

スプレッドシートの1行は、フラットなデータの最も純粋な例です。1行、1組の列、1セルに1つの値。C4セルの値が、別のスプレッドシートを含んでいることはありません。テキストか、数値か、何もないかのどれかです。それがフラットということです。セル同士が入れ子にならないからこそ、合計や並び替えといった表計算の操作がそのまま通用します。

それに対してJSONは、ほとんどフラットになりません。ネストするのです。オブジェクトがオブジェクトを持ち、配列がオブジェクトを持ち、オブジェクトが配列を持つ。顧客レコードは住所オブジェクトを持ち、その中に座標、さらにその中に2つの数値が入ることもあります。このネストこそJSONの存在理由であり、同時に「フラット化」という言葉が生まれた理由でもあります。木を表に流し込むには、枝に何らかの処理が必要です。フラット化とは、その処理の名前です。この「ツリー」という言葉は、データの世界の標準的な呼び方です。根から枝へ、枝から葉へと広がる様子が、まさに木に見えるからです。

「JSONをフラット化する」と言ったら、こういう意味です。このネスト構造を書き直して、すべての値がトップレベルに来るようにし、どこから来たかが分かる名前を付けること。値そのものは変わりません。変わるのは値の住所です。ネストしたオブジェクトをたどるパスから、1つのフラットな名前へと変わります。この処理は、データの値を変換するのではなく、値の置き場所と名前付けを変えるだけです。その点を最初に押さえておくと、後のルールがすんなり理解できます。

なぜこの言葉があるのか：JSONはネストし、CSVはしない

この緊張関係を1枚の絵で説明します。JSONは木です。枝があり、枝分かれがあり、葉があります。CSVは表です。行と列があり、それ以上深いものはありません。CSVのセルはオブジェクトを保持できません。テキストしか保持できないのです。だからJSONからCSVへの変換は、必ず同じ問いに答えなければなりません。ネストをどうするのか、と。JSONは深さを許し、CSVは深さを許しません。この対立が、JSONとCSVの間で変換が常に必要になる根本理由でもあります。

答えは数通りしかありません。その中で最も一般的なのが「フラット化」です。APIが返しそうな、本物のレコードを見てみましょう。このレコードは、多くのWeb APIが実際に返す形をそのまま使っています。架空の単純化した例ではなく、実務で出会う典型です。

Nested: the address object lives inside the customer record

{
  "id": "A-101",
  "customer": { "name": "Amelia", "city": "Austin" },
  "tags": ["new", "vip"]
}

customerオブジェクトは1つ下の階層にいます。tagsのリストも1つ下の階層です。CSVには「1つ下の階層」がありません。だからフラット化した版では、すべてを表面に引き上げます。このページのコンバーターで検証した出力です。この引き上げがフラット化の核心です。表面に来た値には、どこから来たかを示す新しい名前が付きます。

フラット化が実際にやること、ステップごと

フラット化は1つの裏技ではありません。どこにでも適用される4つの小さなルールです。上のレコードを、このページのコンバーターにフラット化オンで通すと、正確に次の結果が出ます。ビルドマシンで検証済みです。これらのルールは、コンバーターのフラット化トグルがオンのときに必ず適用されます。設定を変えなければ、毎回同じ結果になります。

Flattened: depth 1, one value per slot (verified converter output)

{
  "id": "A-101",
  "customer.name": "Amelia",
  "customer.city": "Austin",
  "tags": "new; vip"
}

ルール1：ネストしたオブジェクトはドット記法の列になります。値へのパスが名前になります。customer.name、customer.cityのことです。ドットはパンくずリストに過ぎません。Ameliaの名前は何も変わっていません。変わったのは住所のラベルだけです。ドットの数はネストの深さを表します。3階層のネストなら、ドットが2つ付いた名前になります。パスを読むだけで、元の場所が復元できる仕組みです。

ルール2：単純な値の短いリストは、1つのセルに結合されます。「new」と「vip」は「new; vip」という1つのテキストになりました。2つの値は残っていますが、今はセパレーター付きの1つの文字列です。2つあったという事実は、もう機械には読めなくなっています。区切り文字はこのページのコンバーターではセミコロンとスペースです。この選択は道具によって変わるので、他のツールの出力を読むときは区切り文字の確認が必要です。

ルール3：オブジェクトのリストは道理のある方法で結合できないので、1つのセル内のJSONテキストに折りたたまれます。[{"sku":"B1","qty":2}]というitemsリストは、引用符で囲まれた1つの長いセルになります。データは生き延びていますが、構造としてではなく、再解析が必要なテキストとしてです。このセルはCSVの中ではただの長いテキストなので、表計算ソフトでは内容が読みにくく見えます。元のオブジェクトのリストに戻すには、再びパースする処理が必要です。

ルール4：nullと空の値は空のセルになります。フラットな表には「明示的に何もない」と書く方法がないので、nullは空白に消えます。これは覚えておいてください。フラット化の後では、「nullだった」ことと「空のリストだった」こと、「そもそもなかった」ことを区別できません。この区別の喪失は、後でJSONに戻そうとするときに痛みになります。空白のセルから元の状態を復元する方法は、データ自体には残っていないからです。

これと、同じデータをフラット化オフで処理した結果を比べてみると、この言葉の意味全体が見えます。トグルをオフにすると、customerオブジェクトは{"name":"Amelia","city":"Austin"}というJSONテキストの1つのセルとして残ります。データは失われていませんが、フラットでもありません。セルの中にはまだネストがあり、スプレッドシートには読めない塊が表示されます。フラットとは、どこまでもフラットという意味です。1セルに1つの値、例外なしです。この見比べが、フラット化という言葉の意味を直感的に掴む一番の近道です。同じ入力でトグルのオンとオフを切り替えるだけで、違いが一目瞭然になります。

混同を解く：フラット化はミニファイではない

5人の初心者に「JSONをフラット化する」とは何かと聞くと、そのうち1人はこうします。改行とスペースをすべて消して、1行の巨大なテキストを作ります。それはミニファイであってフラット化ではありません。この区別が重要なのは、言葉が似ているのに、まったく異なることを表しているからです。この混同は、技術者でない方に限った話ではありません。データに慣れた人でも、口頭の説明だけでは取り違えることがあります。言葉の定義を文字で確認する価値があります。

ミニファイが変えるのは空白です。フラット化が変えるのは構造です。ミニファイされたJSONファイルは、まだネストしています。ただ1行になっているだけです。ビルドマシンで検証したところ、同じレコードのミニファイ版と整形版をパースするとバイト単位で同一の構造になり、customerオブジェクトはどちらの場合もオブジェクトのままでした。木は動いていません。変わったのは化粧だけです。つまり、ミニファイはファイルの見た目の問題で、フラット化はデータの設計の問題です。扱うレイヤーがまったく違うのです。

Minified is still nested (depth 2); flattened is depth 1

# minified: no whitespace, STILL nested -> customer is an object
{"id":"A-101","customer":{"name":"Amelia","city":"Austin"},"tags":["new","vip"]}

# flattened: depth 1, nothing nested at any width
{"id":"A-101","customer.name":"Amelia","customer.city":"Austin","tags":"new; vip"}

なぜ混同が起きるのか。日常の言葉では「flat」が「1行に」という意味で使われることがあるからです。「1行にフラット化して」のような言い方です。データの世界では「flat」は「ネストがない」という意味です。チュートリアルが「スプレッドシートに取り込む前にJSONをフラット化しろ」と言ったら、構造の方の意味です。ドット記法の列、結合されたリスト、1セル1つの値のこと。空白を消しても、インポートは何も改善しません。スプレッドシートのインポートウィザードは、構造を理解してくれません。空白の有無ではなく、列の形を見ているからです。だから空白の削除は何の助けにもならないのです。

同じ考え方が別の名前を着ている

フラット化の意味を知ると、別の服を着た同じものが至るところで見えるようになります。Pythonのpandasライブラリではjson_normalizeという関数がそれです。「normalize」がまさにフラット化の仕事をしています。ネストしたオブジェクトがドット記法の列になるのです。これまでのテストで検証したところ、このページのコンバーターと同じように、customer.addressがcustomer.cityにフラット化されました。名前は違っても、やっていることは同じです。木を表に直すという操作は、道具を問わずデータ処理の基本中の基本です。

ExcelのPower Queryでは、ボタンに「展開」と書いてあります。ネストしたレコードの列にある小さな両矢印をクリックすると、新しい列に展開されます。同じ考え方を、より親しみやすい動詞で言ったものです。SQLではUNNESTが、ネストした配列を行に変えます。同じ一族です。Power Queryの「展開」は、Excelの日本語版でも同じ名前で見つかります。ネストしたデータの列があれば、ぜひ一度試してみてください。

正直な注意点を1つ。コマンドラインのJSONツールjqでは、「flatten」がもっと狭い意味で使われます。jqのflattenはネストした配列を1つの配列に畳むだけで、オブジェクトをドット記法のパスに変えることはありません。jqのチュートリアルが「flatten」と言ったら、どちらの意味かを確かめてから解釈してください。データの世界は言葉を大雑把に使い回します。この1点だけは、言葉の意味が本当に分かれています。この違いを知らずにjqの記事を読むと、期待と違う結果になって戸惑います。コマンドの名前より、その説明文を読む習慣が役立ちます。

フラット化には、よく似たいとこが2ついます。3つとも混ざりやすいので名前を挙げておきます。フラット化は1レコード1行を保ち、列を横に広げます。エクスプロードは列を保ち、行を増やします。リストの各要素が1行ずつになり、レコードの残りは繰り返されます。結合はリストを1つのセルに畳みます。上のルール2が短いリストにやっていることです。『how to flatten the JSON data：ネストを展開・結合・そのまま残す判断ガイド（2026年）』では、展開と結合の判断を実際の例で解説しています。コンバーター自身のフラット化スイッチがセル単位で何をするかは、『JSONをフラット化してCSVに変換する方法：トグルが実際にやっていること（2026年ガイド）』で詳しく見せています。この3つの区別が付くと、JSONからCSVへの変換の選択肢がクリアになります。目的に応じて、広げるのか、増やすのか、畳むのかを選べるようになるからです。

フラット化が失わせるもの

フラット化は誠実な作業ですが、情報を失う作業でもあります。何を失うのかは、クリックする前に名前を挙げておく価値があります。第1に、形状は二度と戻りません。フラット化の後、cityとstateが1つの住所オブジェクトの兄弟だったことを記録するものは何も残りません。接頭辞を共有する2つの列があるだけです。フラット化の前に、この4つの損失を頭に入れておくと、後で「こんなはずでは」と慌てずに済みます。どれも対処法のある損失です。

第2に、ドット記法には誰も警告してくれない曖昧さがあります。JSONのトップレベルに文字通り「a.b」というキーが存在し、かつネストしたオブジェクトaの中にキーbもあると、両方が同じ列名にフラット化され、一方の値が静かにもう一方を上書きします。実務ではまれですが、当たると厳しい。この衝突を避けるには、元のキーにドットが含まれていないかを確認します。実務のデータでは、キーがドットを含むことはまれなので、ほとんどの場合は心配いりません。

第3に、結合されたリストは個数の情報が失われます。「new; vip」は1つの文字列に見えます。CSVを読むプログラムは、セパレーターで分割しない限り、それが2つのタグだったことを知りません。タグ自体にセミコロンが含まれたら、その分割すら壊れます。この性質は、タグやカテゴリのような複数選択のデータを扱うときに特に意識する必要があります。個数をデータとして残したいなら、エクスプロードという別の選択肢があります。

第4に、型が崩れます。101は文字としての「101」になります。trueは文字としての「true」になります。CSVを開く側がそれをどう意味付けるかを決めます。特にExcelはデータの再解釈が大好きです。先頭のゼロは消え、長いIDは指数表記になります。フラット化は値を生き延びさせました。でもスプレッドシートを生き延びられるかは別問題です。この再解釈は、フラット化のせいではなく、表計算ソフトの仕様です。CSVファイル自体は正しいテキストを保持しています。開く側の設定で防げることが多いので、インポート時の列の書式設定を確認してください。

だからといってフラット化が間違いというわけではありません。フラット化は片道切符だということです。元のJSONは正本として残してください。コピーをフラット化し、コピーで作業し、元になった木を捨てないことです。正本さえ残っていれば、いつでもやり直せます。作業用のコピーは消耗品と割り切るのが、データ作業の基本的な心構えです。

フラット化すべきか？60秒の判断

決めるのはデータではなく、行き先です。行き先がスプレッドシート、CSVインポート、行を眺める人間なら、フラット化してください。それらの道具はそうしたデータのために作られています。フラット化したファイルはどこで開いてもきれいに表示されます。フラット化は道具の都合に合わせる作業です。自分の好みではなく、受け手の道具が何を期待しているかで決めてください。

行き先が別のプログラム、API、後でJSONに戻す往復なら、フラット化しないでください。ネストを残してください。上で挙げたフラット化の損失は、戻るときにほぐさなければならないバグになります。この往復のケースでは、フラット化の損失がそのままデータの欠損として戻ってきます。特に型の崩れとリストの結合は、復元が困難です。

迷ったら、コピーをフラット化して目で見てください。CSVを開き、ドット記法の列が意味をなしているか、結合されたリストが正しいか、重要なものが読めない塊になっていないかを確認します。60秒の目視は、壊れたインポートの1時間のデバッグに勝ります。この60秒の確認を習慣にすると、変換の失敗のほとんどを防げます。慣れてくると、どこを見ればいいかが自然に分かるようになります。

スプレッドシート、CSVインポート、人の目での確認：フラット化してください。それがそれらの道具の期待する形です。この3つの用途では、フラット化しない理由はほぼありません。変換後のCSVは、そのままExcelで開けます。
API、データベース、JSONへの往復：ネストを残してください。フラット化の損失はバグになります。戻す予定があるなら、最初からネストを保つのが安全です。
迷うとき：コピーをフラット化して開き、確定する前に列を確認してください。この目視確認が、トラブルの早期発見になります。

このページで試してみる

このページ上部のコンバーターは、デフォルトでフラット化します。ネストしたJSONを貼り付けてプレビューを見てください。ネストしたオブジェクトがドット記法の列になり、リストが「; 」で結合され、すべてのセルに値が1つだけ入ります。フラット化をオフにして同じJSONを貼り付けると、この言葉が何を意味するのかが分かります。セル内のネストした塊と、きれいなフラットな表の違いです。自分のデータでのこの見比べが、この用語を定着させる最速の方法です。この体験は、文章で読むよりずっと記憶に残ります。自分のデータで試すことで、フラット化のルールが実感として理解できます。この見比べこそが、ミニファイとの混同を解いた章で説明した違いを、目で確かめる一番の近道です。

JSONに、行として欲しいオブジェクトのリストが含まれている場合、フラット化だけでは足りません。それはエクスプロードという別の操作です。エクスプロードすべき場面の正確な判断は、『how to flatten the JSON data：ネストを展開・結合・そのまま残す判断ガイド（2026年）』で解説しています。エクスプロードは、フラット化とは独立した操作です。両者を組み合わせることもできますが、まずはそれぞれの意味を掴むことが大切です。

よくある質問

JSONをフラット化するとは、簡単に言うとどういう意味ですか？

ネストしたJSONを、何もネストしていない形に書き直すことです。オブジェクトの中のオブジェクトはcustomer.cityのようなドット記法の名前になり、短いリストは1つの結合されたセルになり、すべての値はトップレベルに、1セル1つの値で収まります。結果はフラットな表です。CSVファイルとスプレッドシートが必要とするのは、まさにこの形です。この書き直しは、値の内容を変えません。変わるのは値の置き場所と名前だけです。木の形を、表の形に移し替える作業とイメージしてください。

JSONのフラット化とミニファイは同じことですか？

いいえ。これが最も多い混同です。ミニファイは空白を消すだけで、1行の長いテキストになりますが、ネストは完全に残っています。フラット化は構造そのものを変え、ネストした値をトップレベルに引き上げます。ミニファイされたファイルはパースするとまったく同じ木になります。フラット化されたファイルは、別の、浅い形状になります。両者は似た言葉ですが、扱うものが違います。ミニファイが相手にするのは空白文字、フラット化が相手にするのはデータ構造です。

JSONファイルをフラット化すると、データは変わってしまいますか？

変わるのは形状であって、値ではありません。すべての末端の値は生き延びます。ただしネストはドット記法の列になり、リストは結合されたテキストになり、型はテキストに崩れ、nullは空のセルになります。元のJSONは正本として残し、フラット化したファイルは作業用コピーとして扱ってください。この「形状は変わるが値は変わらない」という点が、フラット化の本質です。値の正しさを疑う必要はありません。確認すべきは、形状の変化が自分の用途に合っているかです。たとえば住所のネストがドット記法の3列になっても、住所の内容そのものは一字も変わっていません。変わるのは置き場所の名前だけです。

フラット化とエクスプロードの違いは何ですか？

フラット化は1レコード1行を保ち、列を横に広げます。ネストしたパスが新しい列になります。エクスプロードは列を保ち、行を増やします。リストの各要素が自分の行を持ち、レコードの残りは繰り返されます。3つのタグを持つ顧客をフラット化すると、「tag1; tag2; tag3」というセルを持つ1行になります。エクスプロードすると3行になります。どちらを選ぶべきかは、『how to flatten the JSON data：ネストを展開・結合・そのまま残す判断ガイド（2026年）』で解説しています。この違いは、行と列のどちらを増やすかという選択です。フラット化は横に広げ、エクスプロードは縦に伸ばします。目的の表の形から逆算して選ぶと迷いません。タグの例で言えば、フラット化は「1行3タグを1セルに」、エクスプロードは「3タグを3行に」します。向きがまったく逆なのです。

CSVファイルがフラットなデータを必要とするのはなぜですか？

CSVには行と列とテキストしかないからです。ネストを置く場所がありません。セルはオブジェクトを保持できず、文字しか保持できないのです。だからネストした構造は、CSVに入る前にフラット化するか（あるいはセル内にJSONテキストとして詰めるか）しなければなりません。この制約は、CSVという形式の設計そのものです。シンプルさと引き換えに、表現できる形状が限られています。その代わり、どんな道具でも開けるという強みがあります。

CSVをネストしたJSONに戻せますか？

おおよその戻しだけです。customer.cityのようなドット記法の列はスクリプトでネストしたオブジェクトにまとめ直せますし、そういう道具もあります。でもフラット化で失われた情報は戻りません。結合されたリストは配列に確実には戻せず、型は推測になり、nullと未定義の区別は分からなくなります。ネストが必要なら、元のJSONを残してください。戻す処理は、失われた情報を推測で補う作業になります。推測は道具によって異なるため、同じCSVからでも戻したJSONの形が変わることがあります。確実に元に戻したいなら、元のJSONを保管してください。結合されたセルを分割し直すスクリプトも書けますが、セパレーターが元の値に含まれていたら復元は不可能です。ここでも正本の保存が効いてきます。

このページのJSONからCSVへのコンバーターは自動でフラット化しますか？

はい。フラット化はデフォルトでオンです。ネストしたJSONを貼り付けると、プレビューにすぐドット記法の列が表示されます。オフにもできます。その場合、ネストしたオブジェクトと配列は単一のセル内のJSONテキストとして残ります。表計算作業なら、オンのままがおすすめです。このデフォルト設定は、表計算作業を想定した選択です。ほとんどの利用者はフラットな表を期待しているため、最初からオンになっています。

フラット化の様子をその場で確認

入れ子のJSONをコンバーターに貼り付けて、フラット化でドット記法の列に変わる様子を確認しましょう。無料、登録不要、すべてブラウザ内で動作します。

JSON CSV コンバーターを開く

ガイド一覧