Niels Lohmann
e9c3985f0a
* 📡 Fix documentation gaps found in a full GitHub Discussions review Reviewed all 1008 GitHub Discussions (2020-2026) for recurring questions that better or more visible documentation would have avoided. Adds/expands documentation for ~26 distinct gaps, including: - New "Debugging" page collecting natvis, GDB pretty printer, LLDB status, and JSON_DIAGNOSTICS pointers (previously scattered/undiscoverable) - Thread-safety and schema-validation FAQ entries - StringType's char-based requirement (no wstring/u16string/u32string) - Brace-initialization-yields-arrays warning directly on the constructor reference page (previously only in the FAQ, missed by users reading the constructor docs) - std::any exclusion from get<T>(), with a manual-dispatch example - Non-string-keyed std::map serializing as an array of pairs - ordered_json compatibility with NLOHMANN_DEFINE_TYPE_* macros (already worked, was undocumented) - std::array truncation on size-mismatched conversion (no exception) - static_cast vs. get<std::optional<T>>() divergence - Recipe for omitting a std::optional field instead of emitting null - No built-in nesting-depth limit during parsing + a callback-based workaround recipe - Recipe for streaming a large homogeneous array via parser callbacks - operator>> stream-position semantics for concatenated JSON values - JSON Pointer array-vs-object creation rule for non-existing paths - CMake target name (nlohmann_json_modules) needed to link C++20 modules - ESP-IDF/PlatformIO: no official package, link to a community fork - get(key, default) as the Python dict.get() equivalent - reserve() recipe for pre-allocating array capacity - JSONC as an alias for the existing ignore_comments/ignore_trailing_commas combination (distinct from the unsupported JSON5) - items() dereferenced-element type: decltype() idiom + detail-namespace stability caveat - Various macro/type-conversion limitations (MSGPACK_DEFINE_ARRAY equivalent, char-array round-tripping, ADL serializer macro gap) Signed-off-by: Niels Lohmann <mail@nlohmann.me> * 🚶 fix format Signed-off-by: Niels Lohmann <mail@nlohmann.me> --------- Signed-off-by: Niels Lohmann <mail@nlohmann.me>
4.4 KiB
JSON Pointer
Introduction
The library supports JSON Pointer (RFC 6901) as an alternative means to address structured values. A JSON Pointer is a string that identifies a specific value within a JSON document.
Consider the following JSON document
{
"array": ["A", "B", "C"],
"nested": {
"one": 1,
"two": 2,
"three": [true, false]
}
}
Then every value inside the JSON document can be identified as follows:
| JSON Pointer | JSON value |
|---|---|
| `` | #!json {"array":["A","B","C"],"nested":{"one":1,"two":2,"three":[true,false]}} |
/array |
#!json ["A","B","C"] |
/array/0 |
#!json A |
/array/1 |
#!json B |
/array/2 |
#!json C |
/nested |
#!json {"one":1,"two":2,"three":[true,false]} |
/nested/one |
#!json 1 |
/nested/two |
#!json 2 |
/nested/three |
#!json [true,false] |
/nested/three/0 |
#!json true |
/nested/three/1 |
#!json false |
Note / does not identify the root (i.e., the whole document), but an object entry with empty key "". See
RFC 6901 for more information.
JSON Pointer creation
JSON Pointers can be created from a string:
json::json_pointer p("/nested/one");
Furthermore, a user-defined string literal can be used to achieve the same result:
auto p = "/nested/one"_json_pointer;
The escaping rules of RFC 6901 are implemented. See the constructor documentation for more information.
Value access
JSON Pointers can be used in the at, operator[],
and value functions just like object keys or array indices.
// the JSON value from above
auto j = json::parse(R"({
"array": ["A", "B", "C"],
"nested": {
"one": 1,
"two": 2,
"three": [true, false]
}
})");
// access values
auto val = j[""_json_pointer]; // {"array":["A","B","C"],...}
auto val1 = j["/nested/one"_json_pointer]; // 1
auto val2 = j.at(json::json_pointer("/nested/three/1")); // false
auto val3 = j.value(json::json_pointer("/nested/four"), 0); // 0
!!! note "Creating intermediate levels that don't exist"
See the [`operator[]` notes](../api/basic_json/operator%5B%5D.md#return-value) for how array vs. object is
decided when a pointer creates intermediate levels that don't exist yet.
Flatten / unflatten
The library implements a function flatten to convert any JSON document into a JSON
object where each key is a JSON Pointer and each value is a primitive JSON value (i.e., a string, boolean, number, or
null).
// the JSON value from above
auto j = json::parse(R"({
"array": ["A", "B", "C"],
"nested": {
"one": 1,
"two": 2,
"three": [true, false]
}
})");
// create flattened value
auto j_flat = j.flatten();
The resulting value j_flat is:
{
"/array/0": "A",
"/array/1": "B",
"/array/2": "C",
"/nested/one": 1,
"/nested/two": 2,
"/nested/three/0": true,
"/nested/three/1": false
}
The reverse function, unflatten recreates the original value.
auto j_original = j_flat.unflatten();
See also
- Class
json_pointer - Function
flatten - Function
unflatten - JSON Patch