JSON Standards Guide: RFC 6901, 6902, and 7396

JSON has become the de facto standard for data exchange on the web. However, as APIs become more complex, simple JSON objects are often not enough. Developers need standardized ways to reference specific parts of a JSON document and to describe changes to those documents. This is where RFC 6901 (JSON Pointer), RFC 6902 (JSON Patch), and RFC 7396 (JSON Merge Patch) come in.

What are JSON Pointer and Patch?

• RFC 6901 (JSON Pointer): Defines a string syntax for identifying a specific value within a JSON document. It's like an "address" for a piece of data.
• RFC 6902 (JSON Patch): Defines a JSON document structure for expressing a sequence of operations to be applied to a JSON document. It's like a "diff" or a "transaction log."
• RFC 7396 (JSON Merge Patch): Provides a simpler way to describe changes by sending a "patch" document that looks like the target document but only contains the changed fields.

1. RFC 6901: JSON Pointer

JSON Pointer uses a forward-slash (/) separated syntax to navigate through the hierarchy of a JSON object.

Syntax Rules:

• / represents the root.
• /foo points to the value of the "foo" key.
• /foo/0 points to the first element of the "foo" array.
• ~1 is used to represent a literal /.
• ~0 is used to represent a literal ~.

Example:

{
  "biscuits": [
    { "name": "Digestive" },
    { "name": "Choco" }
  ]
}

Pointer /biscuits/1/name would resolve to "Choco".

2. RFC 6902: JSON Patch

JSON Patch is an array of operation objects. Each object must have an op field.

Operations:

• add: Adds a value at the specified path.
• remove: Removes the value at the path.
• replace: Replaces the value at the path.
• move: Moves a value from one path to another.
• copy: Copies a value from one path to another.
• test: Tests that a value at a path is as expected.

Example Patch:

[
  { "op": "replace", "path": "/biscuits/0/name", "value": "Oatmeal" },
  { "op": "add", "path": "/biscuits/-", "value": { "name": "Ginger" } }
]

The - in /biscuits/- means "the end of the array."

3. RFC 7396: JSON Merge Patch

JSON Merge Patch is much simpler than RFC 6902. You simply send a JSON object that represents the desired final state of the fields you want to change.

Rules:

• If the patch contains a field with a non-null value, that field is updated or added.
• If the patch contains a field with a null value, that field is removed from the target.
• It is not suitable for patching arrays (it replaces the whole array).

Example:

Target:

{ "a": "b", "c": "d" }

Patch:

{ "a": "z", "c": null, "e": "f" }

Result:

{ "a": "z", "e": "f" }

Comparison: Patch vs. Merge Patch

Feature	RFC 6902 (Patch)	RFC 7396 (Merge Patch)
Complexity	High (Array of ops)	Low (Object-based)
Efficiency	Very High (Surgical)	Moderate (Field-level)
Array Support	Full Support	Poor (Replaces entire array)
Atomic Ops	Yes (test op)	No
Best For	Complex state changes	Simple property updates

FAQ

Q: Which one should I use for my API? A: Use JSON Merge Patch (7396) for simple resource updates where you don't care about precise array manipulation. Use JSON Patch (6902) for complex resources, high-performance requirements, or when you need atomic "test-and-set" operations.

Q: Can I use JSON Pointer in my URL? A: Yes, it is common to use JSON Pointers in URI fragments (e.g., example.com/schema.json#/definitions/user).

Q: How do I handle special characters in keys? A: Use ~1 for / and ~0 for ~. For example, a key named a/b is referenced as /a~1b.

Related Tools

• JSON Formatter & Validator - Use this to validate your Patch or Merge Patch documents.
• JSON to CSV Converter - Flatten your JSON data for analysis.