starred/json
1
0 Fork 0
mirror of https://github.com/nlohmann/json.git synced 2026-11-15 11:58:21 +00:00
Code Issues Packages Projects Releases 10 Wiki Activity
Files
b38131ec40acf69eb3be4d57a51e0a1e051a66ad
json/docs/mkdocs/mkdocs.yml
T
Niels Lohmann b38131ec40 Add JSON_RECURSION_DEPTH_LIMIT to set how deep value walks recurse 
Copying, comparing, serializing, hashing, merging, diffing, converting and
destroying a value, and the CBOR, MessagePack, UBJSON, BJData and BON8 writers
recurse a fixed number of nesting levels on the call stack and finish deeper
levels with an explicit stack (#5387). The number was hard-coded to 128. That is
too much for small stacks: a 128-level dump() needs about 288 KiB at -O0 with
Clang (2.3 KiB per level; 256 KiB with GCC) and crashed in a thread with a
256 KiB stack, and musl threads have 128 KiB by default. Others may want the
opposite.

The macro JSON_RECURSION_DEPTH_LIMIT, defined before including the library,
sets the number; the default stays 128. The value must be an integer constant
from 0 to 254 (not a floating-point number or bool), otherwise a static_assert
names the macro. 254 is the largest value because the copy constructor and the
comparison operators cannot pass a depth down and count it in a byte per thread
(nesting_depth()). The guard that counts now counts only the levels it enters,
so the count never exceeds the limit. It used to count the level that finds the
limit reached as well, which made the count 255 at limit 254: a copy made by a
custom base class while a copy was going on then wrapped the byte to 0 and
recursed another 254 levels (twice the stack).

0 is allowed: every walk then uses its explicit stack from the first level on
and needs a constant amount of stack (16 KiB or less at
-O0 with Clang and GCC, for a value nested 20,000 levels deep). All uses of the
limit compare a depth with it; none computes limit - 1 or limit + 1, and no
walk has a constant 128 of its own.

The macro changes only stack use and speed, never a result. Like
JSON_NO_THREAD_LOCAL it is not part of the ABI tag and must be the same in all
translation units (ODR); the page of the macro says what happens otherwise.

Supporting a limit of 0 needed one fix: update() without merge_objects reached
the explicit-stack merge at depth 0, which always merges objects. update_members
now takes that path only with merge_objects, which is the only case in which it
recurses at all.

Measurements (macOS arm64, Apple clang 21 and g++ 16, documented in the macro
page with a table per operation and optimization level, and a program to
reproduce them): the stack needed at the default of 128 levels is up to 288 KiB
(dump at -O0, Clang), 224 KiB (copy), and 48 KiB or less at -O2; at 254 levels
up to 576 KiB at -O0 and 112 KiB at -O2. Speed at -O2 relative to the default:
ordinary documents (nested 2 to 10 levels) are 1.1 to 2.4 times as slow with a
limit of 0 or 1 and unchanged (within about 0.1) with 16 or 254; values nested
1,000 or 100,000 levels deep show no difference for any limit. The default
build does the same work as before: the instructions retired for copy and conversion
(the walks whose guard changed; net of loading, canada, citm, twitter, jeopardy
and deep values), ==, dump and hash differ from the base by at most 0.02 % for copy
and 0.71 % in either direction for the others (noise), and the cycles for copy
by at most 0.65 %.

Tests: the existing tests that depended on 128 (comparison, allocator, custom
base class, diagnostics, binary writers, patch, merge_diff, conversions, custom
array type) derive their depths from the limit, and two assumed a limit of at
least 1 (limit - 1 wrapped around). tests/src/unit-recursion_depth_limit.cpp
checks that the macro is honoured (the array type of a value counts the levels
that a copy and a comparison descend) and that all walks return the same results
for values nested 1 to 300 levels deep as arrays, objects and both, against
expected strings and bytes built independently of the library; CMake builds it
with limits 0, 1 and 254 besides the default, and the CI target
ci_test_recursion_depth_limit_0 runs the whole suite with a limit of 0. A test
with a base class that copies the value from its copy constructor covers the
wrap-around at 254. The new test does not compile against the
previous header with -DJSON_RECURSION_DEPTH_LIMIT=1.

Docs: new macro page (range, stack and speed tables, small-stack guidance, ODR),
index, nav, macro overview, "Nesting depth" of the untrusted-input page (which
claimed that no walk could exhaust the stack however deep a value is nested; the
default assumes a stack of a few hundred KiB), the assurance case, and the page
of JSON_NO_THREAD_LOCAL.

No breaking changes: the default is unchanged, and the macro is new.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>
2026-11-11 18:32:55 +01:00

666 lines
31 KiB
YAML
Raw Blame History

# Project information
site_name: JSON for Modern C++
site_description: JSON for Modern C++ is a header-only C++11 library that makes JSON a first-class data type.
site_author: Niels Lohmann
site_url: https://json.nlohmann.me/
# Repository
repo_name: nlohmann/json
repo_url: https://github.com/nlohmann/json
edit_uri: edit/develop/docs/mkdocs/docs
# Copyright
copyright: Copyright &copy; 2013-2026 Niels Lohmann
# Configuration
theme:
name: material
custom_dir: overrides
language: en
palette:
- media: '(prefers-color-scheme: light)'
scheme: default
primary: custom
accent: custom
toggle:
icon: material/brightness-7
name: Switch to dark mode
- media: '(prefers-color-scheme: dark)'
scheme: slate
primary: custom
accent: custom
toggle:
icon: material/brightness-4
name: Switch to light mode
icon:
repo: fontawesome/brands/github
font: false
logo: images/wordmark-header.svg
features:
- navigation.instant
- navigation.tracking
- navigation.tabs
- navigation.indexes
- navigation.top
- navigation.footer
- toc.follow
- search.suggest
- search.highlight
- content.code.copy
- content.tabs.link
- content.action.edit
- content.action.view
nav:
- Home:
- index.md
- home/license.md
- "FAQ": home/faq.md
- home/exceptions.md
- Releases:
- 'Overview': home/releases/index.md
- 'Unreleased': home/releases/unreleased.md
- 'v3.12.0': home/releases/v3.12.0.md
- 'v3.11.3': home/releases/v3.11.3.md
- 'v3.11.2': home/releases/v3.11.2.md
- 'v3.11.1': home/releases/v3.11.1.md
- 'v3.11.0': home/releases/v3.11.0.md
- 'v3.10.5': home/releases/v3.10.5.md
- 'v3.10.4': home/releases/v3.10.4.md
- 'v3.10.3': home/releases/v3.10.3.md
- 'v3.10.2': home/releases/v3.10.2.md
- 'v3.10.1': home/releases/v3.10.1.md
- 'v3.10.0': home/releases/v3.10.0.md
- 'v3.9.1': home/releases/v3.9.1.md
- 'v3.9.0': home/releases/v3.9.0.md
- 'v3.8.0': home/releases/v3.8.0.md
- 'v3.7.3': home/releases/v3.7.3.md
- 'v3.7.2': home/releases/v3.7.2.md
- 'v3.7.1': home/releases/v3.7.1.md
- 'v3.7.0': home/releases/v3.7.0.md
- 'v3.6.1': home/releases/v3.6.1.md
- 'v3.6.0': home/releases/v3.6.0.md
- 'v3.5.0': home/releases/v3.5.0.md
- 'v3.4.0': home/releases/v3.4.0.md
- 'v3.3.0': home/releases/v3.3.0.md
- 'v3.2.0': home/releases/v3.2.0.md
- 'v3.1.2': home/releases/v3.1.2.md
- 'v3.1.1': home/releases/v3.1.1.md
- 'v3.1.0': home/releases/v3.1.0.md
- 'v3.0.1': home/releases/v3.0.1.md
- 'v3.0.0': home/releases/v3.0.0.md
- 'v2.1.1': home/releases/v2.1.1.md
- 'v2.1.0': home/releases/v2.1.0.md
- 'v2.0.10': home/releases/v2.0.10.md
- 'v2.0.9': home/releases/v2.0.9.md
- 'v2.0.8': home/releases/v2.0.8.md
- 'v2.0.7': home/releases/v2.0.7.md
- 'v2.0.6': home/releases/v2.0.6.md
- 'v2.0.5': home/releases/v2.0.5.md
- 'v2.0.4': home/releases/v2.0.4.md
- 'v2.0.3': home/releases/v2.0.3.md
- 'v2.0.2': home/releases/v2.0.2.md
- 'v2.0.1': home/releases/v2.0.1.md
- 'v2.0.0': home/releases/v2.0.0.md
- 'v1.1.0': home/releases/v1.1.0.md
- 'v1.0.0': home/releases/v1.0.0.md
- Blog:
- 'How 3.13.0 got faster': home/blog/how_3_13_0_got_faster.md
- home/design_goals.md
- home/architecture.md
- home/customers.md
- home/sponsors.md
- home/debugging.md
- Features:
- features/index.md
- features/arbitrary_types.md
- features/type_recipes.md
- Binary Formats:
- features/binary_formats/index.md
- features/binary_formats/bjdata.md
- features/binary_formats/bon8.md
- features/binary_formats/bson.md
- features/binary_formats/cbor.md
- features/binary_formats/messagepack.md
- features/binary_formats/ubjson.md
- features/binary_values.md
- features/comments.md
- features/conversions.md
- features/creating_values.md
- Element Access:
- features/element_access/index.md
- features/element_access/unchecked_access.md
- features/element_access/checked_access.md
- features/element_access/default_value.md
- features/files.md
- features/iterators.md
- features/merge_patch.md
- features/json_patch.md
- features/json_pointer.md
- features/modifying_values.md
- features/modules.md
- 'nlohmann Namespace': features/namespace.md
- features/no_exceptions.md
- features/object_order.md
- features/performance.md
- Parsing:
- features/parsing/index.md
- features/parsing/json_lines.md
- features/parsing/large_and_partial_input.md
- features/parsing/parse_exceptions.md
- features/parsing/parser_callbacks.md
- features/parsing/sax_interface.md
- features/parsing/untrusted_input.md
- features/assertions.md
- features/serialization.md
- features/enum_conversion.md
- features/macros.md
- features/trailing_commas.md
- Types:
- features/types/index.md
- features/types/number_handling.md
- features/types/template_parameters.md
- Zero-copy views:
- features/json_view/index.md
- features/json_view/lifetime.md
- features/json_view/differences.md
- features/json_view/reading.md
- features/json_view/generic_code.md
- features/json_view/editing.md
- features/json_view/images.md
- Integration:
- integration/index.md
- integration/migration_guide.md
- integration/cmake.md
- integration/package_managers.md
- integration/pkg-config.md
- integration/compile_times.md
- API Documentation:
- basic_json:
- 'Overview': api/basic_json/index.md
- '(Constructor)': api/basic_json/basic_json.md
- '(Destructor)': api/basic_json/~basic_json.md
- 'accept': api/basic_json/accept.md
- 'array': api/basic_json/array.md
- 'array_t': api/basic_json/array_t.md
- 'as_base_class': api/basic_json/as_base_class.md
- 'at': api/basic_json/at.md
- 'back': api/basic_json/back.md
- 'begin': api/basic_json/begin.md
- 'binary': api/basic_json/binary.md
- 'binary_t': api/basic_json/binary_t.md
- 'bjdata_version_t': api/basic_json/bjdata_version_t.md
- 'boolean_t': api/basic_json/boolean_t.md
- 'cbegin': api/basic_json/cbegin.md
- 'cbor_tag_handler_t': api/basic_json/cbor_tag_handler_t.md
- 'cend': api/basic_json/cend.md
- 'clear': api/basic_json/clear.md
- 'contains': api/basic_json/contains.md
- 'count': api/basic_json/count.md
- 'crbegin': api/basic_json/crbegin.md
- 'crend': api/basic_json/crend.md
- 'default_object_comparator_t': api/basic_json/default_object_comparator_t.md
- 'diff': api/basic_json/diff.md
- 'dump': api/basic_json/dump.md
- 'emplace': api/basic_json/emplace.md
- 'emplace_back': api/basic_json/emplace_back.md
- 'empty': api/basic_json/empty.md
- 'end': api/basic_json/end.md
- 'end_pos': api/basic_json/end_pos.md
- 'erase': api/basic_json/erase.md
- 'error_handler_t': api/basic_json/error_handler_t.md
- 'exception': api/basic_json/exception.md
- 'find': api/basic_json/find.md
- 'flatten': api/basic_json/flatten.md
- 'format_as': api/basic_json/format_as.md
- 'from_bjdata': api/basic_json/from_bjdata.md
- 'from_bon8': api/basic_json/from_bon8.md
- 'from_bson': api/basic_json/from_bson.md
- 'from_cbor': api/basic_json/from_cbor.md
- 'from_msgpack': api/basic_json/from_msgpack.md
- 'from_ubjson': api/basic_json/from_ubjson.md
- 'front': api/basic_json/front.md
- 'get': api/basic_json/get.md
- 'get_allocator': api/basic_json/get_allocator.md
- 'get_binary': api/basic_json/get_binary.md
- 'get_ptr': api/basic_json/get_ptr.md
- 'get_ref': api/basic_json/get_ref.md
- 'get_to': api/basic_json/get_to.md
- 'std::formatter&lt;basic_json&gt;': api/basic_json/std_formatter.md
- 'std::hash&lt;basic_json&gt;': api/basic_json/std_hash.md
- 'input_format_t': api/basic_json/input_format_t.md
- 'insert': api/basic_json/insert.md
- 'invalid_iterator': api/basic_json/invalid_iterator.md
- 'is_array': api/basic_json/is_array.md
- 'is_binary': api/basic_json/is_binary.md
- 'is_boolean': api/basic_json/is_boolean.md
- 'is_discarded': api/basic_json/is_discarded.md
- 'is_null': api/basic_json/is_null.md
- 'is_number': api/basic_json/is_number.md
- 'is_number_float': api/basic_json/is_number_float.md
- 'is_number_integer': api/basic_json/is_number_integer.md
- 'is_number_unsigned': api/basic_json/is_number_unsigned.md
- 'is_object': api/basic_json/is_object.md
- 'is_primitive': api/basic_json/is_primitive.md
- 'is_string': api/basic_json/is_string.md
- 'is_structured': api/basic_json/is_structured.md
- 'items': api/basic_json/items.md
- 'json_base_class_t': api/basic_json/json_base_class_t.md
- 'json_serializer': api/basic_json/json_serializer.md
- 'max_size': api/basic_json/max_size.md
- 'meta': api/basic_json/meta.md
- 'merge_diff': api/basic_json/merge_diff.md
- 'merge_patch': api/basic_json/merge_patch.md
- 'number_float_t': api/basic_json/number_float_t.md
- 'number_integer_t': api/basic_json/number_integer_t.md
- 'number_unsigned_t': api/basic_json/number_unsigned_t.md
- 'object': api/basic_json/object.md
- 'object_comparator_t': api/basic_json/object_comparator_t.md
- 'object_t': api/basic_json/object_t.md
- 'operator ValueType': api/basic_json/operator_ValueType.md
- 'operator value_t': api/basic_json/operator_value_t.md
- 'operator[]': api/basic_json/operator[].md
- 'operator=': api/basic_json/operator=.md
- 'operator+=': api/basic_json/operator+=.md
- 'operator==': api/basic_json/operator_eq.md
- 'operator!=': api/basic_json/operator_ne.md
- 'operator<': api/basic_json/operator_lt.md
- 'operator>': api/basic_json/operator_gt.md
- 'operator<=': api/basic_json/operator_le.md
- 'operator>=': api/basic_json/operator_ge.md
- 'operator<=>': api/basic_json/operator_spaceship.md
- 'out_of_range': api/basic_json/out_of_range.md
- 'other_error': api/basic_json/other_error.md
- 'parse': api/basic_json/parse.md
- 'parse_error': api/basic_json/parse_error.md
- 'parse_event_t': api/basic_json/parse_event_t.md
- 'parser_callback_t': api/basic_json/parser_callback_t.md
- 'patch': api/basic_json/patch.md
- 'patch_inplace': api/basic_json/patch_inplace.md
- 'push_back': api/basic_json/push_back.md
- 'rbegin': api/basic_json/rbegin.md
- 'rend': api/basic_json/rend.md
- 'sax_parse': api/basic_json/sax_parse.md
- 'size': api/basic_json/size.md
- 'start_pos': api/basic_json/start_pos.md
- 'string_t': api/basic_json/string_t.md
- 'swap': api/basic_json/swap.md
- 'std::swap&lt;basic_json&gt;': api/basic_json/std_swap.md
- 'to_bjdata': api/basic_json/to_bjdata.md
- 'to_bon8': api/basic_json/to_bon8.md
- 'to_bson': api/basic_json/to_bson.md
- 'to_cbor': api/basic_json/to_cbor.md
- 'to_msgpack': api/basic_json/to_msgpack.md
- 'to_string': api/basic_json/to_string.md
- 'to_ubjson': api/basic_json/to_ubjson.md
- 'type': api/basic_json/type.md
- 'type_error': api/basic_json/type_error.md
- 'type_name': api/basic_json/type_name.md
- 'unflatten': api/basic_json/unflatten.md
- 'update': api/basic_json/update.md
- 'value': api/basic_json/value.md
- 'value_t': api/basic_json/value_t.md
- 'with_t': api/basic_json/with_t.md
- basic_json_document:
- 'Overview': api/basic_json_document/index.md
- '(Constructor)': api/basic_json_document/basic_json_document.md
- 'accept': api/basic_json_document/accept.md
- 'erase': api/basic_json_document/erase.md
- 'insert': api/basic_json_document/insert.md
- 'is_discarded': api/basic_json_document/is_discarded.md
- 'load': api/basic_json_document/load.md
- 'memory_usage': api/basic_json_document/memory_usage.md
- 'node_count': api/basic_json_document/node_count.md
- 'owns_source': api/basic_json_document/owns_source.md
- 'parse': api/basic_json_document/parse.md
- 'parse_copy': api/basic_json_document/parse_copy.md
- 'push_back': api/basic_json_document/push_back.md
- 'read': api/basic_json_document/read.md
- 'root': api/basic_json_document/root.md
- 'save': api/basic_json_document/save.md
- 'set': api/basic_json_document/set.md
- 'shrink_to_fit': api/basic_json_document/shrink_to_fit.md
- 'source': api/basic_json_document/source.md
- basic_json_view:
- 'Overview': api/basic_json_view/index.md
- '(Constructor)': api/basic_json_view/basic_json_view.md
- 'at': api/basic_json_view/at.md
- 'back': api/basic_json_view/back.md
- 'begin': api/basic_json_view/begin.md
- 'cbegin': api/basic_json_view/cbegin.md
- 'cend': api/basic_json_view/cend.md
- 'contains': api/basic_json_view/contains.md
- 'count': api/basic_json_view/count.md
- 'dump': api/basic_json_view/dump.md
- 'empty': api/basic_json_view/empty.md
- 'end': api/basic_json_view/end.md
- 'find': api/basic_json_view/find.md
- 'front': api/basic_json_view/front.md
- 'get': api/basic_json_view/get.md
- 'get_string': api/basic_json_view/get_string.md
- 'get_to': api/basic_json_view/get_to.md
- 'is_array': api/basic_json_view/is_array.md
- 'is_binary': api/basic_json_view/is_binary.md
- 'is_boolean': api/basic_json_view/is_boolean.md
- 'is_discarded': api/basic_json_view/is_discarded.md
- 'is_null': api/basic_json_view/is_null.md
- 'is_number': api/basic_json_view/is_number.md
- 'is_number_float': api/basic_json_view/is_number_float.md
- 'is_number_integer': api/basic_json_view/is_number_integer.md
- 'is_number_unsigned': api/basic_json_view/is_number_unsigned.md
- 'is_object': api/basic_json_view/is_object.md
- 'is_primitive': api/basic_json_view/is_primitive.md
- 'is_string': api/basic_json_view/is_string.md
- 'is_structured': api/basic_json_view/is_structured.md
- 'items': api/basic_json_view/items.md
- 'materialize': api/basic_json_view/materialize.md
- 'number_format': api/basic_json_view/number_format.md
- 'number_token': api/basic_json_view/number_token.md
- 'operator<<': api/basic_json_view/operator_ltlt.md
- 'operator[]': api/basic_json_view/operator[].md
- 'operator==': api/basic_json_view/operator_eq.md
- 'operator!=': api/basic_json_view/operator_ne.md
- 'size': api/basic_json_view/size.md
- 'source_offset': api/basic_json_view/source_offset.md
- 'type': api/basic_json_view/type.md
- 'type_name': api/basic_json_view/type_name.md
- 'value': api/basic_json_view/value.md
- byte_container_with_subtype:
- 'Overview': api/byte_container_with_subtype/index.md
- '(constructor)': api/byte_container_with_subtype/byte_container_with_subtype.md
- 'clear_subtype': api/byte_container_with_subtype/clear_subtype.md
- 'has_subtype': api/byte_container_with_subtype/has_subtype.md
- 'operator==': api/byte_container_with_subtype/operator_eq.md
- 'operator!=': api/byte_container_with_subtype/operator_ne.md
- 'set_subtype': api/byte_container_with_subtype/set_subtype.md
- 'subtype': api/byte_container_with_subtype/subtype.md
- adl_serializer:
- 'Overview': api/adl_serializer/index.md
- 'from_json': api/adl_serializer/from_json.md
- 'to_json': api/adl_serializer/to_json.md
- 'is_json_view': api/is_json_view.md
- 'json': api/json.md
- 'json_document': api/json_document.md
- 'json_editable_document': api/json_editable_document.md
- 'json_editable_view': api/json_editable_view.md
- json_pointer:
- 'Overview': api/json_pointer/index.md
- '(Constructor)': api/json_pointer/json_pointer.md
- 'back': api/json_pointer/back.md
- 'empty': api/json_pointer/empty.md
- 'front': api/json_pointer/front.md
- 'operator string_t': api/json_pointer/operator_string_t.md
- 'operator==': api/json_pointer/operator_eq.md
- 'operator!=': api/json_pointer/operator_ne.md
- 'operator<=>': api/json_pointer/operator_spaceship.md
- 'operator/': api/json_pointer/operator_slash.md
- 'operator/=': api/json_pointer/operator_slasheq.md
- 'parent_pointer': api/json_pointer/parent_pointer.md
- 'pop_back': api/json_pointer/pop_back.md
- 'pop_front': api/json_pointer/pop_front.md
- 'push_back': api/json_pointer/push_back.md
- 'push_front': api/json_pointer/push_front.md
- 'string_t': api/json_pointer/string_t.md
- 'to_string': api/json_pointer/to_string.md
- json_sax:
- 'Overview': api/json_sax/index.md
- 'binary': api/json_sax/binary.md
- 'boolean': api/json_sax/boolean.md
- 'end_array': api/json_sax/end_array.md
- 'end_object': api/json_sax/end_object.md
- 'key': api/json_sax/key.md
- 'null': api/json_sax/null.md
- 'number_float': api/json_sax/number_float.md
- 'number_integer': api/json_sax/number_integer.md
- 'number_unsigned': api/json_sax/number_unsigned.md
- 'parse_error': api/json_sax/parse_error.md
- 'start_array': api/json_sax/start_array.md
- 'start_object': api/json_sax/start_object.md
- 'string': api/json_sax/string.md
- 'json_view': api/json_view.md
- 'operator<<(basic_json), operator<<(json_pointer)': api/operator_ltlt.md
- 'operator>>(basic_json)': api/operator_gtgt.md
- 'operator""_json': api/operator_literal_json.md
- 'operator""_json_pointer': api/operator_literal_json_pointer.md
- 'ordered_json': api/ordered_json.md
- 'ordered_json_document': api/ordered_json_document.md
- 'ordered_json_editable_document': api/ordered_json_editable_document.md
- 'ordered_json_editable_view': api/ordered_json_editable_view.md
- 'ordered_json_view': api/ordered_json_view.md
- 'ordered_map': api/ordered_map.md
- 'view_mode': api/view_mode.md
- macros:
- 'Overview': api/macros/index.md
- 'JSON_ASSERT': api/macros/json_assert.md
- 'JSON_BRACE_INIT_COPY_SEMANTICS': api/macros/json_brace_init_copy_semantics.md
- 'JSON_CATCH_USER, JSON_THROW_USER, JSON_TRY_USER': api/macros/json_throw_user.md
- 'JSON_DIAGNOSTICS': api/macros/json_diagnostics.md
- 'JSON_DELETE_DEPRECATED_FUNCTIONS': api/macros/json_delete_deprecated_functions.md
- 'JSON_DIAGNOSTIC_POSITIONS': api/macros/json_diagnostic_positions.md
- 'JSON_DISABLE_ENUM_SERIALIZATION': api/macros/json_disable_enum_serialization.md
- 'JSON_DISABLE_STREAM_BULK_SCAN': api/macros/json_disable_stream_bulk_scan.md
- 'JSON_DISABLE_TUPLE_REFERENCE_CONVERSION': api/macros/json_disable_tuple_reference_conversion.md
- 'JSON_DISABLE_UNLOCKED_FILE_IO': api/macros/json_disable_unlocked_file_io.md
- 'JSON_HAS_CPP_11, JSON_HAS_CPP_14, JSON_HAS_CPP_17, JSON_HAS_CPP_20, JSON_HAS_CPP_23, JSON_HAS_CPP_26': api/macros/json_has_cpp_11.md
- 'JSON_HAS_EXPERIMENTAL_FILESYSTEM, JSON_HAS_FILESYSTEM': api/macros/json_has_filesystem.md
- 'JSON_HAS_RANGE_VIEW_CONVERSION': api/macros/json_has_range_view_conversion.md
- 'JSON_HAS_RANGES': api/macros/json_has_ranges.md
- 'JSON_HAS_STATIC_RTTI': api/macros/json_has_static_rtti.md
- 'JSON_HAS_STD_FORMAT': api/macros/json_has_std_format.md
- 'JSON_HAS_THREE_WAY_COMPARISON': api/macros/json_has_three_way_comparison.md
- 'JSON_NO_AUTOMATIC_UDLS': api/macros/json_no_automatic_udls.md
- 'JSON_NOEXCEPTION': api/macros/json_noexception.md
- 'JSON_NO_IO': api/macros/json_no_io.md
- 'JSON_NO_SIMD': api/macros/json_no_simd.md
- 'JSON_NO_THREAD_LOCAL': api/macros/json_no_thread_local.md
- 'JSON_PRECISE_STREAM_POSITION': api/macros/json_precise_stream_position.md
- 'JSON_RECURSION_DEPTH_LIMIT': api/macros/json_recursion_depth_limit.md
- 'JSON_SKIP_LIBRARY_VERSION_CHECK': api/macros/json_skip_library_version_check.md
- 'JSON_SKIP_UNSUPPORTED_COMPILER_CHECK': api/macros/json_skip_unsupported_compiler_check.md
- 'JSON_STRICT_BINARY_UTF8': api/macros/json_strict_binary_utf8.md
- 'JSON_STRICT_NUL_HANDLING': api/macros/json_strict_nul_handling.md
- 'JSON_USE_GLOBAL_UDLS': api/macros/json_use_global_udls.md
- 'JSON_USE_IMPLICIT_CONVERSIONS': api/macros/json_use_implicit_conversions.md
- 'JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON': api/macros/json_use_legacy_discarded_value_comparison.md
- 'JSON_USE_OBJECTS_FOR_ENUM_KEYED_MAPS': api/macros/json_use_objects_for_enum_keyed_maps.md
- 'JSON_USE_SIMDUTF': api/macros/json_use_simdutf.md
- 'NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE': api/macros/nlohmann_define_derived_type.md
- 'NLOHMANN_DEFINE_TYPE_INTRUSIVE, NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE': api/macros/nlohmann_define_type_intrusive.md
- 'NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE': api/macros/nlohmann_define_type_non_intrusive.md
- 'NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_WITH_DEFAULT_WITH_NAMES, NLOHMANN_DEFINE_DERIVED_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE_WITH_NAMES': api/macros/nlohmann_define_type_with_names.md
- 'NLOHMANN_JSON_NAMESPACE': api/macros/nlohmann_json_namespace.md
- 'NLOHMANN_JSON_NAMESPACE_BEGIN, NLOHMANN_JSON_NAMESPACE_END': api/macros/nlohmann_json_namespace_begin.md
- 'NLOHMANN_JSON_NAMESPACE_NO_VERSION': api/macros/nlohmann_json_namespace_no_version.md
- 'NLOHMANN_JSON_SERIALIZE_ENUM': api/macros/nlohmann_json_serialize_enum.md
- 'NLOHMANN_JSON_SERIALIZE_ENUM_STRICT': api/macros/nlohmann_json_serialize_enum_strict.md
- 'NLOHMANN_JSON_VERSION_MAJOR, NLOHMANN_JSON_VERSION_MINOR, NLOHMANN_JSON_VERSION_PATCH': api/macros/nlohmann_json_version_major.md
- Community:
- community/index.md
- community/ecosystem.md
- "Code of Conduct": community/code_of_conduct.md
- community/contribution_guidelines.md
- community/quality_assurance.md
- community/governance.md
- community/roadmap.md
- community/security_policy.md
- community/assurance_case.md
# Extras
extra:
social:
- icon: fontawesome/brands/github
link: https://github.com/nlohmann
- icon: fontawesome/brands/linkedin
link: https://www.linkedin.com/in/nielslohmann/
- icon: fontawesome/brands/xing
link: https://www.xing.com/profile/Niels_Lohmann
- icon: fontawesome/brands/paypal
link: https://www.paypal.me/nlohmann
generator: false
# Extensions
markdown_extensions:
- abbr
- admonition
- attr_list
- def_list
- codehilite:
guess_lang: false
- toc:
permalink: true
- md_in_html
- pymdownx.betterem:
smart_enable: all
- pymdownx.caret
- pymdownx.critic
- pymdownx.details
- pymdownx.emoji:
emoji_index: !!python/name:material.extensions.emoji.twemoji
emoji_generator: !!python/name:material.extensions.emoji.to_svg
- pymdownx.inlinehilite
- pymdownx.magiclink
- pymdownx.mark
#- pymdownx.smartsymbols
- pymdownx.superfences:
custom_fences:
- name: mermaid
class: mermaid
format: !!python/name:pymdownx.superfences.fence_code_format
- pymdownx.tasklist:
custom_checkbox: true
- pymdownx.tabbed:
alternate_style: true
- pymdownx.tilde
- pymdownx.snippets:
base_path: docs
check_paths: true
restrict_base_path: false # needed to allow including files from the .github folder
auto_append:
- ../includes/glossary.md
# report broken links, anchors, and nav entries as warnings, so that `mkdocs build --strict` (make build) fails
validation:
nav:
omitted_files: warn
not_found: warn
absolute_links: warn
links:
not_found: warn
anchors: warn
absolute_links: warn
unrecognized_links: warn
hooks:
- hooks/api_changes.py
- hooks/copy_markdown_source.py
- hooks/unreleased_versions.py
plugins:
- search:
separator: '[\s\-\.]'
lang: en
- minify:
minify_html: true
- git-revision-date-localized:
strict: false # log "has no git logs" for uncommitted pages as info, not as a warning
- redirects:
redirect_maps:
'api/basic_json/operator_gtgt.md': api/operator_gtgt.md
'api/basic_json/operator_ltlt.md': api/operator_ltlt.md
'api/basic_json/operator_literal_json.md': api/operator_literal_json.md
'api/basic_json/operator_literal_json_pointer.md': api/operator_literal_json_pointer.md
'api/json_pointer/operator_string.md': api/json_pointer/operator_string_t.md
'home/code_of_conduct.md': community/code_of_conduct.md
- htmlproofer: # see https://github.com/manuzhang/mkdocs-htmlproofer-plugin
enabled: !ENV [ENABLED_HTMLPROOFER, False]
raise_error_after_finish: true # log every broken link, then fail
skip_downloads: true # check headers only (customers.md links large PDFs)
raise_error_excludes: # integer status codes, fnmatch patterns
403: ['*'] # bot protection against the plugin's "Bot <uuid>" user agent
429: ['*'] # rate limiting (hundreds of github.com URLs)
502: ['*']
503: ['*']
504: ['*'] # timeouts are reported as 504
-1: # connection errors
- 'https://repology.org/*' # repology.org is suspended since 2026-09
- 'http://2ak5ape.257.cz/' # customers.md: kept although unreachable
400: ['https://www.meta.com/*'] # customers.md: answers the plugin's user agent with 400, browsers with 200
401:
- 'https://fossies.org/*' # answers the plugin's user agent with 401, browsers and curl with 200
- 'https://mysupport.razer.com/*' # customers.md: same, browsers answer 200
419: ['https://news.ycombinator.com/*'] # answers the plugin's user agent with 419, browsers with 200
404:
- 'https://gitlab.b-data.ch/*' # answers the plugin's user agent with 404, browsers with 200
# customers.md: kept although dead
- 'https://www.cisco.com/c/dam/en_us/about/doing_business/open_source/docs/CiscoWebexDeskCamera-23-1622100417.pdf'
- 'https://docs.cyberark.com/Downloads/Legal/Privileged%20Session%20Manager%20for%20SSH%20Third-Party%20Notices.pdf'
- 'https://docs.citrix.com/en-us/provisioning/2203-ltsr/downloads/pvs-third-party-notices-2203.pdf'
- 'https://docs.citrix.com/en-us/citrix-virtual-apps-desktops/2305/downloads/third-party-notices-apps-and-desktops.pdf'
500: ['https://marne.io/licenses'] # customers.md: kept although dead
ignore_urls:
- mailto:*
- privacy:
# repology.org refuses requests from GitHub Actions runners, which made
# the privacy plugin abort the whole build when it could not download the
# package badges (the fetch fails, then reading the missing cache entry
# raises FileNotFoundError). Readers' browsers are served normally, so
# leave these badges as external references instead of self-hosting them.
# The same goes for img.shields.io, whose version badges time out from
# time to time (strict mode turns the failed download into an error) and
# would go stale between builds if they were self-hosted anyway.
assets_exclude:
- repology.org/*
- img.shields.io/*
- llmstxt:
markdown_description: >
JSON for Modern C++ is a C++11 header-only library implementing a JSON
value type with an STL-like API, JSON Pointer/Patch, CBOR/MessagePack/
BSON/UBJSON/BJData/BON8 binary format support, and a SAX-style parser interface.
sections:
Home:
- index.md
- home/*.md
- home/blog/*.md
Features:
- features/*.md
- features/binary_formats/*.md
- features/element_access/*.md
- features/parsing/*.md
- features/types/*.md
Integration:
- integration/*.md
API Documentation:
- api/*.md
- api/basic_json/*.md
- api/basic_json_document/*.md
- api/basic_json_view/*.md
- api/adl_serializer/*.md
- api/byte_container_with_subtype/*.md
- api/json_pointer/*.md
- api/json_sax/*.md
- api/macros/*.md
Community:
- community/*.md
extra_css:
- css/custom.css
- css/brand.css
- css/fig-sax.css
- css/fig-jsonview.css
- css/fig-exceptions.css
- css/fig-pointer.css
- css/fig-charts.css
- css/fig-integration.css
- css/fig-macros.css
extra_javascript:
- js/mermaid-brand.js
- js/external-links.js
- js/fig-sax.js
- js/fig-jsonview.js
- js/fig-exceptions.js
- js/fig-pointer.js
- js/fig-charts.js
- js/fig-integration.js
- js/fig-macros.js
Reference in new issue View Git Blame Copy Permalink