JSON Patch

Original Article ↗ Hacker News Discussion ↗

JSON Patch (RFC 6902) — a standard for describing changes to JSON documents as structured operations instead of raw text diffs — draws both praise for enabling atomic, fine-grained updates and criticism for its complexity and edge cases. Commenters highlight strengths like transactional multi-field updates, use in APIs and databases, and support for tools that auto-generate patches, but point out shortcomings around array handling, lack of string edit operations, concurrency, and non‑idempotent behavior. Many suggest simpler or more specialized alternatives such as JSON Merge Patch, JSONPath-based selectors, database-native update mechanisms, or even higher-level scripting and CRDTs when richer semantics or collaborative editing are needed.

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.