フラット化を尊重することを教えてくれたタスクは、チケットでは退屈に見えました: " 設定オブジェクトをスプレッドシートにエクスポートして、クライアントが編集できるようにします。 " 設定は、Laravelコンフィグから深くネストされたJSONブロブで、場所には3 つと4 つのレベルがあり、機能フラグの配列が混在していました スプレッドシートには木ではなく列があります クライアントが1 行で見ることができる単一のフラットキーとしてすべてのリーフ値が必要で、編集してハンドバックし、その後、単一の配列インデックスを失うことなく、それらの編集から正確にネストされた構造を再構築する必要がありました その往復、フラットにネストされ、フラットバックにネストされた、それがJSONフラットナーが行うことであり、ロスレスにすることはゲーム全体です ツールツ JSON フラットナー この仕事のために私が構築したツールです。このガイドでは、そのツールがどのように機能し、どこに節約されるかを説明します。
tl;dr: JSON フラットナーは、ネストされたオブジェクトを、各値へのパスをキーとする単一レベルのオブジェクトに変換します
{"user":{"city":"Austin"}}なる{"user.city":"Austin"}。 () のパス内のインデックスでフラット化された配列roles.0). unflatten はそれを反転し、それらの点線のキーからネストされたオブジェクトと配列を再構築します。 Toolz ツールは両方向をロスレスで実行し、空のオブジェクトと配列を保存し、ドットまたはブラケット配列の表記とカスタム区切り文字をサポートし、アップロードとサインアップなしで完全にクライアント側で実行されます。
私はLaravelとReactでSaaSを構築し、WordPressプラグインを出荷しているので、ネストされたJSONは私の日のどこにでもあります: configファイル、APIペイロード、i18nメッセージカタログ、機能フラグストア、しかしそれらのペイロードを消費するシステムは、頻繁にフラットキーを欲しがります フラット化とは、構造化データにとって自然な形状と、スプレッドシート、環境変数、点線のキーストアにとって自然な形状の間のアダプターであり、それ以外の迷惑なタスクの多くを静かにブロック解除する小さな操作です。
JSONフラットナーとは何ですか?
JSON フラットナーは、ネストされた JSON オブジェクトを、各キーがルートからリーフ値へのフルパスである単一レベルのオブジェクトに変換します。 path 構文も任意ではありません: RFC 6901 ドキュメント内の1 つの値をアドレス指定する標準的な方法であるJSON Pointerを定義します。 nested {"user":{"name":"Ada","address":{"city":"Austin"}}} がフラットになります {"user.name":"Ada","user.address.city":"Austin"}.nothing about the values changes; only their addressing does.どんなに深くても、どの葉にも、到達方法を綴った鍵が1つ付く。
配列も同様に扱われ、配列インデックスはパスセグメントになります: {"roles":["admin","editor"]} に平坦化します {"roles.0":"admin","roles.1":"editor"}。 key のインデックスは、逆演算が配列を正しい順序で再構築できるようにするものです。 unflatten という逆演算は、点付きキーの平坦なオブジェクトを取得し、ネストされたオブジェクトと配列を再構築し、各ステップでパス セグメントがオブジェクト プロパティに名前を付けるか配列インデックスに名前を付けるかを決定します。 flatten と unflatten が同じ区切り文字と配列表記を使用する場合、それらは正確な逆数であり、ロスレス ラウンド トリップは、ツールが一方向の利便性ではなく実際の作業に対して信頼できるものになるプロパティです。
そもそもなぜJSONをフラット化してしまうのでしょうか?
なぜなら多くのシステムはフラットなキーと値のペアしか話さず 点線パスはネストされた構造を 失うことなくそれらを通して運ぶ標準的な方法です 最も明確な例はスプレッドシートです スプレッドシートは列のグリッドで " の列はありません " ユーザー内のアドレス内の都市 " オブジェクトをフラット化し user.address.city 値が 1 列のヘッダーになることで、その値を維持できるようになります。これはまさに私の設定エクスポート チケットに必要なものです。
同じ形が他の多くの場所に現れます 環境変数と .env ファイルはフラットで、それにコンフィグをマッピングするツールは、点線またはアンダースコア付きのパスを使用します。 internationalization ライブラリは、次のように点線付きのパスで文字列をキーします checkout.button.label。 feature-flag プラットフォーム、分析イベントスキーマ、および多くのロギングパイプラインはすべて、多くの場合、各フィールドに独立してインデックス付けまたはクエリを実行できるように、1 レベルのキーを必要とします。いずれの場合も、ネスティングは現実的で意味があり、フラット化すると、それを破棄するのではなく、パス内に保存されます。フラット表現がその目的を果たした場合、フラット化を解除すると、元のオブジェクトが再構築されます。 JSON とスプレッドシートの間も具体的に移動する場合は、 CSVからJSONへのコンバーター は、その旅行の表形式の区間の自然な相棒です。
平坦化するときの配列の扱いは?
配列は、人が最も頻繁に間違う部分であるため、正確である価値があります。 配列要素は、その数値インデックスをパス セグメントとして使用してフラット化され、順序が維持され、配列を正確に再構築できます。 Toolz ツールは、そのインデックスに対して 2 つの表記法を提供し、同じ情報を異なる構文でエンコードします。
| 入力 | ドット表記 | ブラケットの表記法 |
|---|---|---|
{"roles":["admin","editor"]} |
roles.0、 roles.1 |
roles[0]、 roles[1] |
{"items":[{"id":1}]} |
items.0.id |
items[0].id |
{"matrix":[[1,2]]} |
matrix.0.0 |
matrix[0][0] |
ドット表記が書き込みます roles.0、コンパクトで、configとi18nシステムが値をキーする数と一致します。 bracket notationは書き込みます roles[0]、これは、javascriptのアクセス構文と一部のクエリ言語が使用するパススタイルを反映します。どちらもより正確ではありません; あなたは、もう一方の端にシステムが期待するものを選択します。重要なことは一貫性です: あなたがフラット化する表記法は何でも、フラット化を解除するために同じものを使用します。なぜなら、それはツールが数値セグメントを知っている方法だからです。 "array index"ではなく、"たまたま数字であるオブジェクトキーを意味します。" Toolz フラットナーはデフォルトでドット表記になり、ワンクリックでブラケットに切り替えることができます。
JSONフラットナーはどのように使用すればよいですか?
フローには2 つの方向と2 つのオプションがあります。 toggleを上部に配置してflattenまたはunflattenを選択することから始めます。 flattenはネストされたJSONを取り、点線のキーを生成します; unflattenは点線のキーを取り、ネストされた構造を再構築します。 load Sampleは、どの方向にあるか作業例で塗りつぶしますので、独自のデータを貼り付ける前に、入力と出力の両方の形状を確認できます。
JSON を入力ボックスに貼り付けます。 flatten の場合、それはネストされたオブジェクトです; unflatten の場合、キーが点線パスであるフラット オブジェクトです。入力は有効な JSON でなければならず、そうでない場合、ツールは空白の出力を渡す代わりに parser' s メッセージと問題の位置を報告するため、迷走した末尾のカンマはすぐに見つけられます。キーのスタイルを設定します。区切り文字はデフォルトでドットになり、キーにすでにドットが含まれている場合に変更でき、配列の表記切り替えが切り替わります roles.0 あんど roles[0].これら2 つの設定をフラットに横切って同一に保ち、その一致するフラット化を解除して往復が並ぶようにします。 「アクション」ボタンをクリックし、葉が何枚出たかを確認するキーカウントを確認し、出力をコピーするか、aとしてダウンロードします .json ファイル。全体は、ブラウザでクリックした瞬間に実行され、どこにも送信されません。
平坦化はロスレスですか?エッジケースは何ですか?
Toolzツールの場合、はい、知る価値のあるエッジケースが1 つあります スカラー、 null、ブール値、数値は手付かずで生き残る。 微妙な部分は空のコンテナ: 空のオブジェクトである {} または空の配列 [] は無言で落とすのではなく葉値として保存されるので、空のリストに依存するコンフィグは、それが何であったかを正確に往復します。多くの素朴なフラットナーは空のコンテナを失い、それが文書の意味を静かに変えるため、これは意図的な選択です。
1 つの本物の制限は、区切り文字をすでに含むキーです。 データにリテラル ドットを含むオブジェクト キーがある場合 {"a.b":1}、そしてドット区切り文字でフラット化すると、パスは曖昧になります: フラットされていないかどうかを見分けることができません a.b 鍵が 1 つか、入れ子になっていました a そしたら b.修正点は、区切り文字をキーに表示されない文字に変更することです (スラッシュやパイプなど) 、 その同じ区切り文字を両方向に使用します (2 つの方向で、同じ方向で表示されるエスケープ問題と同じクラスです) CSV 区切り文字がデータと衝突します、同じソリューションが適用されます: 値に含まれていない区切り文字を選択します。そのケースの外では、フラット化に続いて、一致する設定でフラット化されていないと、元のドキュメントが正確に再現され、配列と空のコンテナが含まれています。
フラット化と別の形式への変換の違いは何ですか?
フラット化はフォーマット変換ではありません; JSON 内での再構築です フラット化の出力は、ネストではなく 1 レベルの点線キーを使用するだけで、依然として JSON です。これは、JSON を真に異なるシリアル化に変えるコンバーターとは異なり、どれが必要かを知っていればステップが節約されます。
構成ファイルの YAML と同じデータを表現したい場合は、 JSON から YAML へのコンバータ はツールなので、形状ではなく構文を変更します。 typeScript インターフェイスが構造を説明して、フロントエンドが何を処理しているかを理解できるようにしたい場合は、 JSON から TypeScript コンバータ サンプルからそれを推測します。検証のための正式な契約が必要な場合は、 JSON スキーマジェネレータ 例から JSON スキーマを導出する フラット化は、これらを置き換えるのではなく、これらの横に置かれます: ダウンストリーム システムが 1 レベルのキーを必要とするときにフラット化し、システムが別の言語を必要とするときに変換するペイロードをフラット化して列として編集し、その後、個別に、React に渡すネストされたバージョンの型を生成する、両方を順番に頻繁に実行します。 pretty-printing またはそのチェーンの任意の時点で JSON を検証するには、 JSON フォーマッタ 次のタブで開いたままにするユーティリティです。
フラット解除は配列とオブジェクトをどのように決定しますか?
これは往復を機能させるメカニズムであり、それを理解することで、ツール& #39; のデフォルトとその 1 つの鋭いエッジの両方が説明されます。 unflatten は次のようなキーを読み取ります user.roles.0、セグメントに分割します user、 roles、そして 0、そして、それが行くようにそれらを建物の構造歩く 各ステップで、それは作成する容器の種類を決定するために次のセグメントを見ます 次のセグメントが非負の整数であれば、配列; それが何か他のものであるならば、それはオブジェクトを作るので roles.0 ツールにそれを伝えます roles は、最初の要素が値である配列である必要があります address.city と伝えている address を持つオブジェクトである必要があります city 財産.
その単一の規則、 " integer segment は配列インデックス、 " を意味し、これが、設定が一致する flatten と unflatten が配列を正確に再現する理由です。 dot 表記では配列インデックスとオブジェクト キーは両方ともドット間のテキストにすぎないため、ツールは完全に整数テストに依存します。 bracket 表記では、 [0] 構文は分割が起こる前に意図を明示します。どちらも機能しますが、それらを混合し、括弧で平坦化し、点で平坦化を解除すると、ツールが依存する信号が破壊されます。
これはルールから続く鋭いエッジです。つまり、キーが真に文字列であるオブジェクトです "0"、 "1"、 "2" は配列と一旦平らにすると区別できない。 どちらもキーを生成する 0、 1、 2、そして unflatten は、それが圧倒的に一般的なケースであるため、配列としてそれらを再構築します。 往復を生き残るために数値文字列キーを持つオブジェクトが本当に必要な場合、それはフラット化とフラット化解除が正確な型を返さない唯一の状況であり、そのオブジェクトをネストしたままにするか、非数値キースキームを使用する方が良いでしょう。これを何年も続けて、私はそのケースを正確に 2 回ヒットしました。どちらも、おそらく最初からモデル化が間違っていたデータでは、デフォルトは、ほとんどすべての人にとって正しい取引です。 の文字列として先頭にゼロを持つ数値を保持することの背後にある同じ種類の実用的な決定です CSVからJSONへのコンバーター:このツールは、ほとんどの場合、データが意味するものに合わせて最適化し、一般的なパスを扱いにくくするのではなく、まれな例外を文書化します。
私のJSONはこのツールに貼り付けるのが安全ですか?
はい、そしてそれは約束ではなく建築的です 解析、フラット化、フラット化解除、シリアル化はすべて、独自のブラウザタブ内でJavaScriptとして実行されます アップロードもサーバー往復もなく、ログも保存も何もありません browser' s ネットワークタブを開き、アクションボタンをクリックします: リクエストは消えません ページがロードされると、インターネットから切断することができ、それは動作し続けます, 最初からループ内にサーバーが存在しなかったため。
これは思われるよりも重要です、なぜならJSONペイロードはまさに秘密を運ぶ種類のものだからです: コンフィグ内のAPIトークン、APIレスポンス内の個人データ、設定ブロブ内の内部識別子など、オブジェクトをサーバーにアップロードしたフラットナーはプライベートペイロードを他の誰かに変えるでしょう& #39; s ログライン クライアントサイド処理はリスクを完全に除去するので、それが Toolz.dev 上のすべてのツールにわたるデフォルトの完全な推論が必要な場合は、 にレイアウトしました オンラインツール向けデータプライバシーガイド、そしてこの種の仕事に使用するより広いキットは私のものです Web 開発者ツールキット ガイド。
よくある質問
JSONをフラット化するとはどういう意味ですか?
JSONをフラット化すると、ネストされたオブジェクトを、キーが各値へのパスである単一レベルのオブジェクトに変換します。 nested {"user":{"city":"Austin"}} がフラットになります {"user.city":"Austin"}. leaf の値ごとに 1 つの点線のキーが得られ、出力にはネストが残らない。 unflatten はプロセスを反転させ、ネストされた構造を再構築する。
平坦化するときの配列の扱いは?
配列要素は、インデックスをパス セグメントとして使用してフラット化されます。 {"roles":["admin","editor"]} なる {"roles.0":"admin","roles.1":"editor"} ドット表記では、または {"roles[0]":"admin","roles[1]":"editor"} ブラケット表記で。 index は順序を保持するため、フラット化を解除したときに配列を正確に再構築できます。
点線のキーをフラット化解除してネストされた JSON に戻すことはできますか? はい。 unflatten モードに切り替えて、キーが点線パスであるフラット オブジェクトを貼り付けます。ツールは、ネストされたオブジェクトと配列を再構築し、各パス セグメントが整数インデックスであるかどうかによって配列とオブジェクトを決定します。 flatten と unflatten は、区切り文字と配列の表記が一致すると、正確に逆になります。
ドット配列表記とブラケット配列表記の違いは何ですか?
どちらも同じ配列インデックスをエンコードします; 構文だけが異なります。 dot 表記は書き込みます items.0.id、コンパクトでconfigやi18nキーで一般的な。 bracket notationは書き込みを行う items[0].id、javascriptのアクセス構文と一部のクエリ言語に一致するもの ターゲットシステムが期待するものを選択し、両方向に同じものを使用します。
フラット化するとデータが失われますか? いいえ スカラー、ヌル、ブール値、さらには空のオブジェクトや空の配列までもがリーフ値として保持されるため、結果をフラット化しないと元のドキュメントが再現されます。注目すべき点の 1 つは、区切り文字がすでに含まれているキーです。そのため、区切り文字は構成可能です。
なぜJSONをフラット化してしまうのでしょうか? フラット化では、1 レベルのキー (スプレッドシートの列、環境変数、点線の翻訳キー、機能フラグのストア、および多くの分析およびログ パイプライン) を期待するシステムにネストされたデータを適応させます。点線のパスはフラット形式を通じて元の構造を伝送するため、何も失われません。
キーにすでにドットが含まれている場合はどうなりますか? キー内のリテラル ドットはパス区切り文字とあいまいなため、往復で間違った場所に分割される可能性があります。区切り文字をキーに表示されないスラッシュやパイプなどの文字に変更し、フラット化およびフラット化解除の両方にその同じ区切り文字を使用します。
私の JSON はどこかにアップロードされていますか? いいえ ブラウザでJavaScriptとして実行される解析と変換 何も送信、ログ、保存されません フラット化中にネットワークタブを見ること、またはツールが接続なしで動作し続けるため、オフラインにすることでこれを確認できます。
