キー名とパスを分ける
キーが draft/a~b で、その値が state を含む別のオブジェクトである JSON オブジェクトを考えます。ここでのスラッシュはキーの一部であり、新しい階層を作りません。これに対し JSON Pointer は、スラッシュで区切った参照トークンをたどって値を特定します。たとえば /orders/0/item は配列内の要素を指し、0 は配列の添字です。キー名をエスケープせずにそのままポインターへコピーすると、別の位置を参照したり、参照に失敗したりします。
RFC 6901 は各トークン内の二つのエスケープを定めます。チルダは ~0、スラッシュは ~1 になります。空でないポインターは各経路部分の前にスラッシュを付けますが、空のポインターは文書全体を指します。この記法が表すのは経路に含まれる文字であり、参照先の値の内容ではありません。JSON オブジェクト自体も変更しません。データや利用者から渡されたプロパティ名を使って経路を組み立てるときは、トークン用のツールでその名前を個別にエスケープしてください。
区間ごとにパスを組み立てる
キー draft/a~b では、まずチルダを ~0 に、次にスラッシュを ~1 に置き換えます。エスケープされたトークンは draft~1a~0b です。先頭にスラッシュを付け、別のメンバー state を続けると /draft~1a~0b/state になります。下の埋め込み変換器が行うのはトークンの変換で、先頭のスラッシュは付けません。長い JSON Pointer のどの位置にもそのトークンを置けるためです。図の三段階と出力を比べてください。
逆方向のトークンツールでは、先に ~1 をスラッシュに戻し、その後で ~0 をチルダに戻します。この順序は重要です。~01 をまず ~1 に戻し、続けてそれをスラッシュに変えてしまうと、元のプロパティ名が変わります。JSON Pointer のトークンと URL のパーセント符号化は別物です。ポインターを URL フラグメントに入れる場合は、その外側の URI にも追加の符号化規則があります。リンクや API リクエストを調べる際は、二つの層を分けて確認してください。
- 元のキー：draft/a~b
- エスケープ後：draft~1a~0b
- 完全なパス：/draft~1a~0b/state
平坦化ツールが作るもの
平坦化ツールは JSON オブジェクトをたどり、葉の値を完全な JSON Pointer のようなキーの下に書き出します。たとえば draft/a~b の下に state というメンバーがあるオブジェクトでは、同じ葉の値を持つ平坦な項目のキーは /draft~1a~0b/state です。ネストしたデータを比較、一覧表示、書き出しする際に役立ちます。逆方向のツールはこれらのパスのキーを読んで階層を再構築しますが、パス同士が衝突したり矛盾したりしないことが条件です。平坦化された項目も JSON オブジェクトのメンバーであり、自動的な検索操作そのものではありません。
このツールでは配列を末端の値として扱い、要素ごとに /0 や /1 のキーを作りません。空のオブジェクトも末端の値です。一般の JSON Pointer は配列の添字を指せますが、このツールが作るフラットな一覧にはその添字が列挙されません。一方の経路が /a に単一の値を割り当て、別の経路が /a/b に値を割り当てようとする場合、逆方向の変換は衝突として拒否しなければなりません。経路のキーを手作業で変更するときは、元の JSON を保存してください。
パス形式のデータを安全に扱う
まず有効な JSON を用意し、一つの値への住所が必要なのか、末端の値を一覧にしたいのかを決めます。一つの住所なら、経路を実際のプロパティ名ごとに分け、それぞれを個別にエスケープして、先頭にスラッシュを付けて連結します。ポインター全体を一括でエスケープすると、区切りのスラッシュまで名前の一部になってしまいます。多数の末端値を調べるならオブジェクトをフラット化し、生成されたキーを別のシステムへ渡す前に確認してください。
データを復元する際は、すべてのフラットなキーがスラッシュで始まり、~ のエスケープが有効か確認してください。同じ場所への重複代入、親子で衝突するキー、配列を末端値として扱う規則、名前にドットやスラッシュを含むキーに注意が必要です。両方の記号を含む小さなオブジェクトで往復変換を試し、字下げではなく解析後の JSON 構造を比較します。ポインターの構文は標準で定義されますが、フラット化の方針はこのツール固有なので、業務の手順へ組み込む前に確かめてください。