New JSON Patch Operators and Modifiers

[huggsboson]

We've loved using the JSONPatch specification thus far and have built a number of internal and external APIs to use it. I wanted to get your thoughts on a few additions we will be pursuing to the JSONPatch spec (using a different content-type application/vnd.box.json-patch+json).

You are already aware of our desire for a strict-add operator and put it on the json-patch2 issue list. We are going to use patches to help us describe migrations on json which have a number of optional fields. We ended up wanting to make sure that everything made sense and was consistent with the existing set of operators and easy to reason about. Also we are contemplating a few new operators for dealing with paths with certain values.

Before I jump in, I realize this ups the complexity of the spec a bit, but we actually have need for each and everyone of these new operators and new modifiers. Some of the combinations of operators and modifiers aren't really needed for us, but we wanted to specify them fully to ensure that the convention we described actually generalizes properly.

Modifiers

The rule we've found when studying the existing operators is:
Operators throw if source does not exist and do not care if dest exists or does not exist

What we are looking to do is add a number of new operators that follow this naming convention:
A suffix on operators for modifiers on source:
? = skip if source does not exist

A suffix on operators for modifiers on dest:
! = throws if dest exists

• = skip if dest exists

Here's a helpful model for understanding:

​
add: { "op": "add", "path": "/foo", "value": "bar" } -- destination only
add -- overwrite dest either way
add! -- throw if dest is exists (aka the-one-true-add)
add* -- skip if dest exists (aka default operator)

remove: { "op": "remove", "path": "/foo" } -- source only
remove -- throw if source is missing otherwise delete
remove? -- skip if source is missing

replace: { "op": "replace", "path": "/foo", "value": "bar" } -- source only
replace -- throw if source is missing otherwise replace value
replace? -- skip if source is missing

copy: { "op": "copy", "from": "/foo", "path": "/bar" }
copy -- throws if source does not exist otherwise set or overwrite
copy? -- skips if source does not exist
copy! -- throws if dest already exists
copy* -- skips if dest already exists
ban: copy?! -- throw if dest exists or skip if source is missing
ban: copy?* -- skip if source does not exist or dest does exist

move: { "op": "move", "from": "/foo", "path": "/bar" }
move -- throws if source does not exist
move? -- skips if source does not exist
move! -- throws if source already exists, throws if dest already exists
move* -- skip if dest already exists
...

test: { "op": "test", "path": "/foo", "value": "bar" } -- source only
test -- throws if does not exist or is not equal value
test? - skips if source does not exist
!test -- throws if does not exist or value is equal, special.
!test? -- skip if source does not exist or throw if value is equal, special.

New Operators

We are also looking to add some new base operators: exists, translate, omit.
exists: { "op": "exists", "path": "/foo" } -- source only
exists -- throws if source does not exist
!exists -- throws if source exists, special.

translate: { "op": "translate", "path": "/foo", "from": "bar", "value": "baz" } -- source only
translate -- translates values at path that match "from" to "value"
translate? -- skip if source does not exist

omit: { "op": "omit", "path": "/foo", "value": "bar" } -- source only
omit -- remove the property or item if it matches value, throw if source does not exist
omit? -- skip if source does not exist

So yeah, I know you are pretty open to extensions as long as we are clear about the content-type. I'd just love any feedback you have about the design choices we've made so we can avoid deviating too much from any future plans you have.

[konrad7d]

+1 especially for the ability to test for element non-existence (the "!exists" keyword).

[mitar]

I think this is adding to much complexity to JSON patch. I think JSON patch should just provide a diff against a known version of base JSON and then external algorithms should be used to fuzzy-apply this if base JSON does not exactly match. I would suggest that JSON patch only standardizes some ways to provide more operation-level and global-level context to help with such fuzzy-apply algorithms.

The problem is that JSON is an array, Maybe we should make it an object with one property for steps of the patch, so:

{
  "context": <value>,
  "steps": [
    ...
  ]
}

This would make it much easier to extend. And add some global metadata to the whole set of steps. While additional metadata could go into each step as well.