Back to Blog

    JsonifyTools field guide

    JSON Diff vs. JSON Patch: Which One Do You Need?

    Learn the difference between reviewing JSON changes and representing updates with RFC 6902 JSON Patch or JSON Merge Patch.

    By JsonifyTools4 min read
    COMPARE OR UPDATE?: diff ≠ patch — review output versus API operationsDIFFexplain change≠PATCHapply operationsCOMPARE OR UPDATE?diff ≠ patchreview output versus API operations
    A diagram illustrating review output versus api operations.

    “We need a JSON diff” can mean two different things: show a reviewer what changed, or send a server an instruction to update a resource. Those are related jobs, but their output formats and failure modes differ. Picking the wrong one can leave an API client trying to submit a Git-style patch where the endpoint expects operations.

    Review JSON changes

    A diff is a comparison view

    A diff compares a before document with an after document and presents additions, removals, or edits. A text diff may look like unified Git output; a structural JSON diff can point to paths such as profile.email. Its purpose is explanation and review. The output is not automatically an API request body.

    Human-readable change summary
    ~ profile.email
      before: "old@example.test"
      after:  "new@example.test"
    + profile.timezone: "UTC"

    JSON Patch is an operation document

    RFC 6902 defines a JSON Patch document as an array of operations such as add, remove, replace, move, copy, and test. Each operation uses a JSON Pointer path. A server applies those operations according to the resource state and endpoint contract; array indexes can make an operation sensitive to earlier edits.

    RFC 6902-style replace operation
    [
      {
        "op": "replace",
        "path": "/profile/email",
        "value": "new@example.test"
      }
    ]

    This format answers “what instructions should be applied?” A review diff answers “what differs?” The same comparison can be used to help a person author an operation list, but an operation document needs correct paths, ordering, and server support. See the RFC 6902 specification.

    Merge Patch is a different update convention

    RFC 7396 JSON Merge Patch describes a patch as an object shaped like the target document. Object members are merged recursively; a member set to null means remove that member. This makes it concise for many object updates, but it also means expressing “set this property to JSON null” is ambiguous under the convention. Arrays are replaced as values rather than edited item by item.

    Merge Patch body
    {
      "profile": {
        "timezone": "UTC",
        "legacyEmail": null
      }
    }

    The null behavior is easy to miss when an application treats null as meaningful data. Read the endpoint documentation and the RFC 7396 specification before choosing this format.

    Choose by destination

    Which artifact are you producing?
    Review changes → diffUpdate a resource → endpoint patch formatReplace full state → resource document

    JsonifyTools Compare JSON is for inspecting differences. It can provide a standard unified diff view; it does not claim to emit an RFC 6902 operation array or an HTTP patch body. Use the API Tester to inspect a request and response, and format the response before you reason about its fields.

    Check the endpoint media type and concurrency rules

    JSON Patch and Merge Patch commonly use different media types, and an endpoint may support neither. Also check whether the server expects an ETag or another precondition: a patch created against an old representation may overwrite a newer update. A comparison tool can help review the state change, but the API contract decides how the update is submitted.

    Test the operation against the exact starting document

    For JSON Patch, apply operations in order to a copy of the expected resource and test array edits around insertions and removals. A pointer token containing a slash or tilde needs escaping under JSON Pointer rules. For Merge Patch, test explicit nulls and arrays. These cases are easy to overlook when an operation list is authored by hand.

    Tags

    • JSON diff vs JSON Patch
    • RFC 6902
    • JSON Merge Patch
    • RFC 7396
    • HTTP PATCH request
    • JSON change review
    • JSON Pointer
    • API update format