2026-08-27 · 6 min read · Rahul Chitturi
- json
- api
- debugging
A JSON Patch operation can be syntactically valid and still update the wrong array element. Paths such as /items/2 target a position, not the business identity of the item currently occupying that position.
The failure often appears when a client builds a patch from stale state while another request inserts, removes, or reorders the array. Replaying the old index against the new document then changes a different record without producing a parse error.
Reconstruct the exact base document
Keep a sanitized copy of the document version used to create the patch, the patch operations in order, and the server document that received them. Format each value before comparing paths and array contents.
- Check whether an earlier remove operation shifted later indexes
- Compare the document version or ETag at read and write time
- Confirm move and copy paths are evaluated in the expected order
- Identify each array member by a stable ID rather than display position
Protect patches from stale state
Use conditional updates such as If-Match with an ETag or include a version test operation before mutations. Rejecting a stale patch is safer than guessing how old indexes map onto current data.
For frequently edited collections, an endpoint addressed by item ID may be clearer than positional JSON Patch. If order itself is the resource, model ordering and conflict behavior explicitly.
A Flashman workflow
Use the JSON formatter to inspect the base document and patch, the diff tool to compare versions, the UUID generator for synthetic stable IDs, and the timestamp converter to order concurrent requests.
Turn the incident into a regression case with the original operation sequence and an intentional concurrent insert. The expected result should be either a safe conflict or the correct identified item.