nlohmann::basic_json::merge_diff¶

static basic_json merge_diff(const basic_json& source,
                             const basic_json& target);

Creates a JSON Merge Patch so that value source can be changed into the value target by calling the merge_patch function. The patch contains only what differs: changed and added members with their new values, and removed members with the value null. Nested objects are compared member by member; any other value that differs, including an array, is replaced as a whole.

For two JSON values source and target, where target contains no object member whose value is null, the following code always yields true:

basic_json patched = source;
patched.merge_patch(merge_diff(source, target));
patched == target;

Parameters¶

source (in): JSON value to compare from
target (in): JSON value to compare against

Return value¶

a JSON Merge Patch to convert the source to target

Exception safety¶

Strong guarantee: source and target are never modified.

Complexity¶

Linear in the total number of values (including nested ones) in source and target, times the cost of a key-based object operation (looking up a key, or adding one to the patch): logarithmic for json, and linear for ordered_json (see ordered_map complexity). For ordered_json, diffing two objects with n and m members therefore takes O((n+m)²).

Notes¶

A merge patch uses null to remove a member, so it cannot set a member to null. As in RFC 7396, a null member of target is treated as absent: the patch removes the member from source instead of setting it to null. A member that is null in both source and target is unchanged and left out of the patch, so source keeps it.
A merge patch cannot reorder object members, and merge_patch appends added members at the end. For ordered_json, the patched value therefore has the same members as target, but not necessarily in the same order, and may compare unequal to it. The patch lists changed and removed members in the order of source, followed by added members in the order of target.

Examples¶

Example

The following code shows how a JSON Merge Patch is created as a diff for two JSON values.

#include <iostream>
#include <iomanip>
#include <nlohmann/json.hpp>

using json = nlohmann::json;
using namespace nlohmann::literals;

int main()
{
    // the source document
    json source = R"(
        {
            "title": "Goodbye!",
            "author": {
                "givenName": "John",
                "familyName": "Doe"
            },
            "tags": [
                "example",
                "sample"
            ],
            "content": "This will be unchanged"
        }
    )"_json;

    // the target document
    json target = R"(
        {
            "title": "Hello!",
            "author": {
                "givenName": "John"
            },
            "tags": [
                "example"
            ],
            "content": "This will be unchanged",
            "phoneNumber": "+01-123-456-7890"
        }
    )"_json;

    // create the patch
    json patch = json::merge_diff(source, target);

    // roundtrip
    json patched_source = source;
    patched_source.merge_patch(patch);

    // output patch and roundtrip result
    std::cout << std::setw(4) << patch << "\n\n"
              << std::setw(4) << patched_source << std::endl;
}

Output:

{
    "author": {
        "familyName": null
    },
    "phoneNumber": "+01-123-456-7890",
    "tags": [
        "example"
    ],
    "title": "Hello!"
}

{
    "author": {
        "givenName": "John"
    },
    "content": "This will be unchanged",
    "phoneNumber": "+01-123-456-7890",
    "tags": [
        "example"
    ],
    "title": "Hello!"
}

Version history¶

Added in version 3.13.0 unreleased.