JSON Patch

JSON Patch とは

JSON Patch (RFC 6902) は、JSON ドキュメントに対する部分更新操作を配列形式で記述する標準フォーマットである。HTTP PATCH メソッドと組み合わせて、リソースの一部だけを更新する REST API を実装する際に使われる。Content-Type は application/json-patch+json を指定する。

PUT がリソース全体の置換であるのに対し、PATCH + JSON Patch は「何をどう変更するか」を明示的に記述する。大きなリソースの一部だけを更新する場合、転送データ量が大幅に削減される。

6 つの操作

6 つの操作の例を示す。

[
  { "op": "add",     "path": "/tags/2",    "value": "urgent" },
  { "op": "remove",  "path": "/tags/0" },
  { "op": "replace", "path": "/status",    "value": "active" },
  { "op": "move",    "from": "/old_name",  "path": "/new_name" },
  { "op": "copy",    "from": "/template",  "path": "/config" },
  { "op": "test",    "path": "/version",   "value": 3 }
]

操作	説明	用途
add	値を追加 (配列の挿入、新フィールドの追加)	新しいタグの追加
remove	値を削除	不要なフィールドの削除
replace	値を置換	ステータスの更新
move	値を移動 (remove + add)	フィールド名の変更
copy	値をコピー	テンプレートからの複製
test	値が期待通りか検証 (楽観的ロック)	競合検出

test 操作による楽観的ロック

test 操作は JSON Patch の最も重要な機能だ。更新前に現在の値を検証し、他のクライアントが同時に変更していないことを確認する。

[
  { "op": "test",    "path": "/version", "value": 3 },
  { "op": "replace", "path": "/status",  "value": "shipped" },
  { "op": "replace", "path": "/version", "value": 4 }
]

version が 3 でなければ、パッチ全体が失敗する (409 Conflict)。DynamoDB の条件付き書き込みと同じ概念だ。

PUT vs PATCH vs JSON Patch

PUT と PATCH vs JSON Patch のコード例を比較する。

// PUT: リソース全体を置換 (全フィールドを送信)
PUT /orders/123
{ "id": "123", "status": "shipped", "items": [...], "address": {...}, "total": 5000 }

// PATCH + JSON Merge Patch: 変更フィールドだけ送信 (シンプル)
PATCH /orders/123
Content-Type: application/merge-patch+json
{ "status": "shipped" }

// PATCH + JSON Patch: 操作を明示的に記述 (高機能)
PATCH /orders/123
Content-Type: application/json-patch+json
[{ "op": "replace", "path": "/status", "value": "shipped" }]

方式	長所	短所
PUT	シンプル、べき等	全フィールド送信が必要
JSON Merge Patch	シンプル、直感的	配列操作が苦手、null で削除
JSON Patch	配列操作、test 操作、高精度	記述が冗長

JSON Patch が適するケース

• 大きなリソースの一部だけを更新する API
• 配列の特定要素を操作する必要がある場合
• 楽観的ロック (test 操作) が必要な場合
• 変更履歴を操作単位で記録したい場合

理論と実装の両面から学ぶなら関連書籍が参考になる。