PATCH: merge patch vs JSON Patch

API design: REST, HTTP, GraphQL and gRPC Mid-level Python 3.13+ PostgreSQL 17+ Reviewed By Best Latest Apps

Predict the output

Apply a merge patch. What's the result?

Python 3.13
Doc = dict[str, object]


def merge(target: Doc, patch: Doc) -> Doc:
    out = dict(target)
    for k, v in patch.items():
        if v is None:
            out.pop(k, None)
        else:
            out[k] = v
    return out

doc: Doc = {"name": "Ana", "nick": "A", "tags": [1, 2]}
print(merge(doc, {"nick": None, "tags": [3]}))

Options
Hint 1 of 1

What does null mean in a merge patch?

Choose an answer, then open Show answer below to check it.

Show answer

Answer: A {'name': 'Ana', 'tags': [3]}

Correct. null removes nick; the array is replaced, not merged.

JSON Merge Patch (RFC 7396) has two rules here: a null value deletes the key, and any other value, including an array, replaces what was there. Keys missing from the patch stay as they were.

Why not the others?
  • B {'name': 'Ana', 'nick': None, 'tags': [3]}. In merge patch, null means delete.
  • C {'name': 'Ana', 'tags': [1, 2, 3]}. Arrays are replaced wholesale.
  • D {'nick': None, 'tags': [3]}. Fields not in the patch stay.

30-second answer

Two standards: JSON Merge Patch (RFC 7396, application/merge-patch+json) sends a partial document; fields present are replaced, and null means delete the field. It's simple but can't set a field to null as a value or edit array elements. JSON Patch (RFC 6902) sends a list of operations (add, remove, replace, test) with paths, which handles arrays and conditional updates at the cost of complexity. Pair either with If-Match.

Practise saying it · 30 s. No recording, just a timer

Explain PATCH formats.

Say your answer out loud, then check which of these points you covered:

  • Merge patch: partial doc, null deletes
  • Arrays replaced
  • JSON Patch: operations
  • Absent vs null
  • If-Match

Deep dive

Merge patch replaces arrays wholesale.

JSON Patch's test op makes the patch fail if a value isn't what you expect.

Validate the resulting resource, not just the patch.

Distinguish 'field absent' from 'field null' in your request models (Pydantic: model_fields_set).

Common mistakes

  • Treating absent and null the same and wiping fields.
  • PATCH that silently ignores unknown fields the client meant to change.
  • No concurrency control on PATCH.

Senior take & follow-ups

Compare the two RFCs, explain the null and array limits, and add If-Match.

Follow-up questions

Think of your answer first, then open the hint.

  1. How do you tell absent from null in Python?

    Show hint

    Track which fields were set, e.g. a sentinel default or Pydantic's model_fields_set.

  2. When pick JSON Patch?

    Show hint

    Array edits, or when you need test-and-set semantics.

Related questions

Suggest a fix if something here is wrong or out of date.