deploy: a47170346a

features/merge_patch.md

@@ -12,6 +12,78 @@ easier to read and write for object-shaped documents.
 The function [`merge_diff`](../api/basic_json/merge_diff.md) creates a merge patch that changes one JSON value into
 another.
 
+The example below applies one patch to one document. Here is the document before:
+
+```json
+{
+    "title": "Goodbye!",
+    "author": {
+        "givenName": "John",
+        "familyName": "Doe"
+    },
+    "tags": ["example", "sample"],
+    "content": "This will be unchanged"
+}
+```
+
+This is the patch:
+
+```json
+{
+    "title": "Hello!",
+    "phoneNumber": "+01-123-456-7890",
+    "author": {
+        "familyName": null
+    },
+    "tags": ["example"]
+}
+```
+
+And this is the document after applying it:
+
+```json
+{
+    "title": "Hello!",
+    "author": {
+        "givenName": "John"
+    },
+    "tags": ["example"],
+    "content": "This will be unchanged",
+    "phoneNumber": "+01-123-456-7890"
+}
+```
+
+The table goes through the members one by one. "Member" is the name of an object member in the patch (and in the
+document); it is not a [JSON Pointer](json_pointer.md) and nothing of it is passed to the function: the whole patch is
+passed to [`merge_patch`](../api/basic_json/merge_patch.md).
+
+<div class="nj-pointer-mpt" markdown>
+
+| Rule | Member | Before | Patch | After |
+|------|--------|--------|-------|-------|
+| <span class="nj-pointer-mp nj-pointer-mp--set">change value</span> | `title` | `#!json "Goodbye!"` | `#!json "Hello!"` | `#!json "Hello!"` |
+| <span class="nj-pointer-mp nj-pointer-mp--add">add key</span> | `phoneNumber` | <span class="nj-pointer-mp-none">(no member)</span> | `#!json "+01-123-456-7890"` | `#!json "+01-123-456-7890"` |
+| <span class="nj-pointer-mp nj-pointer-mp--rec">object merges recursively</span> | `author` | `#!json {"givenName": "John", "familyName": "Doe"}` | `#!json {"familyName": null}` | `#!json {"givenName": "John"}` |
+| <span class="nj-pointer-mp nj-pointer-mp--del">null removes key</span> | `familyName` inside `author` | `#!json "Doe"` | `#!json null` | <span class="nj-pointer-mp-none">(removed)</span> |
+| <span class="nj-pointer-mp nj-pointer-mp--arr">array replaced whole</span> | `tags` | `#!json ["example", "sample"]` | `#!json ["example"]` | `#!json ["example"]` |
+| <span class="nj-pointer-mp nj-pointer-mp--keep">unchanged key</span> | `content` | `#!json "This will be unchanged"` | <span class="nj-pointer-mp-none">(no member)</span> | `#!json "This will be unchanged"` |
+
+</div>
+
+An array in the patch replaces the array in the target, so a merge patch cannot change a single element. Each member of
+the patch is applied like this; a patch that is not an object replaces the whole target.
+
+```mermaid
+flowchart LR
+    M["member of the patch"] --> N{{"value null?"}}
+    N -->|yes| D["delete the key"]
+    N -->|no| O{{"value an object?"}}
+    O -->|yes| R["merge recursively into the target's value"]
+    O -->|no| S["set the key to the value"]
+```
+
+<p class="nj-caption" markdown>How one member of a merge patch is applied: a `null` value deletes the key, an object is merged recursively, and any other value replaces the value of the key.</p>
+
 !!! tip "Not a general deep merge"
 
     A merge patch is not a general deep merge: a `#!json null` value in the patch deletes the key from the target.
@@ -101,6 +173,7 @@ another.
 
 - [JSON Patch and Diff](json_patch.md) - a more expressive alternative that describes a sequence of operations
 - [JSON Pointer](json_pointer.md) - the addressing scheme used by JSON Patch
-- Function [`merge_patch`](../api/basic_json/merge_patch.md)
-- Function [`merge_diff`](../api/basic_json/merge_diff.md)
+- [`merge_patch`](../api/basic_json/merge_patch.md) - apply a JSON Merge Patch to a value
+- [`merge_diff`](../api/basic_json/merge_diff.md) - create a JSON Merge Patch from two values
 - Function [`update`](../api/basic_json/update.md) - merge objects, optionally recursively
+- [Modifying values](modifying_values.md) - simple in-place modifications