JSON Flatten / Unflatten — dot-notation キーで平坦化・復元

JSON の構造変換が扱うデータの機微性

JSON の flatten・unflatten 操作が行われる典型的なシーンは、API レスポンスの変換・設定ファイルの環境変数化・i18n 翻訳データの整形・データベーススキーマの前処理です。これらのデータには顧客情報・API キー・データベース接続文字列・内部サービスのエンドポイントが含まれていることが多くあります。

特に flatten 操作はデータ構造の設計を露わにします。\{"user.billing.card.last4": "1234"} のようなフラットキーはデータモデルの内部構造をそのまま示しており、DB の設計・フィールド名・ネスト構造が外部のサービスに伝わることになります。スキーマ情報が漏洩することは、システム設計書の一部を共有するのと同義です。

オンラインの JSON ツールにネストした設定を送るリスク

設定ファイルの JSON (特に CI/CD パイプラインの環境設定、マイクロサービスのサービス設定、クラウドリソースの定義ファイル) には秘密情報が含まれていることがあります。これらを flatten・unflatten するためにオンラインツールに貼り付けると、その内容がサーバーに送信されます。

見た目に複雑なネスト JSON ほど、一度に多くの情報を含んでいます。JSON を展開してキーを確認してから「これは外部に出してはいけない」と気づく、という順序になりやすいのが、オンラインツールを使う場合の構造的な問題です。ローカルで処理するツールは、確認前に情報が外部に出るリスクを根本的に排除します。

JSON.parse と再帰アルゴリズムだけでブラウザ内完結

このツールの flatten・unflatten 処理は JSON.parse で入力をパースし、再帰的にオブジェクトツリーを走査してキーを結合・分解するだけです。外部ライブラリへの依存なしに実装されており、Dot (.)・Slash (/)・Bracket (["key"]) の 3 種類の区切り文字と、bracket/index 2 種類の配列記法をすべてブラウザ内で処理します。型 (number / string / boolean / null) はリーフ値として JSON.parse の結果をそのまま保持し、unflatten 時に配列インデックスを数値として認識して正しく再構築します。

入力した JSON はページメモリ内にのみ存在し、処理の間もネットワーク送信は一切発生しません。機密を含む設定ファイルや API レスポンスの変換処理をブラウザのタブ内で完結させることができます。

実務での安全な変換ワークフロー

i18n 翻訳データを Crowdin・Lokalise へインポートする前の flatten 変換、MongoDB の $set クエリ生成のための \{"user.address.city": "Tokyo"} 形式への変換、CSV エクスポート前のネスト解除など、データパイプラインの前処理として JSON 構造変換が必要な場面は多いです。このツールではその全工程をブラウザ内で完結させることができるため、処理対象のデータが顧客情報を含んでいても、外部への送信なしに変換・確認・コピーの一連の作業を実施できます。flatten した結果を整形して読みたい場合は json-format、特定パスだけ抽出したい場合は json-path-query も同様にローカルで動作します。

再帰アルゴリズムとキー衝突 / 区切り文字エスケープの罠

flatten の実装は深さ優先の再帰関数で、現在のキーパス (例: user.address) を引数として渡しながら子要素を辿ります。リーフ値 (number / string / boolean / null) に到達したらキーパスとペアで結果オブジェクトに登録します。配列は要素ごとに [0] / [1] 形式でキーパスを伸ばします。unflatten はその逆で、キーパスを区切り文字で分割し、数値セグメントは配列インデックス、文字列セグメントはオブジェクトキーとして再構築します。

最も踏みやすい罠はキー名に区切り文字が含まれるケースです。{"foo.bar": "value"} のように元キーに . が含まれていると、flatten 後に foo.bar だけ見て unflatten すると { foo: { bar: "value" } } になってしまい元構造を失います。標準的な対策はキー名のエスケープ (foo\.bar) ですが、実装によっては未サポートのことがあります。本ツールでこの問題に遭遇したら、区切り文字をデフォルトの . から / や bracket notation に切り替えることでキー衝突を避けられます。

MongoDB / Elasticsearch / Algolia / Crowdin での実用上の差

MongoDB の $set クエリは flatten 形式 ({ "user.address.city": "Tokyo" }) を直接受け付け、ネストフィールドへのピンポイント更新に使われます。配列要素は $ 演算子 ("posts.$.title": ...) で扱うため、本ツールの [0] / .0 形式とは別系統です。Elasticsearch の flatten field type (7.3+) は機械的にネストを潰しますが、検索クエリ側は field.subfield.subsubfield のドット記法でアクセスする必要があります。

i18n の Crowdin / Lokalise は階層キー (messages.button.submit) と flat キー (messages_button_submit) のどちらでもインポートできるサービスが多いですが、エクスポート時の形式は設定により異なります。Algolia は最大ネスト深さがプランで制限されるため、深いネストを flatten してから送信する用途で使われます。本ツールが 2 種類の配列記法と 3 種類の区切り文字をサポートするのは、これら下流サービスごとに期待する形式が違うためで、変換後の形式を目視で確認してから配布する運用が現実的です。