JSON Patch

API Design

Meaning

JSON Patch (RFC 6902) is a JSON document format that describes a sequence of operations to apply to a target JSON document, transforming it into a new state. It addresses the problem of partially updating a resource without resending the entire payload, which saves bandwidth and avoids lost-update races on concurrent writes. Engineers reach for it when designing REST PATCH endpoints or when they need to express structured, atomic mutations over a network.

Primary Function

API design

Communicative Purpose

Enables partial, structured updates to JSON resources without resending the entire document.

Pattern

describe operations → apply patch to target document → produce updated document

Função primária

API design

Propósito comunicativo

Enables partial, structured updates to JSON resources without resending the entire document.

Situações de gatilho

REST API design: implementing PATCH endpoints for partial resource updates

Contextos

REST APIs, HTTP PATCH endpoints, microservices, configuration management, document databases

Padrão

describe operations → apply patch to target document → produce updated document

Colocados típicos

RFC 6902
HTTP PATCH method
JSON Merge Patch (RFC 7396)
JSON Pointer (RFC 6901)
Content-Type: application/json-patch+json

Substituições comuns

JSON Merge Patch (RFC 7396) — simpler merge-based format but cannot express array operations or conditional updates
full PUT replacement — simpler but wastes bandwidth and risks lost updates on concurrent writes

Erros comuns

Confusing JSON Patch with JSON Merge Patch: they use different operation semantics and content types

Similar / contraste

JSON Merge Patch (RFC 7396): simpler merge-based format, no array operations

Interferências

Coming from REST PUT-only APIs: may try to send full document replacement — JSON Patch enables partial updates with explicit operations

Família do chunk

JSON Merge Patch
JSON Pointer
HTTP PATCH method
RFC 6902

Nuance

When NOT to use: simple full-document replacements where PUT suffices, or when the client cannot reliably compute the diff

Efeito pragmático

Reduces bandwidth on partial updates, provides a standardized format that any client/server pair can implement interoperably, and enables atomic multi-operation updates that prevent inconsistent intermediate states.

Dica de memória

JSON Patch is like a surgical instruction list for a JSON document — each operation says exactly where to cut, what to add, and what to replace, applied in order.

Upgrade path

JSON Patch with JSON Pointer (RFC 6901) for addressing nested values, or JSON Patch Extensions for custom operations

Frequência: MediumFormulaicidade: FlexiblePrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

import jsonpatch original = { "name": "Alice", "email": "alice@example.com", "roles": ["admin", "user"] } patch = [ {"op": "replace", "path": "/email", "value": "alice.new@example.com"}, {"op": "add", "path": "/roles/2", "value": "auditor"} ] result = jsonpatch.apply_patch(original, patch) print(result)

import requests patch_doc = [ {"op": "replace", "path": "/status", "value": "active"}, {"op": "remove", "path": "/deprecated_field"} ] response = requests.patch( "https://api.example.com/users/42", json=patch_doc, headers={"Content-Type": "application/json-patch+json"} ) print(response.status_code)

import json def apply_patch(document, patch): for operation in patch: op = operation["op"] path = operation["path"].lstrip("/").split("/") if op == "test": current = document for key in path: current = current[int(key)] if key.isdigit() else current[key] assert current == operation["value"], f"Test failed at {operation['path']}" elif op == "replace": target = document for key in path[:-1]: target = target[int(key)] if key.isdigit() else target[key] target[path[-1]] = operation["value"] return document doc = {"version": 2, "data": [1, 2, 3]} patch = [ {"op": "test", "path": "/version", "value": 2}, {"op": "replace", "path": "/data/1", "value": 99} ] print(apply_patch(doc, patch))