JSON Patch

Original Article ↗ Hacker News Discussion ↗

Use cases and perceived benefits

  • Seen as useful beyond HTTP, analogous to a structured “diff” format for JSON.
  • Common use cases: efficient updates to large documents/arrays, undo/redo stacks, partial API updates, reactive server→client state sync, multi-client coordination using test for optimistic concurrency, and cloud APIs (e.g., AWS Cloud Control).
  • Multi-op patches plus test are valued for atomic, transaction-like updates: either all changes apply or none.

Alternatives and “simpler” PATCH models

  • Many prefer “merge-style” patches (JSON Merge Patch / partial objects) where:
    • Missing keys = untouched, explicit null = delete, other values = set.
    • This feels more intuitive and requires “nothing new to learn.”
  • JSON Merge Patch is highlighted as good for most cases, with arrays replaced wholesale rather than partially updated.
  • Some argue that for many APIs, simple merge semantics plus good modeling (e.g., splitting documents, using subresources) avoids needing JSON Patch at all.

Path syntax and JSON Pointer criticism

  • JSON Patch’s reliance on JSON Pointer (/foo/bar) draws complaints:
    • / is unintuitive compared to dot notation; escaping with ~0/~1 feels alien.
    • Using strings requires custom parsing and escaping; several suggest an array path format like ["foo", 0, "bar"].
  • Desire for richer selectors:
    • Select list items by key/value (e.g., plants[latin=="Ceiba speciosa"]), or insert “after” a given element.
    • JSONPath/JMESPath mentioned as alternatives that support querying but are not part of RFC6902.

Concurrency, idempotency, and integrity

  • JSON Patch is criticized as weak for concurrent writes and non-idempotent array ops (add/move).
  • test is recommended to ensure the server document matches expectations before applying changes.
  • Some want optional checksums or original values in patches; others note this partially overlaps with test.

Representation, performance, and scope

  • Debate over forcing JSON as internal representation:
    • Critics prefer native/binary structures plus generic diff tools (rsync, Zstd patches) or DB-level replication.
    • Supporters note many systems already store JSON (or JSON-like) in databases, making patching natural.
  • Applying patches can be slower on large numbers of resources; some report performance issues.

Limitations and edge cases

  • Hard or impossible with JSON Patch:
    • Editing substrings, collaborative text editing, reordering arrays, or patching associative arrays/“lists with keys” by key.
  • Several note maintenance burden: paths become stale as schemas change, though this would break any stateful client regardless.