wt/json

mirror of https://github.com/nlohmann/json.git synced 2026-10-13 10:14:53 +00:00

Files

T

satelliteprogrammer 40a62947d3 support JSON Merge Patch (RFC 7396) diff creation (#4965 )

* 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>

2026-10-12 09:33:43 +02:00

2.1 KiB

Raw Blame History

nlohmann::basic_json::merge_patch

void merge_patch(const basic_json& apply_patch);

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.

The function implements the following algorithm from Section 2 of RFC 7396 (JSON Merge Patch):

define MergePatch(Target, Patch):
  if Patch is an Object:
    if Target is not an Object:
      Target = {} // Ignore the contents and set it to an empty Object
    for each Name/Value pair in Patch:
      if Value is null:
        if Name exists in Target:
          remove the Name/Value pair from Target
      else:
        Target[Name] = MergePatch(Target[Name], Value)
    return Target
  else:
    return Patch

Thereby, Target is the current object; that is, the patch is applied to the current value.

Parameters

apply_patch (in): the patch to apply

Exception safety

Basic guarantee: if an exception is thrown during the operation, the JSON value may be partially modified.

Complexity

Linear in the lengths of apply_patch.

Notes

apply_patch may be #!cpp *this itself or refer to a value contained in #!cpp *this (for example, a subobject returned by #!cpp (*this)[key]); it is read as it was when merge_patch() was called, before any modification of #!cpp *this.

Examples

??? 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"
```

Version history

Added in version 3.0.0.
Fixed use of freed or relocated memory when apply_patch is #!cpp *this or refers to a value contained in #!cpp *this, in version 3.13.0.

2.1 KiB Raw Blame History