mirror of
https://github.com/nlohmann/json.git
synced 2026-10-15 18:57:13 +00:00
satelliteprogrammer
40a62947d3
* support JSON Merge Patch (RFC 7396) diff creation The JSON merge patch document format describes the set of modifications to a resource's content, that more closely mimics the syntax of the resource being modified. However, and in contrast to JSON Patch (RFC 6902), a JSON Merge Patch cannot express certain modifications, e.g., changing an array element at a specific index, or setting a specific object value to null. The null value in a JSON Merge Patch is used to remove the key from the object. The diff algorithm is not part of the RFC 7396, but it was tested against all examples provided, plus additional cases on how null values are handled. Signed-off-by: Luís Murta <luis@murta.dev> * improve algorithm efficiency Signed-off-by: Luís Murta <luis@murta.dev> * fix inconsistent nulls and empty arrays Also add CHECKs for the patch, documentation and run `make amalgamate`. Signed-off-by: Luís Murta <luis@murta.dev> * documentation cleanups Signed-off-by: Luís Murta <luis@murta.dev> * add an iterative fallback to merge_diff Bound the recursion depth like diff() and merge_patch(), and test values nested past the bound. Signed-off-by: Luís Murta <luis@murta.dev> * address the remaining review comments Signed-off-by: Luís Murta <luis@murta.dev> * move multi-line raw strings out of CHECK macros GCC 4.8/5, ICPC and NVHPC mis-tokenize multi-line raw string literals inside macro arguments, breaking the build or the parsed JSON. Signed-off-by: Luís Murta <luis@murta.dev> --------- Signed-off-by: Luís Murta <luis@murta.dev>
43 lines
1.9 KiB
Markdown
43 lines
1.9 KiB
Markdown
# JSON Merge Patch
|
|
|
|
The library supports JSON Merge Patch ([RFC 7386](https://tools.ietf.org/html/rfc7386)) as a patch format.
|
|
The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of
|
|
modifications to a target resource's content. This function applies a merge patch to the current JSON value.
|
|
|
|
Instead of using [JSON Pointer](json_pointer.md) to specify values to be manipulated, it describes the changes using a
|
|
syntax that closely mimics the document being modified. Unlike [JSON Patch](json_patch.md), a JSON Merge Patch cannot
|
|
express every kind of change (e.g., it cannot reorder array elements or remove a specific array element), but it is
|
|
easier to read and write for object-shaped documents.
|
|
|
|
The function [`merge_diff`](../api/basic_json/merge_diff.md) creates a merge patch that changes one JSON value into
|
|
another.
|
|
|
|
!!! tip "Not a general deep merge"
|
|
|
|
A merge patch is not a general deep merge: a `#!json null` value in the patch deletes the key from the target.
|
|
To merge two objects recursively (e.g., defaults and user settings), use
|
|
[`update`](../api/basic_json/update.md) with `merge_objects` set to `#!cpp true`; see
|
|
[Merging objects](modifying_values.md#merging-objects).
|
|
|
|
??? example
|
|
|
|
The following code shows how a JSON Merge Patch is applied to a JSON document.
|
|
|
|
```cpp
|
|
--8<-- "examples/merge_patch.cpp"
|
|
```
|
|
|
|
Output:
|
|
|
|
```json
|
|
--8<-- "examples/merge_patch.output"
|
|
```
|
|
|
|
## See also
|
|
|
|
- [JSON Patch and Diff](json_patch.md) - a more expressive alternative that describes a sequence of operations
|
|
- [JSON Pointer](json_pointer.md) - the addressing scheme used by JSON Patch
|
|
- Function [`merge_patch`](../api/basic_json/merge_patch.md)
|
|
- Function [`merge_diff`](../api/basic_json/merge_diff.md)
|
|
- Function [`update`](../api/basic_json/update.md) - merge objects, optionally recursively
|