4. 操作
操作对象 (operation object) MUST 恰好有一个 "op" 成员, 其值指示要执行的操作. 该值 MUST 是 "add", "remove", "replace", "move", "copy", 或 "test" 之一; 其他值均为错误. 每种对象的语义定义如下.
此外, 操作对象 MUST 恰好有一个 "path" 成员. 该成员的值是一个包含 JSON-Pointer 值 [RFC6901] 的字符串, 引用目标文档内执行操作的位置 (即 "目标位置 (target location)").
其他操作对象成员的含义由具体操作定义 (见下面各小节). 对于相关操作未显式定义的成员 MUST 被忽略 (即该操作会像未定义成员没有出现在对象中一样完成).
注意, 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], Section 2.5) 之后应用.
4.1. add
"add" 操作会根据目标位置 (target location) 引用的内容, 执行以下功能之一:
-
如果目标位置指定的是数组索引, 则在数组的指定索引处插入一个新值.
-
如果目标位置指定的是尚不存在的对象成员, 则向对象添加一个新成员.
-
如果目标位置指定的是已经存在的对象成员, 则替换该成员的值.
操作对象 MUST 包含一个 "value" 成员, 其内容指定要添加的值.
例如:
{ "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }
应用该操作时, 目标位置 MUST 引用以下之一:
-
目标文档的根 - 此时指定的值会成为目标文档的全部内容.
-
要添加到现有对象的成员 - 此时提供的值会添加到该对象中指示的位置. 如果该成员已经存在, 则由指定的值替换它.
-
要添加到现有数组的元素 - 此时提供的值会添加到数组中指示的位置. 位于指定索引处或其后的任何元素都会向右移动一个位置. 指定的索引 MUST NOT 大于数组中的元素数量. 如果使用
"-"字符来索引数组末尾 (见 [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" }
如果从数组中移除一个元素, 则位于指定索引之后的任何元素都会向左移动一个位置.
4.3. replace
"replace" 操作会用新值替换目标位置处的值. 操作对象 MUST 包含一个 "value" 成员, 其内容指定替换值.
目标位置 MUST 存在, 操作才能成功.
例如:
{ "op": "replace", "path": "/a/b/c", "value": 42 }
在功能上, 此操作等同于先对某个值执行 "remove" 操作, 随后立即在同一位置使用替换值执行 "add" 操作.
4.4. move
"move" 操作会移除指定位置处的值, 并将其添加到目标位置.
操作对象 MUST 包含一个 "from" 成员, 它是一个包含 JSON Pointer 值的字符串, 引用目标文档中要从中移动该值的位置.
"from" 位置 MUST 存在, 操作才能成功.
例如:
{ "op": "move", "from": "/a/b/c", "path": "/a/b/d" }
在功能上, 此操作等同于先对 "from" 位置执行 "remove" 操作, 随后立即在目标位置使用刚刚移除的值执行 "add" 操作.
"from" 位置 MUST NOT 是 "path" 位置的真前缀; 即一个位置不能被移动到它自己的某个子位置中.
4.5. copy
"copy" 操作会将指定位置处的值复制到目标位置.
操作对象 MUST 包含一个 "from" 成员, 它是一个包含 JSON Pointer 值的字符串, 引用目标文档中要从中复制该值的位置.
"from" 位置 MUST 存在, 操作才能成功.
例如:
{ "op": "copy", "from": "/a/b/c", "path": "/a/b/e" }
在功能上, 此操作等同于在目标位置使用 "from" 成员指定的值执行 "add" 操作.
4.6. test
"test" 操作用于测试目标位置处的值是否等于指定值.
操作对象 MUST 包含一个 "value" 成员, 该成员承载要与目标位置处的值进行比较的值.
目标位置处的值 MUST 等于 "value" 的值, 该操作才被视为成功.
这里, "相等" 是指目标位置处的值和 "value" 所承载的值具有相同的 JSON 类型, 并且按照该类型的以下规则被视为相等:
-
strings: 如果包含相同数量的 Unicode 字符, 且其码点逐字节相等, 则视为相等.
-
numbers: 如果数值上相等, 则视为相等.
-
arrays: 如果包含相同数量的值, 且按照本列表中的类型特定规则, 每个值都可视为等于另一个数组中对应位置处的值, 则视为相等.
-
objects: 如果包含相同数量的成员, 且通过比较键 (作为字符串) 和值 (使用本列表中的类型特定规则), 每个成员都可视为等于另一个对象中的某个成员, 则视为相等.
-
literals (false, true, and null): 如果二者相同, 则视为相等.
注意, 所执行的比较是逻辑比较; 例如, 数组成员值之间的空白并不重要.
另请注意, 对象成员序列化时的顺序并不重要.
例如:
{ "op": "test", "path": "/a/b/c", "value": "foo" }