4. 操作
操作オブジェクト (Operation Object) は, 実行する操作を示す値を持つ "op" メンバーを正確に 1 つ持たなければなりません。その値は "add", "remove", "replace", "move", "copy", または "test" のいずれかでなければなりません; 他の値はエラーです。各オブジェクトのセマンティクスは以下に定義されています。
さらに, 操作オブジェクトは正確に 1 つの "path" メンバーを持たなければなりません。そのメンバーの値は, 操作が実行されるターゲット文書 (Target Document) 内の場所 ("ターゲット位置", Target Location) を参照する JSON-Pointer 値 [RFC6901] を含む文字列です。
他の操作オブジェクトメンバーの意味は操作によって定義されます (以下のサブセクションを参照)。問題の操作に対して明示的に定義されていないメンバーは無視されなければなりません (つまり, 未定義のメンバーがオブジェクトに現れなかったかのように操作が完了します)。
JSON オブジェクト内のメンバーの順序は重要ではないことに注意してください; したがって, 以下の操作オブジェクトは等価です:
{ "op": "add", "path": "/a/b/c", "value": "foo" }
{ "path": "/a/b/c", "op": "add", "value": "foo" }
{ "value": "foo", "path": "/a/b/c", "op": "add" }
操作は JSON 文書によって表されるデータ構造に適用されます, つまり, あらゆるアンエスケープ ([RFC4627], セクション 2.5 を参照) が行われた後です。
4.1. add
"add" 操作は, ターゲット位置が参照する内容に応じて, 以下の機能のいずれかを実行します:
-
ターゲット位置が配列インデックスを指定する場合, 指定されたインデックスで配列に新しい値が挿入されます。
-
ターゲット位置がまだ存在しないオブジェクトメンバーを指定する場合, オブジェクトに新しいメンバーが追加されます。
-
ターゲット位置が存在するオブジェクトメンバーを指定する場合, そのメンバーの値が置き換えられます。
操作オブジェクトは, 追加する値を指定する内容を持つ "value" メンバーを含まなければなりません。
例えば:
{ "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }
操作が適用される場合, ターゲット位置は以下のいずれかを参照しなければなりません:
-
ターゲット文書のルート - この場合, 指定された値がターゲット文書の全内容になります。
-
既存のオブジェクトに追加するメンバー - この場合, 提供された値が指定された場所でそのオブジェクトに追加されます。メンバーが既に存在する場合は, 指定された値で置き換えられます。
-
既存の配列に追加する要素 - この場合, 提供された値が指定された場所で配列に追加されます。指定されたインデックス以上の要素はすべて右に 1 つずつシフトされます。指定されたインデックスは配列内の要素数より大きくてはなりません。配列の末尾をインデックスするために
"-"文字が使用される場合 ([RFC6901] を参照), これは配列に値を追加する効果があります。
この操作は既存のオブジェクトと配列に追加するように設計されているため, そのターゲット位置は存在しないことがよくあります。したがってポインタのエラー処理アルゴリズムが呼び出されますが, この仕様では "add" ポインタのエラー処理動作をそのエラーを無視し, 指定どおりに値を追加するように定義しています。
ただし, オブジェクト自体またはそれを含む配列は存在する必要があり, そうでない場合はエラーのままです。たとえば, 次の文書から始めて, ターゲット位置が "/a/b" の "add":
{ "a": { "foo": 1 } }
はエラーではありません, なぜなら "a" が存在し, "b" がその値に追加されるからです。次の文書ではエラーです:
{ "q": { "bar": 2 } }
なぜなら "a" が存在しないからです。
4.2. remove
"remove" 操作はターゲット位置の値を削除します。
操作が成功するには, ターゲット位置が存在しなければなりません (MUST)。
例えば:
{ "op": "remove", "path": "/a/b/c" }
配列から要素を削除する場合, 指定されたインデックスより上の要素は左に1つずつシフトされます。
4.3. replace
"replace" 操作はターゲット位置の値を新しい値に置き換えます。操作オブジェクトは, 置換値を指定する内容を持つ "value" メンバーを含まなければなりません (MUST)。
操作が成功するには, ターゲット位置が存在しなければなりません (MUST)。
例えば:
{ "op": "replace", "path": "/a/b/c", "value": 42 }
この操作は機能的には, 値に対する "remove" 操作に続いて, 同じ場所で置換値を使用した "add" 操作を実行することと同じです。
4.4. move
"move" 操作は指定された場所の値を削除し, ターゲット位置に追加します。
操作オブジェクトは, 値を移動する元のターゲットドキュメント内の場所を参照する JSON Pointer 値を含む文字列である "from" メンバーを含まなければなりません (MUST)。
"from" 位置は操作が成功するために存在しなければなりません (MUST)。
例えば:
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" }
この操作は機能的には, "from" 場所に対する "remove" 操作に続いて, 削除されたばかりの値を使用してターゲット位置で "add" 操作を実行することと同じです。
"from" 位置は "path" 位置の真の接頭辞であってはなりません (MUST NOT); つまり, 場所をその子の1つに移動することはできません。
4.5. copy
"copy" 操作は指定された場所の値をターゲット位置にコピーします。
操作オブジェクトは "from" メンバーを含まなければなりません, これは値をコピーするターゲット文書内の場所を参照する JSON Pointer 値を含む文字列です。
操作が成功するには, "from" 位置が存在しなければなりません。
例えば:
{ "op": "copy", "from": "/a/b/c", "path": "/a/b/e" }
この操作は, "from" メンバーで指定された値を使用してターゲット位置で "add" 操作を実行することと機能的に同一です。
4.6. test
"test" 操作はターゲット位置の値が指定された値と等しいかどうかをテストします。
操作オブジェクトは, ターゲット位置の値と比較する値を伝える "value" メンバーを含まなければなりません。
操作が成功したと見なされるには, ターゲット位置が "value" 値と等しくなければなりません。
ここで "等しい" とは, ターゲット位置の値と "value" によって伝えられる値が同じ JSON 型であり, その型に対する以下の規則によって等しいと見なされることを意味します:
-
文字列: 同じ数の Unicode 文字を含み, それらのコードポイントがバイト単位で等しい場合, 等しいと見なされます。
-
数値: それらの値が数値的に等しい場合, 等しいと見なされます。
-
配列: 同じ数の値を含み, この型固有の規則のリストを使用して, 各値が他の配列の対応する位置の値と等しいと見なされる場合, 等しいと見なされます。
-
オブジェクト: 同じ数のメンバーを含み, キー (文字列として) と値 (この型固有の規則のリストを使用) を比較することにより, 各メンバーが他のオブジェクトのメンバーと等しいと見なされる場合, 等しいと見なされます。
-
リテラル (false, true, および null): それらが同じ場合, 等しいと見なされます。
実行される比較は論理的な比較であることに注意してください; たとえば, 配列のメンバー値間の空白は重要ではありません。
また, オブジェクトメンバーのシリアル化の順序は重要ではないことに注意してください。
例えば:
{ "op": "test", "path": "/a/b/c", "value": "foo" }