JSON Patch Specification

JSON Patch is a format for describing changes to a JSON document.

The patch documents are themselves JSON documents, consisting of a single operation or an array of operations.

Example

Input:

{"baz": "qux", "foo": "bar"}

Patch:

[
    {"op": "set", "path": "$.baz", "value": "boo"},
    {"op": "set", "path": "$.hello", "value": ["world"]},
    {"op": "del", "path": "$.foo"}
]

Output:

{"baz": "boo", "hello": ["world"]}

Schema

https://github.com/nineteendo/jsonyx/blob/2.3.x/json-patch.schema.json

Operations

append

Append a value to the end of an array.

Fields:

  • op (string) - the operation to perform. Must be "append".

  • path (string, default: "$") - the absolute path to the array.

  • value (any) - a value.

Example:

Input:

[1, 2, 3]

Patch:

{"op": "append", "value": 4}

Output:

[1, 2, 3, 4]

assert

Test if a condition is true.

Fields:

  • op (string) - the operation to perform. Must be "assert".

  • path (string, default: "$") - the absolute path where the expression is evaluated.

  • expr (string) - an expression.

  • msg (string, default: "Path <path>: <expr>"): an error message

Example:

Input:

false

Good patch:

{"op": "assert", "expr": "@ == false"}

Bad patch:

{"op": "assert", "expr": "@ == true"}

clear

Remove all items from an array or all properties from an object.

Fields:

  • op (string) - the operation to perform. Must be "clear".

  • path (string, default: "$") - the absolute path to the array or object.

Example:

Input:

[1, 2, 3]

Patch:

{"op": "clear"}

Output:

[]

copy

Copy a value.

Fields:

  • op (string) - the operation to perform. Must be "copy".

  • mode (string) - the paste mode. Must be:

    • "append" - append the source value to the end of a target array.

    • "extend" - extend the target array with the values of the source array.

    • "insert" - insert the source value at the specified index in the target array. In this mode, the to field is required.

    • "set" - replace the target value with the source value.

    • "update" - update the target object with the properties of the source object, overwriting existing properties.

  • path (string, default: "$") - the absolute path where the operation is applied.

  • from (string) - the relative path to the source value.

  • to (string, default: "@") - the relative path to the target value.

Example:

Input:

{"a": 0}

Patch:

{"op": "copy", "mode": "set", "from": "@.a", "to": "@.b"}

Output:

{"a": 0, "b": 0}

Note

You can’t use a filter in the from and to fields.

del

Delete an item from an array or a property from an object.

Fields:

  • op (string) - the operation to perform. Must be "del".

  • path (string) - the absolute path to the item.

Example:

Input:

[1, 2, 3]

Patch:

{"op": "del", "path": "$[1]"}

Output:

[1, 3]

Tip

Using a filter instead of an index is more robust.

extend

Extend an array with the values of another array.

Fields:

  • op (string) - the operation to perform. Must be "extend".

  • path (string, default: "$") - the absolute path to the array.

  • values (array) - another array.

Example:

Input:

[1, 2, 3]

Patch:

{"op": "extend", "values": [4, 5, 6]}

Output:

[1, 2, 3, 4, 5, 6]

insert

Insert a value at the specified index in an array.

Fields:

  • op (string) - the operation to perform. Must be "insert".

  • path (string) - the absolute path with the index in the array.

  • value (any) - a value.

Example:

Input:

[1, 2, 3]

Patch:

{"op": "insert", "path": "$[0]", "value": 0}

Output:

[0, 1, 2, 3]

Tip

Using a filter instead of an index is more robust.

move

Move a value.

Fields:

  • op (string) - the operation to perform. Must be "move".

  • mode (string) - the paste mode. Must be:

    • "append" - append the source value to the end of a target array.

    • "extend" - extend the target array with the values of the source array.

    • "insert" - insert the source value at the specified index in the target array. In this mode, the to field is required.

    • "set" - replace the target value with the source value.

    • "update" - update the target object with the items of the source object, overwriting existing properties.

  • path (string, default: "$") - the absolute path where the operation is applied.

  • from (string) - the relative path to the source value.

  • to (string, default: "@") - the relative path to the target value.

Example:

Input:

{"a": 0}

Patch:

{"op": "move", "mode": "set", "from": "@.a", "to": "@.b"}

Output:

{"b": 0}

Note

You can’t use a filter in the from and to fields.

reverse

Reverse the items from an array.

Fields:

  • op (string) - the operation to perform. Must be "reverse".

  • path (string, default: "$") - the absolute path to the array.

Example:

Input:

[1, 2, 3]

Patch:

{"op": "reverse"}

Output:

[3, 2, 1]

set

Replace an item of an array, a property of an object or the root.

Fields:

  • op (string) - the operation to perform. Must be "set".

  • path (string, default: "$") - the absolute path to the value.

  • value (any) - a value.

Example:

Input:

false

Patch:

{"op": "set", "value": true}

Output:

true

sort

Sort an array.

Fields:

  • op (string) - the operation to perform. Must be "sort".

  • path (string, default: "$") - the absolute path to the array.

  • reverse (boolean, default: false) - sort in descending order.

Example:

Input:

[3, 1, 2]

Patch:

{"op": "sort"}

Output:

[1, 2, 3]

update

Update an object with the properties of another object, overwriting existing properties.

Fields:

  • op (string) - the operation to perform. Must be "update".

  • path (string, default: "$") - the absolute path to the object.

  • properties (object) - another object.

Example:

Input:

{"a": 1, "b": 2, "c": 3}

Patch:

{"op": "update", "properties": {"a": 4, "b": 5, "c": 6}}

Output:

{"a": 4, "b": 5, "c": 6}