JSON Pointer, JSON Patch and Merge Patch

Python · pointer/pointer.py

# JSON Pointer (RFC 6901), evaluated as the RFC describes: split at "/", decode ~1 then ~0 in each token, and take one
# step per token, a member name in an object or a decimal index in an array.
import json
import re

order = {
    "id": "BK-10042",
    "status": "paid",
    "items": [{"sku": "BK-101", "qty": 2}, {"sku": "BK-205", "qty": 1}],
    "attachments": {"invoices/BK-10042.pdf": {"pages": 2}, "~draft": {"pages": 1}},
}

INDEX = re.compile(r"0|[1-9][0-9]*")  # no leading zeros, no sign
q = json.dumps  # quote a name the way JSON writes it


def kind_of(value):
    return "boolean" if isinstance(value, bool) else "null" if value is None else "string" if isinstance(value, str) else "number"


def tokens_of(pointer):
    if pointer == "":
        return []  # the empty pointer names the whole document
    if not pointer.startswith("/"):
        raise ValueError(f"{q(pointer)} does not start with /")
    if re.search(r"~(?![01])", pointer):
        raise ValueError("a ~ must be followed by 0 or 1")
    return [t.replace("~1", "/").replace("~0", "~") for t in pointer[1:].split("/")]


def pointer_get(doc, pointer):
    value = doc
    for token in tokens_of(pointer):
        if isinstance(value, dict):
            if token not in value:
                raise ValueError(f"no member {q(token)}")
            value = value[token]
        elif isinstance(value, list):
            if token == "-":
                raise ValueError('"-" is the place after the last element, which holds no value')
            if not INDEX.fullmatch(token):
                raise ValueError(f"{q(token)} is not an array index")
            if int(token) >= len(value):
                raise ValueError(f"index {token} is past the end of {len(value)} elements")
            value = value[int(token)]
        else:
            raise ValueError(f"{q(token)} goes below a {kind_of(value)}, which has no members")
    return value


def pointer_of(path):
    """Build a pointer from member names and indexes: ~ becomes ~0 first, then / becomes ~1."""
    return "".join("/" + str(p).replace("~", "~0").replace("/", "~1") for p in path)


for p in ["", "/id", "/items/1/qty", "/attachments/invoices~1BK-10042.pdf/pages", "/attachments/~0draft/pages",
          "/items/01", "/items/2", "/items/-", "/qty", "/id/0", "/items/~2"]:
    try:
        shown = json.dumps(pointer_get(order, p), separators=(",", ":"))
        if p == "":
            shown = "the whole document, " + shown[:24] + "..."
        print(f"{q(p):46} -> {shown}")
    except ValueError as e:
        print(f"{q(p):46} -> error: {e}")

print("built:", pointer_of(["attachments", "invoices/BK-10042.pdf", "pages"]))
# The order of decoding matters: the token "~01" means the name "~1".
print('"~01", ~1 decoded first:', q("~01".replace("~1", "/").replace("~0", "~")))
print('"~01", ~0 decoded first:', q("~01".replace("~0", "~").replace("~1", "/")))

""                                             -> the whole document, {"id":"BK-10042","status...
"/id"                                          -> "BK-10042"
"/items/1/qty"                                 -> 1
"/attachments/invoices~1BK-10042.pdf/pages"    -> 2
"/attachments/~0draft/pages"                   -> 1
"/items/01"                                    -> error: "01" is not an array index
"/items/2"                                     -> error: index 2 is past the end of 2 elements
"/items/-"                                     -> error: "-" is the place after the last element, which holds no value
"/qty"                                         -> error: no member "qty"
"/id/0"                                        -> error: "0" goes below a string, which has no members
"/items/~2"                                    -> error: a ~ must be followed by 0 or 1
built: /attachments/invoices~1BK-10042.pdf/pages
"~01", ~1 decoded first: "~1"
"~01", ~0 decoded first: "/"

JavaScript · pointer/pointer.mjs

// JSON Pointer (RFC 6901), evaluated as the RFC describes: split at "/", decode ~1 then ~0 in each token, and take one
// step per token, a member name in an object or a decimal index in an array.
const order = {
  id: 'BK-10042',
  status: 'paid',
  items: [{ sku: 'BK-101', qty: 2 }, { sku: 'BK-205', qty: 1 }],
  attachments: { 'invoices/BK-10042.pdf': { pages: 2 }, '~draft': { pages: 1 } },
};

const INDEX = /^(?:0|[1-9][0-9]*)$/; // no leading zeros, no sign
const q = JSON.stringify; // quote a name the way JSON writes it

const kindOf = (value) => (value === null ? 'null' : typeof value);

function tokensOf(pointer) {
  if (pointer === '') return []; // the empty pointer names the whole document
  if (!pointer.startsWith('/')) throw new Error(`${q(pointer)} does not start with /`);
  if (/~(?![01])/.test(pointer)) throw new Error('a ~ must be followed by 0 or 1');
  return pointer.slice(1).split('/').map((t) => t.replaceAll('~1', '/').replaceAll('~0', '~'));
}

function pointerGet(doc, pointer) {
  let value = doc;
  for (const token of tokensOf(pointer)) {
    if (Array.isArray(value)) {
      if (token === '-') throw new Error('"-" is the place after the last element, which holds no value');
      if (!INDEX.test(token)) throw new Error(`${q(token)} is not an array index`);
      if (Number(token) >= value.length) throw new Error(`index ${token} is past the end of ${value.length} elements`);
      value = value[Number(token)];
    } else if (value !== null && typeof value === 'object') {
      // Object.hasOwn, never `in`: an inherited name such as "constructor" is not a member of the document.
      if (!Object.hasOwn(value, token)) throw new Error(`no member ${q(token)}`);
      value = value[token];
    } else {
      throw new Error(`${q(token)} goes below a ${kindOf(value)}, which has no members`);
    }
  }
  return value;
}

/** Build a pointer from member names and indexes: ~ becomes ~0 first, then / becomes ~1. */
const pointerOf = (path) => path.map((p) => `/${String(p).replaceAll('~', '~0').replaceAll('/', '~1')}`).join('');

for (const p of ['', '/id', '/items/1/qty', '/attachments/invoices~1BK-10042.pdf/pages', '/attachments/~0draft/pages',
  '/items/01', '/items/2', '/items/-', '/qty', '/id/0', '/items/~2']) {
  try {
    let shown = JSON.stringify(pointerGet(order, p));
    if (p === '') shown = `the whole document, ${shown.slice(0, 24)}...`;
    console.log(`${q(p).padEnd(46)} -> ${shown}`);
  } catch (e) {
    console.log(`${q(p).padEnd(46)} -> error: ${e.message}`);
  }
}

console.log('built:', pointerOf(['attachments', 'invoices/BK-10042.pdf', 'pages']));
// The order of decoding matters: the token "~01" means the name "~1".
console.log('"~01", ~1 decoded first:', q('~01'.replaceAll('~1', '/').replaceAll('~0', '~')));
console.log('"~01", ~0 decoded first:', q('~01'.replaceAll('~0', '~').replaceAll('~1', '/')));

""                                             -> the whole document, {"id":"BK-10042","status...
"/id"                                          -> "BK-10042"
"/items/1/qty"                                 -> 1
"/attachments/invoices~1BK-10042.pdf/pages"    -> 2
"/attachments/~0draft/pages"                   -> 1
"/items/01"                                    -> error: "01" is not an array index
"/items/2"                                     -> error: index 2 is past the end of 2 elements
"/items/-"                                     -> error: "-" is the place after the last element, which holds no value
"/qty"                                         -> error: no member "qty"
"/id/0"                                        -> error: "0" goes below a string, which has no members
"/items/~2"                                    -> error: a ~ must be followed by 0 or 1
built: /attachments/invoices~1BK-10042.pdf/pages
"~01", ~1 decoded first: "~1"
"~01", ~0 decoded first: "/"

Python · patch/jsonpatch.py

# JSON Patch (RFC 6902): the six operations, applied in order to a copy of the document. If any operation fails, the
# copy is thrown away and the caller's document is never touched, so a patch applies whole or not at all.
import copy
import json
import re

NEEDS = {"add": ("path", "value"), "remove": ("path",), "replace": ("path", "value"),
         "move": ("from", "path"), "copy": ("from", "path"), "test": ("path", "value")}


def q(value):
    """A name or a value as compact JSON text, for messages."""
    return json.dumps(value, separators=(",", ":"))


class PatchError(Exception):
    """A patch that could not be applied; the document is unchanged."""


def tokens_of(pointer):
    """The tokens of a JSON Pointer (RFC 6901), ~1 decoded before ~0."""
    if pointer == "":
        return []
    if not pointer.startswith("/") or re.search(r"~(?![01])", pointer):
        raise PatchError(f"{q(pointer)} is not a JSON Pointer")
    return [t.replace("~1", "/").replace("~0", "~") for t in pointer[1:].split("/")]


def index_of(token, size):
    """An array index from 0 to size - 1 (add passes size + 1, so that it may name the end)."""
    if not re.fullmatch(r"0|[1-9][0-9]*", token) or int(token) >= size:
        raise PatchError(f"no array position {q(token)}")
    return int(token)


def resolve(doc, tokens):
    for token in tokens:
        if isinstance(doc, list):
            doc = doc[index_of(token, len(doc))]
        elif isinstance(doc, dict) and token in doc:
            doc = doc[token]
        else:
            raise PatchError(f"no member {q(token)}")
    return doc


def json_equal(a, b):
    """test's equality: the same JSON type, numbers by value, arrays in order, objects whatever their member order."""
    if isinstance(a, bool) or isinstance(b, bool):
        return type(a) is type(b) and a == b
    if isinstance(a, (int, float)) and isinstance(b, (int, float)):
        return a == b
    if isinstance(a, list) and isinstance(b, list):
        return len(a) == len(b) and all(json_equal(x, y) for x, y in zip(a, b))
    if isinstance(a, dict) and isinstance(b, dict):
        return a.keys() == b.keys() and all(json_equal(a[k], b[k]) for k in a)
    return type(a) is type(b) and a == b


def add(doc, tokens, value):
    if not tokens:
        return value  # the whole document is replaced
    parent, last = resolve(doc, tokens[:-1]), tokens[-1]
    if isinstance(parent, list):
        parent.insert(len(parent) if last == "-" else index_of(last, len(parent) + 1), value)
    elif isinstance(parent, dict):
        parent[last] = value  # creates the member, or replaces it
    else:
        raise PatchError(f"{q(last)} is below a value that has no members")
    return doc


def remove(doc, tokens):
    """(doc, the value removed); the value must exist."""
    if not tokens:
        raise PatchError("the whole document cannot be removed")
    parent, last = resolve(doc, tokens[:-1]), tokens[-1]
    if isinstance(parent, list):
        return doc, parent.pop(index_of(last, len(parent)))
    if isinstance(parent, dict) and last in parent:
        return doc, parent.pop(last)
    raise PatchError(f"no member {q(last)}")


def apply_op(doc, op):
    kind = op.get("op")
    if kind not in NEEDS:
        raise PatchError(f"unknown op {q(kind)}")
    if any(member not in op for member in NEEDS[kind]):
        raise PatchError(f"{kind} needs {' and '.join(NEEDS[kind])}")
    path = tokens_of(op["path"])
    if kind == "add":
        return add(doc, path, copy.deepcopy(op["value"]))
    if kind == "remove":
        return remove(doc, path)[0]
    if kind == "replace":
        if not path:
            return copy.deepcopy(op["value"])
        parent, last = resolve(doc, path[:-1]), path[-1]
        if isinstance(parent, list):
            parent[index_of(last, len(parent))] = copy.deepcopy(op["value"])
        elif isinstance(parent, dict) and last in parent:
            parent[last] = copy.deepcopy(op["value"])
        else:
            raise PatchError(f"no member {q(last)}")
        return doc
    if kind == "test":
        actual = resolve(doc, path)
        if not json_equal(actual, op["value"]):
            raise PatchError(f"the value is {q(actual)}, not {q(op['value'])}")
        return doc
    source = tokens_of(op["from"])
    if kind == "move":
        if path[: len(source)] == source and len(path) > len(source):
            raise PatchError("a value cannot move into itself")
        doc, value = remove(doc, source)
        return add(doc, path, value)
    return add(doc, path, copy.deepcopy(resolve(doc, source)))  # copy


def apply_patch(doc, patch):
    """A new document with every operation applied, or PatchError; doc itself is never changed."""
    result = copy.deepcopy(doc)
    for number, op in enumerate(patch):
        try:
            result = apply_op(result, op)
        except PatchError as e:
            raise PatchError(f"operation {number}, {op.get('op')} {op.get('path')}: {e}") from None
    return result

JavaScript · patch/jsonpatch.mjs

// JSON Patch (RFC 6902): the six operations, applied in order to a copy of the document. If any operation fails, the
// copy is thrown away and the caller's document is never touched, so a patch applies whole or not at all.
const NEEDS = {
  add: ['path', 'value'], remove: ['path'], replace: ['path', 'value'],
  move: ['from', 'path'], copy: ['from', 'path'], test: ['path', 'value'],
};
const q = JSON.stringify; // names and values as compact JSON text, for messages
const clone = (value) => JSON.parse(JSON.stringify(value)); // a JSON document copies exactly this way

export class PatchError extends Error {}

/** The tokens of a JSON Pointer (RFC 6901), ~1 decoded before ~0. */
function tokensOf(pointer) {
  if (pointer === '') return [];
  if (!pointer.startsWith('/') || /~(?![01])/.test(pointer)) throw new PatchError(`${q(pointer)} is not a JSON Pointer`);
  return pointer.slice(1).split('/').map((t) => t.replaceAll('~1', '/').replaceAll('~0', '~'));
}

/** An array index from 0 to size - 1 (add passes size + 1, so that it may name the end). */
function indexOf(token, size) {
  if (!/^(?:0|[1-9][0-9]*)$/.test(token) || Number(token) >= size) throw new PatchError(`no array position ${q(token)}`);
  return Number(token);
}

const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
// A member is set as an own data property, so a name such as "__proto__" stays data and never reaches a prototype.
const setMember = (obj, name, value) => Object.defineProperty(obj, name, { value, writable: true, enumerable: true, configurable: true });

function resolve(doc, tokens) {
  for (const token of tokens) {
    if (Array.isArray(doc)) doc = doc[indexOf(token, doc.length)];
    else if (isObject(doc) && Object.hasOwn(doc, token)) doc = doc[token];
    else throw new PatchError(`no member ${q(token)}`);
  }
  return doc;
}

/** test's equality: the same JSON type, numbers by value, arrays in order, objects whatever their member order. */
export function jsonEqual(a, b) {
  if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((x, i) => jsonEqual(x, b[i]));
  if (isObject(a) && isObject(b)) {
    const names = Object.keys(a);
    return names.length === Object.keys(b).length && names.every((k) => Object.hasOwn(b, k) && jsonEqual(a[k], b[k]));
  }
  return a === b;
}

function add(doc, tokens, value) {
  if (!tokens.length) return value; // the whole document is replaced
  const parent = resolve(doc, tokens.slice(0, -1));
  const last = tokens.at(-1);
  if (Array.isArray(parent)) parent.splice(last === '-' ? parent.length : indexOf(last, parent.length + 1), 0, value);
  else if (isObject(parent)) setMember(parent, last, value); // creates the member, or replaces it
  else throw new PatchError(`${q(last)} is below a value that has no members`);
  return doc;
}

/** [doc, the value removed]; the value must exist. */
function remove(doc, tokens) {
  if (!tokens.length) throw new PatchError('the whole document cannot be removed');
  const parent = resolve(doc, tokens.slice(0, -1));
  const last = tokens.at(-1);
  if (Array.isArray(parent)) return [doc, parent.splice(indexOf(last, parent.length), 1)[0]];
  if (isObject(parent) && Object.hasOwn(parent, last)) {
    const value = parent[last];
    delete parent[last];
    return [doc, value];
  }
  throw new PatchError(`no member ${q(last)}`);
}

function applyOp(doc, op) {
  const kind = op.op;
  if (!Object.hasOwn(NEEDS, kind)) throw new PatchError(`unknown op ${q(kind)}`);
  if (NEEDS[kind].some((member) => !Object.hasOwn(op, member))) throw new PatchError(`${kind} needs ${NEEDS[kind].join(' and ')}`);
  const path = tokensOf(op.path);
  if (kind === 'add') return add(doc, path, clone(op.value));
  if (kind === 'remove') return remove(doc, path)[0];
  if (kind === 'replace') {
    if (!path.length) return clone(op.value);
    const parent = resolve(doc, path.slice(0, -1));
    const last = path.at(-1);
    if (Array.isArray(parent)) parent[indexOf(last, parent.length)] = clone(op.value);
    else if (isObject(parent) && Object.hasOwn(parent, last)) setMember(parent, last, clone(op.value));
    else throw new PatchError(`no member ${q(last)}`);
    return doc;
  }
  if (kind === 'test') {
    const actual = resolve(doc, path);
    if (!jsonEqual(actual, op.value)) throw new PatchError(`the value is ${q(actual)}, not ${q(op.value)}`);
    return doc;
  }
  const source = tokensOf(op.from);
  if (kind === 'move') {
    if (path.length > source.length && source.every((t, i) => path[i] === t)) throw new PatchError('a value cannot move into itself');
    const [rest, value] = remove(doc, source);
    return add(rest, path, value);
  }
  return add(doc, path, clone(resolve(doc, source))); // copy
}

/** A new document with every operation applied, or PatchError; doc itself is never changed. */
export function applyPatch(doc, patch) {
  let result = clone(doc);
  patch.forEach((op, number) => {
    try {
      result = applyOp(result, op);
    } catch (e) {
      if (!(e instanceof PatchError)) throw e;
      throw new PatchError(`operation ${number}, ${op.op} ${op.path}: ${e.message}`);
    }
  });
  return result;
}

Python · patch/patch_demo.py

# Three JSON Patch documents against one stored order: one that applies, one whose last operation fails, and tests
# that show which values count as equal.
import json

from jsonpatch import PatchError, apply_patch

order = {
    "id": "BK-10042",
    "status": "paid",
    "branch": "Pune",
    "items": [{"sku": "BK-101", "qty": 2}, {"sku": "BK-205", "qty": 1}],
    "tags": ["gift", "fragile"],
}


def show(doc):
    return json.dumps(doc, separators=(",", ":"))


# 1. Every operation, applied in order to a copy of the order.
edit = [
    {"op": "test", "path": "/status", "value": "paid"},
    {"op": "replace", "path": "/items/0/qty", "value": 3},
    {"op": "add", "path": "/items/-", "value": {"sku": "BK-310", "qty": 1}},
    {"op": "remove", "path": "/tags/0"},
    {"op": "copy", "from": "/branch", "path": "/pickup"},
    {"op": "move", "from": "/items/2", "path": "/items/0"},
]
print("edited:", show(apply_patch(order, edit)))

# 2. The last operation fails, so the first two are not applied either.
ship = [
    {"op": "replace", "path": "/status", "value": "shipped"},
    {"op": "add", "path": "/tracking", "value": "AWB-7781"},
    {"op": "test", "path": "/items/0/qty", "value": 5},
]
try:
    apply_patch(order, ship)
except PatchError as e:
    print("refused:", e)
print("stored:", show(order))

# 3. Which values a test counts as equal.
for text in [
    '{"op": "test", "path": "/items/0/qty", "value": 2.0}',
    '{"op": "test", "path": "/items/0/qty", "value": "2"}',
    '{"op": "test", "path": "/items/1", "value": {"qty": 1, "sku": "BK-205"}}',
    '{"op": "test", "path": "/tags", "value": ["fragile", "gift"]}',
]:
    try:
        apply_patch(order, [json.loads(text)])
        print(f"{text} -> passes")
    except PatchError as e:
        print(f"{text} -> {str(e).split(': ', 1)[1]}")

edited: {"id":"BK-10042","status":"paid","branch":"Pune","items":[{"sku":"BK-310","qty":1},{"sku":"BK-101","qty":3},{"sku":"BK-205","qty":1}],"tags":["fragile"],"pickup":"Pune"}
refused: operation 2, test /items/0/qty: the value is 2, not 5
stored: {"id":"BK-10042","status":"paid","branch":"Pune","items":[{"sku":"BK-101","qty":2},{"sku":"BK-205","qty":1}],"tags":["gift","fragile"]}
{"op": "test", "path": "/items/0/qty", "value": 2.0} -> passes
{"op": "test", "path": "/items/0/qty", "value": "2"} -> the value is 2, not "2"
{"op": "test", "path": "/items/1", "value": {"qty": 1, "sku": "BK-205"}} -> passes
{"op": "test", "path": "/tags", "value": ["fragile", "gift"]} -> the value is ["gift","fragile"], not ["fragile","gift"]

JavaScript · patch/patch_demo.mjs

// Three JSON Patch documents against one stored order: one that applies, one whose last operation fails, and tests
// that show which values count as equal.
import { PatchError, applyPatch } from './jsonpatch.mjs';

const order = {
  id: 'BK-10042',
  status: 'paid',
  branch: 'Pune',
  items: [{ sku: 'BK-101', qty: 2 }, { sku: 'BK-205', qty: 1 }],
  tags: ['gift', 'fragile'],
};

const show = (doc) => JSON.stringify(doc);

// 1. Every operation, applied in order to a copy of the order.
const edit = [
  { op: 'test', path: '/status', value: 'paid' },
  { op: 'replace', path: '/items/0/qty', value: 3 },
  { op: 'add', path: '/items/-', value: { sku: 'BK-310', qty: 1 } },
  { op: 'remove', path: '/tags/0' },
  { op: 'copy', from: '/branch', path: '/pickup' },
  { op: 'move', from: '/items/2', path: '/items/0' },
];
console.log('edited:', show(applyPatch(order, edit)));

// 2. The last operation fails, so the first two are not applied either.
const ship = [
  { op: 'replace', path: '/status', value: 'shipped' },
  { op: 'add', path: '/tracking', value: 'AWB-7781' },
  { op: 'test', path: '/items/0/qty', value: 5 },
];
try {
  applyPatch(order, ship);
} catch (e) {
  if (!(e instanceof PatchError)) throw e;
  console.log('refused:', e.message);
}
console.log('stored:', show(order));

// 3. Which values a test counts as equal.
for (const text of [
  '{"op": "test", "path": "/items/0/qty", "value": 2.0}',
  '{"op": "test", "path": "/items/0/qty", "value": "2"}',
  '{"op": "test", "path": "/items/1", "value": {"qty": 1, "sku": "BK-205"}}',
  '{"op": "test", "path": "/tags", "value": ["fragile", "gift"]}',
]) {
  try {
    applyPatch(order, [JSON.parse(text)]);
    console.log(`${text} -> passes`);
  } catch (e) {
    if (!(e instanceof PatchError)) throw e;
    console.log(`${text} -> ${e.message.split(': ').slice(1).join(': ')}`);
  }
}

edited: {"id":"BK-10042","status":"paid","branch":"Pune","items":[{"sku":"BK-310","qty":1},{"sku":"BK-101","qty":3},{"sku":"BK-205","qty":1}],"tags":["fragile"],"pickup":"Pune"}
refused: operation 2, test /items/0/qty: the value is 2, not 5
stored: {"id":"BK-10042","status":"paid","branch":"Pune","items":[{"sku":"BK-101","qty":2},{"sku":"BK-205","qty":1}],"tags":["gift","fragile"]}
{"op": "test", "path": "/items/0/qty", "value": 2.0} -> passes
{"op": "test", "path": "/items/0/qty", "value": "2"} -> the value is 2, not "2"
{"op": "test", "path": "/items/1", "value": {"qty": 1, "sku": "BK-205"}} -> passes
{"op": "test", "path": "/tags", "value": ["fragile", "gift"]} -> the value is ["gift","fragile"], not ["fragile","gift"]

Python · patch/conditional.py

# Two support agents read the same order, both see 2 copies of BK-101, and both send a change. Without a test the
# second change silently undoes the first; with a test of the value each agent saw, the second patch is refused.
import json

from jsonpatch import PatchError, apply_patch

stored = {"id": "BK-10042", "items": [{"sku": "BK-101", "qty": 2}, {"sku": "BK-205", "qty": 1}]}


def server(doc, patch):
    """What a PATCH endpoint would answer: the new document and 200, or the old one and 409 Conflict."""
    try:
        return apply_patch(doc, patch), "200 OK"
    except PatchError as e:
        return doc, f"409 Conflict ({e})"


a_wants = {"op": "replace", "path": "/items/0/qty", "value": 3}  # the customer added a copy
b_wants = {"op": "replace", "path": "/items/0/qty", "value": 1}  # the customer returned a copy

print("without test:")
doc, status = server(stored, [a_wants])
print("  agent A:", status, "qty", doc["items"][0]["qty"])
doc, status = server(doc, [b_wants])
print("  agent B:", status, "qty", doc["items"][0]["qty"], "<- A's change is gone, and nobody was told")

print("with a test of the value each agent saw:")
saw = {"op": "test", "path": "/items/0/qty", "value": 2}
doc, status = server(stored, [saw, a_wants])
print("  agent A:", status, "qty", doc["items"][0]["qty"])
doc, status = server(doc, [saw, b_wants])
print("  agent B:", status, "qty", doc["items"][0]["qty"])
# B reads the order again, sees 3, and sends a patch built on what is really there.
doc, status = server(doc, [{"op": "test", "path": "/items/0/qty", "value": 3}, {**b_wants, "value": 2}])
print("  agent B, after reading again:", status, "qty", doc["items"][0]["qty"])
print("final:", json.dumps(doc, separators=(",", ":")))

without test:
  agent A: 200 OK qty 3
  agent B: 200 OK qty 1 <- A's change is gone, and nobody was told
with a test of the value each agent saw:
  agent A: 200 OK qty 3
  agent B: 409 Conflict (operation 0, test /items/0/qty: the value is 3, not 2) qty 3
  agent B, after reading again: 200 OK qty 2
final: {"id":"BK-10042","items":[{"sku":"BK-101","qty":2},{"sku":"BK-205","qty":1}]}

JavaScript · patch/conditional.mjs

// Two support agents read the same order, both see 2 copies of BK-101, and both send a change. Without a test the
// second change silently undoes the first; with a test of the value each agent saw, the second patch is refused.
import { PatchError, applyPatch } from './jsonpatch.mjs';

const stored = { id: 'BK-10042', items: [{ sku: 'BK-101', qty: 2 }, { sku: 'BK-205', qty: 1 }] };

/** What a PATCH endpoint would answer: the new document and 200, or the old one and 409 Conflict. */
function server(doc, patch) {
  try {
    return [applyPatch(doc, patch), '200 OK'];
  } catch (e) {
    if (!(e instanceof PatchError)) throw e;
    return [doc, `409 Conflict (${e.message})`];
  }
}

const aWants = { op: 'replace', path: '/items/0/qty', value: 3 }; // the customer added a copy
const bWants = { op: 'replace', path: '/items/0/qty', value: 1 }; // the customer returned a copy

console.log('without test:');
let [doc, status] = server(stored, [aWants]);
console.log('  agent A:', status, 'qty', doc.items[0].qty);
[doc, status] = server(doc, [bWants]);
console.log('  agent B:', status, 'qty', doc.items[0].qty, "<- A's change is gone, and nobody was told");

console.log('with a test of the value each agent saw:');
const saw = { op: 'test', path: '/items/0/qty', value: 2 };
[doc, status] = server(stored, [saw, aWants]);
console.log('  agent A:', status, 'qty', doc.items[0].qty);
[doc, status] = server(doc, [saw, bWants]);
console.log('  agent B:', status, 'qty', doc.items[0].qty);
// B reads the order again, sees 3, and sends a patch built on what is really there.
[doc, status] = server(doc, [{ op: 'test', path: '/items/0/qty', value: 3 }, { ...bWants, value: 2 }]);
console.log('  agent B, after reading again:', status, 'qty', doc.items[0].qty);
console.log('final:', JSON.stringify(doc));

without test:
  agent A: 200 OK qty 3
  agent B: 200 OK qty 1 <- A's change is gone, and nobody was told
with a test of the value each agent saw:
  agent A: 200 OK qty 3
  agent B: 409 Conflict (operation 0, test /items/0/qty: the value is 3, not 2) qty 3
  agent B, after reading again: 200 OK qty 2
final: {"id":"BK-10042","items":[{"sku":"BK-101","qty":2},{"sku":"BK-205","qty":1}]}

Python · merge/merge.py

# JSON Merge Patch (RFC 7396): the patch is an object of changes. A member set to null is deleted, any other value is
# merged in, and anything that is not an object, an array included, replaces what was there whole.
import json


def merge_patch(target, patch):
    if not isinstance(patch, dict):
        return patch  # a non-object patch replaces the target whole
    if not isinstance(target, dict):
        target = {}  # an object patch starts from an empty object
    result = dict(target)
    for name, value in patch.items():
        if value is None:
            result.pop(name, None)  # null deletes the member
        else:
            result[name] = merge_patch(result.get(name), value)
    return result


# The test cases of RFC 7396, Appendix A: original, patch and the result the RFC gives.
CASES = [
    ('{"a":"b"}', '{"a":"c"}', '{"a":"c"}'),
    ('{"a":"b"}', '{"b":"c"}', '{"a":"b","b":"c"}'),
    ('{"a":"b"}', '{"a":null}', "{}"),
    ('{"a":"b","b":"c"}', '{"a":null}', '{"b":"c"}'),
    ('{"a":["b"]}', '{"a":"c"}', '{"a":"c"}'),
    ('{"a":"c"}', '{"a":["b"]}', '{"a":["b"]}'),
    ('{"a":{"b":"c"}}', '{"a":{"b":"d","c":null}}', '{"a":{"b":"d"}}'),
    ('{"a":[{"b":"c"}]}', '{"a":[1]}', '{"a":[1]}'),
    ('["a","b"]', '["c","d"]', '["c","d"]'),
    ('{"a":"b"}', '["c"]', '["c"]'),
    ('{"a":"foo"}', "null", "null"),
    ('{"a":"foo"}', '"bar"', '"bar"'),
    ('{"e":null}', '{"a":1}', '{"e":null,"a":1}'),
    ("[1,2]", '{"a":"b","c":null}', '{"a":"b"}'),
    ("{}", '{"a":{"bb":{"ccc":null}}}', '{"a":{"bb":{}}}'),
]
right = sum(merge_patch(json.loads(o), json.loads(p)) == json.loads(r) for o, p, r in CASES)
print(f"RFC 7396, Appendix A: {right} of {len(CASES)} cases give the RFC's result")

profile = {"name": "Asha", "nickname": "Ash", "emails": ["asha@example.com", "asha.work@example.com"], "theme": "dark"}
show = lambda doc: json.dumps(doc, separators=(",", ":"))
print("change one member:  ", show(merge_patch(profile, {"theme": "light"})))
print("try to set null:    ", show(merge_patch(profile, {"nickname": None})))
print("change one email:   ", show(merge_patch(profile, {"emails": ["asha.home@example.com"]})))

RFC 7396, Appendix A: 15 of 15 cases give the RFC's result
change one member:   {"name":"Asha","nickname":"Ash","emails":["asha@example.com","asha.work@example.com"],"theme":"light"}
try to set null:     {"name":"Asha","emails":["asha@example.com","asha.work@example.com"],"theme":"dark"}
change one email:    {"name":"Asha","nickname":"Ash","emails":["asha.home@example.com"],"theme":"dark"}

JavaScript · merge/merge.mjs

// JSON Merge Patch (RFC 7396): the patch is an object of changes. A member set to null is deleted, any other value is
// merged in, and anything that is not an object, an array included, replaces what was there whole.
const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
// A member is set as an own data property, so a name such as "__proto__" stays data and never becomes a prototype.
const setMember = (obj, name, value) => Object.defineProperty(obj, name, { value, writable: true, enumerable: true, configurable: true });

function mergePatch(target, patch) {
  if (!isObject(patch)) return patch; // a non-object patch replaces the target whole
  const result = isObject(target) ? { ...target } : {}; // an object patch starts from an empty object
  for (const [name, value] of Object.entries(patch)) {
    if (value === null) delete result[name]; // null deletes the member
    else setMember(result, name, mergePatch(Object.hasOwn(result, name) ? result[name] : undefined, value));
  }
  return result;
}

/** Whether two JSON values are equal, whatever the order of object members. */
function same(a, b) {
  if (Array.isArray(a) || Array.isArray(b)) return Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((x, i) => same(x, b[i]));
  if (isObject(a) && isObject(b)) return Object.keys(a).length === Object.keys(b).length && Object.keys(a).every((k) => Object.hasOwn(b, k) && same(a[k], b[k]));
  return a === b;
}

// The test cases of RFC 7396, Appendix A: original, patch and the result the RFC gives.
const CASES = [
  ['{"a":"b"}', '{"a":"c"}', '{"a":"c"}'],
  ['{"a":"b"}', '{"b":"c"}', '{"a":"b","b":"c"}'],
  ['{"a":"b"}', '{"a":null}', '{}'],
  ['{"a":"b","b":"c"}', '{"a":null}', '{"b":"c"}'],
  ['{"a":["b"]}', '{"a":"c"}', '{"a":"c"}'],
  ['{"a":"c"}', '{"a":["b"]}', '{"a":["b"]}'],
  ['{"a":{"b":"c"}}', '{"a":{"b":"d","c":null}}', '{"a":{"b":"d"}}'],
  ['{"a":[{"b":"c"}]}', '{"a":[1]}', '{"a":[1]}'],
  ['["a","b"]', '["c","d"]', '["c","d"]'],
  ['{"a":"b"}', '["c"]', '["c"]'],
  ['{"a":"foo"}', 'null', 'null'],
  ['{"a":"foo"}', '"bar"', '"bar"'],
  ['{"e":null}', '{"a":1}', '{"e":null,"a":1}'],
  ['[1,2]', '{"a":"b","c":null}', '{"a":"b"}'],
  ['{}', '{"a":{"bb":{"ccc":null}}}', '{"a":{"bb":{}}}'],
];
const right = CASES.filter(([o, p, r]) => same(mergePatch(JSON.parse(o), JSON.parse(p)), JSON.parse(r))).length;
console.log(`RFC 7396, Appendix A: ${right} of ${CASES.length} cases give the RFC's result`);

const profile = { name: 'Asha', nickname: 'Ash', emails: ['asha@example.com', 'asha.work@example.com'], theme: 'dark' };
const show = (doc) => JSON.stringify(doc);
console.log('change one member:  ', show(mergePatch(profile, { theme: 'light' })));
console.log('try to set null:    ', show(mergePatch(profile, { nickname: null })));
console.log('change one email:   ', show(mergePatch(profile, { emails: ['asha.home@example.com'] })));

RFC 7396, Appendix A: 15 of 15 cases give the RFC's result
change one member:   {"name":"Asha","nickname":"Ash","emails":["asha@example.com","asha.work@example.com"],"theme":"light"}
try to set null:     {"name":"Asha","emails":["asha@example.com","asha.work@example.com"],"theme":"dark"}
change one email:    {"name":"Asha","nickname":"Ash","emails":["asha.home@example.com"],"theme":"dark"}

Python · patch/diff.py

# From two versions of an order, make a JSON Patch and a Merge Patch, apply each to version 1, and check which one
# gives back version 2. Arrays are compared by position, the simplest diff that is always correct.
import json

from jsonpatch import apply_patch, json_equal

v1 = {"id": "BK-10042", "status": "paid", "note": "call before delivery",
      "items": [{"sku": "BK-101", "qty": 2}, {"sku": "BK-205", "qty": 1}]}
v2 = {"id": "BK-10042", "status": "shipped", "note": None, "tracking": "AWB-7781",
      "items": [{"sku": "BK-101", "qty": 3}, {"sku": "BK-205", "qty": 1}]}


def step(path, name):
    return f"{path}/{str(name).replace('~', '~0').replace('/', '~1')}"


def json_patch(a, b, path=""):
    if isinstance(a, dict) and isinstance(b, dict):
        ops = [{"op": "remove", "path": step(path, k)} for k in a if k not in b]
        for k in b:
            ops += json_patch(a[k], b[k], step(path, k)) if k in a else [{"op": "add", "path": step(path, k), "value": b[k]}]
        return ops
    if isinstance(a, list) and isinstance(b, list):
        common = min(len(a), len(b))
        ops = [op for i in range(common) for op in json_patch(a[i], b[i], step(path, i))]
        ops += [{"op": "remove", "path": step(path, i)} for i in range(len(a) - 1, common - 1, -1)]  # from the end
        return ops + [{"op": "add", "path": step(path, "-"), "value": v} for v in b[common:]]
    return [] if json_equal(a, b) else [{"op": "replace", "path": path, "value": b}]


def merge_patch_of(a, b):
    if not (isinstance(a, dict) and isinstance(b, dict)):
        return b
    patch = {k: None for k in a if k not in b}
    for k in b:
        if k not in a:
            patch[k] = b[k]
        elif not json_equal(a[k], b[k]):
            patch[k] = merge_patch_of(a[k], b[k])
    return patch


def merge_patch(target, patch):  # RFC 7396, as in the merge example
    if not isinstance(patch, dict):
        return patch
    result = dict(target) if isinstance(target, dict) else {}
    for name, value in patch.items():
        if value is None:
            result.pop(name, None)
        else:
            result[name] = merge_patch(result.get(name), value)
    return result


def text(doc):
    return json.dumps(doc, separators=(",", ":"))


ops = json_patch(v1, v2)
mp = merge_patch_of(v1, v2)
print(f"JSON Patch, {len(ops)} operations, {len(text(ops))} bytes:")
for op in ops:
    print("  " + text(op))
print(f"Merge Patch, {len(text(mp))} bytes:")
print("  " + text(mp))
print("JSON Patch gives version 2:", json_equal(apply_patch(v1, ops), v2))
merged = merge_patch(v1, mp)
print("Merge Patch gives version 2:", json_equal(merged, v2), "| note in the result:", "note" in merged)

JSON Patch, 4 operations, 198 bytes:
  {"op":"replace","path":"/status","value":"shipped"}
  {"op":"replace","path":"/note","value":null}
  {"op":"add","path":"/tracking","value":"AWB-7781"}
  {"op":"replace","path":"/items/0/qty","value":3}
Merge Patch, 114 bytes:
  {"status":"shipped","note":null,"tracking":"AWB-7781","items":[{"sku":"BK-101","qty":3},{"sku":"BK-205","qty":1}]}
JSON Patch gives version 2: True
Merge Patch gives version 2: False | note in the result: False

JavaScript · patch/diff.mjs

// From two versions of an order, make a JSON Patch and a Merge Patch, apply each to version 1, and check which one
// gives back version 2. Arrays are compared by position, the simplest diff that is always correct.
import { applyPatch, jsonEqual } from './jsonpatch.mjs';

const v1 = { id: 'BK-10042', status: 'paid', note: 'call before delivery',
  items: [{ sku: 'BK-101', qty: 2 }, { sku: 'BK-205', qty: 1 }] };
const v2 = { id: 'BK-10042', status: 'shipped', note: null, tracking: 'AWB-7781',
  items: [{ sku: 'BK-101', qty: 3 }, { sku: 'BK-205', qty: 1 }] };

const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
// A member is set as an own data property, so a name such as "__proto__" stays data and never becomes a prototype.
const setMember = (obj, name, value) => Object.defineProperty(obj, name, { value, writable: true, enumerable: true, configurable: true });
const step = (path, name) => `${path}/${String(name).replaceAll('~', '~0').replaceAll('/', '~1')}`;

function jsonPatch(a, b, path = '') {
  if (isObject(a) && isObject(b)) {
    const ops = Object.keys(a).filter((k) => !Object.hasOwn(b, k)).map((k) => ({ op: 'remove', path: step(path, k) }));
    for (const k of Object.keys(b)) {
      ops.push(...(Object.hasOwn(a, k) ? jsonPatch(a[k], b[k], step(path, k)) : [{ op: 'add', path: step(path, k), value: b[k] }]));
    }
    return ops;
  }
  if (Array.isArray(a) && Array.isArray(b)) {
    const common = Math.min(a.length, b.length);
    const ops = [];
    for (let i = 0; i < common; i++) ops.push(...jsonPatch(a[i], b[i], step(path, i)));
    for (let i = a.length - 1; i >= common; i--) ops.push({ op: 'remove', path: step(path, i) }); // from the end
    for (const v of b.slice(common)) ops.push({ op: 'add', path: step(path, '-'), value: v });
    return ops;
  }
  return jsonEqual(a, b) ? [] : [{ op: 'replace', path, value: b }];
}

function mergePatchOf(a, b) {
  if (!(isObject(a) && isObject(b))) return b;
  const patch = {};
  for (const k of Object.keys(a)) if (!Object.hasOwn(b, k)) setMember(patch, k, null);
  for (const k of Object.keys(b)) {
    if (!Object.hasOwn(a, k)) setMember(patch, k, b[k]);
    else if (!jsonEqual(a[k], b[k])) setMember(patch, k, mergePatchOf(a[k], b[k]));
  }
  return patch;
}

function mergePatch(target, patch) { // RFC 7396, as in the merge example
  if (!isObject(patch)) return patch;
  const result = isObject(target) ? { ...target } : {};
  for (const [name, value] of Object.entries(patch)) {
    if (value === null) delete result[name];
    else setMember(result, name, mergePatch(Object.hasOwn(result, name) ? result[name] : undefined, value));
  }
  return result;
}

const text = (doc) => JSON.stringify(doc);
const ops = jsonPatch(v1, v2);
const mp = mergePatchOf(v1, v2);
console.log(`JSON Patch, ${ops.length} operations, ${text(ops).length} bytes:`);
for (const op of ops) console.log(`  ${text(op)}`);
console.log(`Merge Patch, ${text(mp).length} bytes:`);
console.log(`  ${text(mp)}`);
console.log('JSON Patch gives version 2:', jsonEqual(applyPatch(v1, ops), v2));
const merged = mergePatch(v1, mp);
console.log('Merge Patch gives version 2:', jsonEqual(merged, v2), '| note in the result:', Object.hasOwn(merged, 'note'));

JSON Patch, 4 operations, 198 bytes:
  {"op":"replace","path":"/status","value":"shipped"}
  {"op":"replace","path":"/note","value":null}
  {"op":"add","path":"/tracking","value":"AWB-7781"}
  {"op":"replace","path":"/items/0/qty","value":3}
Merge Patch, 114 bytes:
  {"status":"shipped","note":null,"tracking":"AWB-7781","items":[{"sku":"BK-101","qty":3},{"sku":"BK-205","qty":1}]}
JSON Patch gives version 2: true
Merge Patch gives version 2: false | note in the result: false