JSON and data guides
JSON Patch vs Merge Patch: choose the update format
Apply ordered operations or merge an object patch, and understand null deletion and array replacement.
Operations or a merge document
JSON Patch is an ordered array of operations; Merge Patch is a document describing merged object fields. They are different protocols.
Choose JSON Patch when the update needs array positions or a precondition. Choose Merge Patch for simple object changes whose null semantics match your API.
Document: {"name":"Ada","active":true}
JSON Patch: [{"op":"replace","path":"/active","value":false}]
Merge Patch: {"active":false}Null deletes in Merge Patch
In Merge Patch, a null value removes an object member rather than assigning a JSON null. Arrays are replaced as complete values.
If your domain needs an explicit null value or surgical array edits, this format may not express the intended update. Test those cases before designing the endpoint.
{"name":"Ada","note":"x"} + {"note":null}
→ {"name":"Ada"}Escape JSON Pointer paths
Patch paths use JSON Pointer. In a property name, a slash becomes ~1 and a tilde becomes ~0; this is not URL percent encoding.
Array indexes refer to the current document after earlier operations. Adding or removing an element can change what a later index points to.
Property: a/b~c
Pointer: /a~1b~0cUse test for a precondition
A test operation checks a value before subsequent modifications. Failure must stop the patch; Nav Tools does not return a partially applied result.
A local test is not a replacement for server concurrency controls. Use an API version or ETag as appropriate and compare the resulting document.