RFC 6901 & 6902 — JSON Pointer and JSON Patch

JSON Pointer (RFC 6901)

A JSON Pointer is a string that identifies a specific value within a JSON document. It looks like a filesystem path: a sequence of reference tokens separated by / characters. RFC 6901, published April 2013, is the formal specification.

Examples:

• "" — the root document
• /users — the top-level users key
• /users/0 — the first element of the users array
• /users/0/name — the name field of the first user

Characters / and ~ within a key are escaped as ~1 and ~0 respectively. A JSON Pointer can also be used as a URI fragment identifier (e.g., schema.json#/properties/name) — a usage common in JSON Schema's $ref resolution.

JSON Patch (RFC 6902)

JSON Patch is an HTTP PATCH media type (application/json-patch+json) for describing changes to a JSON document as a sequence of operations. RFC 6902 was published simultaneously with RFC 6901. Each operation targets a JSON Pointer path and describes what to do at that path.

A patch document is a JSON array of operation objects:

[
  { "op": "replace", "path": "/status", "value": "active" },
  { "op": "add",     "path": "/tags/0", "value": "featured" },
  { "op": "remove",  "path": "/legacy_id" }
]

Operations are applied atomically: either all succeed or the document is left unchanged (on error). This transactional guarantee is a key advantage over JSON Merge Patch.

The Six Operations

• add: Adds a value at the specified path. If the path targets an array index, the element is inserted (shifting existing elements right).
• remove: Removes the value at the specified path.
• replace: Sets the value at the specified path (equivalent to remove + add, but faster in most implementations).
• move: Moves a value from one path to another (remove + add at a different location).
• copy: Copies a value from one path to another without removing it from the source.
• test: Asserts that the value at a path equals a given value. If the assertion fails, the entire patch is rejected. Useful for optimistic concurrency checks.

Real-World Use Cases

JSON Patch is widely used in REST APIs that need granular update semantics:

• Collaborative editing: Multiple clients can independently generate patches from their local edits and apply them to a shared document, enabling operational-transform-style merging.
• Configuration management: Tools like Kubernetes use strategic merge patch and JSON Patch interchangeably for updating resource definitions.
• JSON Schema $ref: JSON Pointer is the path syntax used in JSON Schema's $ref keyword to reference sub-schemas within the same document.
• Optimistic locking: The test operation enables check-and-set semantics — a patch only applies if a specific value exists, preventing lost updates in concurrent-write scenarios.