Visual RFC.
ALL RFCs / RFC 6902
Read the RFC ↗

RFC 6902 / START HERE

JSON Patch, before the details

JSON means JavaScript Object Notation, a format for structured values. Patch is an ordinary word for a set of edits; JSON Patch is the name of this instruction format.

It is a list of instructions for changing a JSON document: add, remove, replace, move, copy and test. Each instruction names a location using a JSON Pointer, such as /items/1 for the second array element.

Start the guide See the 5 chapters ↓

The idea in one picture

  1. Original JSON

  2. Ordered edits

  3. Updated JSON

A simplified picture of the idea; the chapters explain the actual mechanisms.

Why it exists

It lets an application describe precise edits in order instead of replacing a whole document. RFC6902 defines this format and its media type; HTTP PATCH is a separate method, and JSON Merge Patch is a different format.

A familiar example

A fictional picnic planner inserts a snack into a list, then checks a count before saving. Earlier edits change the positions later edits see. A failed test makes the patch unsuccessful, and an HTTP PATCH must not leave a partly updated resource. Understanding the edits does not grant permission to make them.

Helpful background

You can start here without reading another RFC. If these ideas are unfamiliar, these short introductions may help.

JSONRFC 8259 · beginner overview ↗JSON PointerRFC 6901 · beginner overview ↗HTTP PATCHRFC 5789 · beginner overview ↗

What you’ll learn next

Begin with chapter one, or choose a topic.

  1. Apply operations in array orderA JSON Patch is an array of edit instructions. Each operation sees the result of the preceding one.
  2. Resolve paths and existing parentsA path names the place to edit. Adding a missing leaf is allowed, but its containing object or array must already exist.
  3. Insert, remove and replace array elementsArray positions are zero-based and move as elements are inserted or removed. A supplied array is one value, not a spread instruction.
  4. Copy values and move after removalcopy retains the source. move removes it first, then interprets its destination on the resulting document.
  5. Test values and commit an HTTP patch atomicallytest compares JSON values without editing them. A failed operation means the patch is not successful; HTTP PATCH must not leave partial changes.
Start with chapter one →

This introduction explains RFC 6902 (2013). Read the original RFC ↗