Point users to update(…, true), JSON Pointer defaults, and built-in std::optional (#5804)

A code search of client code found many hand-written versions of
functionality the library already has: recursive object merges
(update(j, true) since 3.10.5), dotted-path getters (value() and
contains() with a JSON Pointer), get_or helpers (value() throws for a
member that is present but null), and adl_serializer specializations
for std::optional (supported since 3.12.0).

- modifying_values.md: describe both modes of update(), add a
  defaults + user settings recipe, and stop recommending Merge Patch
  for recursive merges.
- merge_patch.md: note that null deletes keys, so a merge patch is not
  a general deep merge; link update().
- default_value.md: add "Nested values" (value/contains with a JSON
  Pointer, building a pointer from a dotted path with operator/=) and
  a warning that null and mistyped members are not missing.
- value.md: note that a null member is converted, not replaced by the
  default.
- json_pointer.md: link value/contains/at with JSON Pointers.
- arbitrary_types.md: note that std::optional needs no serializer.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
This commit is contained in:
Niels Lohmann authored and GitHub committed 2026-10-11 08:22:10 +02:00
1 parent 74a03dec84
commit 11ef352511
6 files changed
+122 -6

No files matched your search

+8
View File
@@ -9,6 +9,13 @@ syntax that closely mimics the document being modified. Unlike [JSON Patch](json
express every kind of change (e.g., it cannot reorder array elements or remove a specific array element), but it is
easier to read and write for object-shaped documents.
!!! 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.
To merge two objects recursively (e.g., defaults and user settings), use
[`update`](../api/basic_json/update.md) with `merge_objects` set to `#!cpp true`; see
[Merging objects](modifying_values.md#merging-objects).
??? example
The following code shows how a JSON Merge Patch is applied to a JSON document.
@@ -28,3 +35,4 @@ easier to read and write for object-shaped documents.
- [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 [`update`](../api/basic_json/update.md) - merge objects, optionally recursively