mirror of https://github.com/nlohmann/json.git synced 2026-10-03 05:00:30 +00:00

Files

T

Niels Lohmann 63c10a51fc Review and extend the documentation, and check it in CI (#5638 )

* Review and extend the documentation, and check it in CI

A review of all documentation pages found factual errors, dead links,
missing cross-references, and gaps in examples. This fixes them and adds
checks so the same problems are caught automatically.

Fixes:
- wrong signatures and version histories (operator!= C++20 member,
  binary() subtype type, get<PointerType>(), JSON_NO_THREAD_LOCAL, ...)
- stale descriptions (number parsing since #5283, UBJSON table, SAX
  example that no longer compiled, tsl::ordered_map advice)
- dead internal and external links; repology.org badges (the domain is
  suspended) replaced by badges that query the registries directly
- deprecation notes link the migration guide; the guide itself fixed

Additions:
- "See also" sections, cross-references, 25 runnable examples, 12
  Mermaid diagrams, new API pages for json_pointer::operator<=> and
  byte_container_with_subtype::operator==/!=
- landing page, guides for untrusted input and performance
- "unreleased" badge after versions newer than the latest release

Checks:
- strict documentation build (broken links/anchors fail it); CI and
  the publish workflow fetch the full history the build needs
- weekly external link check, Mermaid syntax check in CI
- check_structure.py: example titles, heading levels, alt texts,
  header links, docset index coverage; its unused-example check works
  again
- all examples produce the same output on every platform

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Keep the customer links that could not be fixed

A dead link on the customers page is still the evidence of where the
use of the library was documented. Keep the original URLs of the entries
without a working replacement (Marne, Cisco Webex Desk Camera, Philips
Hue, CyberArk) and exclude exactly these URLs from the link check.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Correct the duplicate-key recipe's claim about SAX positions

The SAX interface's key() receives no position either; only parse_error()
does. Also note that the recipe does not report the path to the repeated
key (see discussion #5085).

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Say the library is available as a single header and mention json_fwd.hpp

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Correct documentation errors found while hunting for bugs

- patch/patch_inplace: list the JSON pointer errors parse_error.106-109
  and out_of_range.402/404, and quote the actual parse_error.105 message.
- unflatten: list parse_error.106/107/108 and out_of_range.404.
- to_bson: list out_of_range.415 (binary subtype above 255) and note
  that 412 and 415 are new in 3.13.0.
- to_string: state that string_t must be convertible to std::string, also
  in the StringType requirements table.
- JSON Lines: a `while (input >> j)` loop also throws after the last value
  for concatenated JSON values; show a loop that works for both.
- BON8: a string gets 0xFF only if nothing follows it in the message; a
  string at the end of an array or object is ended by 0xFE.
- custom_string_type.hpp: add operator+=(char), which the "Always
  required" list asks for (json_pointer::to_string, flatten, unflatten,
  and diff did not compile), and an ADL int_to_string for diff and items.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

* Cache the release headers with functools.lru_cache

Codacy (Pylint) flagged the mutable default argument that header() used
as its cache. functools.lru_cache keeps the same memoization without it.
The script's output is unchanged.

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

---------

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

2026-10-02 11:32:15 +02:00

20 KiB

Raw Blame History

Releases

This page summarizes the notable changes of every release and links to the relevant documentation. The complete release notes — including all changes, the download files, and their checksums — are published on the GitHub releases page.

!!! info "Unreleased changes"

This documentation is built from the `develop` branch and may describe changes that are not part of a release
yet. Their version numbers are followed by an <span class="unreleased-version">unreleased</span> badge.

v3.12.0 (2025-04-11)

Fixes bugs found in 3.11.3 and adds several features. All changes are backward-compatible.

Adds diagnostic byte positions via JSON_DIAGNOSTIC_POSITIONS, exposed through the new start_pos and end_pos member functions.
Makes the conversion macros templated (so they also work with ordered_json) and adds NLOHMANN_DEFINE_DERIVED_TYPE for derived classes.
Adds std::optional support (C++17) and lets patch, diff, and flatten work with arbitrary string types.
Extends the binary formats: BJData draft 3 and unsigned 64-bit integers for BSON.
Adds multidimensional C-array conversion and UTF-8 encoded std::filesystem::path conversions, and lowers the minimum CMake version to allow CMake 4.0.

Full release notes.

v3.11.3 (2023-11-28)

Adds features and fixes bugs found in 3.11.2. All changes are backward-compatible.

Adds a custom base class as a node customization point.
Adds serialization-only conversion macros (NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE and NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE) and a clearer parse error for empty input.
Adds Bazel and Swift Package Manager build support.
Fixes custom allocators, a memory leak in adl_serializer's to_json, initializer-list construction when size_type is not int, and many compiler warnings.

Full release notes.

v3.11.2 (2022-08-12)

Fixes bugs found in 3.11.1 and restructures the namespace. All changes are backward-compatible.

Fixes the value function (broken for strings, size types, and nullptr in 3.11.0) and makes json_fwd.hpp self-contained.
Restores using json_pointer as a key in associative containers and comparing it with strings.
Restructures the inline namespace and allows disabling the version component, and avoids heap allocations in the BJData parser.

Full release notes.

v3.11.1 (2022-08-01)

Fixes a regression from 3.11.0. All changes are backward-compatible.

Restores the global user-defined string literals operator""_json and operator""_json_pointer, which 3.11.0 had moved into a namespace by default.

Full release notes.

v3.11.0 (2022-08-01)

One of the largest releases ever. All changes are backward-compatible.

Allows std::string_view as object keys in at, operator[], value, erase, find, contains, and count.
Adds the BJData binary format (the fifth supported format).
Improves C++20 support, including operator<=> and <ranges>-compatible iterators.
Adds a versioned, ABI-tagged inline namespace (NLOHMANN_JSON_NAMESPACE) and the option to move the UDLs out of the global namespace (JSON_USE_GLOBAL_UDLS).
Adds patch_inplace, default values for the conversion macros, and an option to disable enum serialization (JSON_DISABLE_ENUM_SERIALIZATION).

This release introduced a UDL regression that was fixed in 3.11.1. Full release notes.

v3.10.5 (2022-01-03)

Bug-fix release. All changes are backward-compatible.

Guards the std::filesystem conversions behind compiler-support checks (JSON_HAS_FILESYSTEM), which can be set to 0 to disable them altogether.

Full release notes.

v3.10.4 (2021-10-16)

Fixes regressions introduced in 3.10.0. All changes are backward-compatible.

Fixes the std::filesystem::path conversion (which could trigger a stack overflow and broke compilation on Windows).
Fixes compilation for types with an explicit defaulted constructor and for code relying on the return values of std::find and std::remove.

Full release notes.

v3.10.3 (2021-10-08)

Fixes more regressions from 3.10.0. All changes are backward-compatible.

Fixes extended-diagnostics assertions triggered by update and by inserting into arrays.
Supports custom allocators when writing binary formats into a std::vector, and allows conversion from types that only provide begin()/end().

Full release notes.

v3.10.2 (2021-08-26)

Re-release of 3.10.1, whose Git tag pointed at the wrong commit due to a bug in the release script. All changes are backward-compatible. Full release notes.

v3.10.1 (2021-08-24)

Fixes a regression from 3.10.0. All changes are backward-compatible.

Fixes an extended-diagnostics assertion triggered when used with ordered_json, and hardens the GDB pretty-printer.

Full release notes.

v3.10.0 (2021-08-17)

Feature release. All changes are backward-compatible.

Adds extended diagnostic messages (JSON_DIAGNOSTICS) that prepend a JSON pointer to exception messages to pinpoint the offending value.
Adds a GDB pretty-printer and a cbor_tag_handler_t store option to keep CBOR tags as binary subtypes.
Supports containers with non-default-constructible types and parsing from std::byte.
Adds JSON_NO_IO to exclude the I/O headers and the JSON_HAS_CPP_* macros to override the detected C++ standard.

Full release notes.

v3.9.1 (2020-08-06)

Fixes two regressions from 3.9.0. All changes are backward-compatible.

Accepts consecutive comments and completes the ordered_json interface (e.g. ordered_json::parse).

Full release notes.

v3.9.0 (2020-07-27)

Feature release adding four long-requested features. All changes are backward-compatible.

Optional comment parsing in parse via the ignore_comments parameter.
ordered_json to preserve the insertion order of object keys.
An option to switch off implicit conversions.
The NLOHMANN_DEFINE_TYPE_* convenience macros, plus high-precision-number support for UBJSON and CBOR tag handling.

Full release notes.

v3.8.0 (2020-06-14)

Feature release. All changes are backward-compatible.

Introduces a binary value type that is read from and written to CBOR, BSON, and MessagePack, and can be shared between formats.
Generalizes the input adapters to read from any LegacyInputIterator container (3–10 % faster parsing).
Fixes contains for JSON pointers and makes the binary from_cbor/from_msgpack/etc. functions respect allow_exceptions.

Full release notes.

v3.7.3 (2019-11-17)

Fixes a regression from 3.7.2 that could yield quadratic complexity in destructor calls. All changes are backward-compatible. Full release notes.

v3.7.2 (2019-11-10)

Fixes a stack overflow for deeply nested input by making the destructor iterative; parsing is now bounded only by available memory. All changes are backward-compatible. Full release notes.

v3.7.1 (2019-11-06)

Bug-fix release. All changes are backward-compatible.

Fixes a segmentation fault when serializing the std::int64_t minimum value and fixes contains for JSON pointers.
Allows items with a custom string type and makes json_pointer::back const.

Full release notes.

v3.7.0 (2019-07-28)

Convenience features and house-keeping. All changes are backward-compatible.

Adds a contains overload that checks a JSON pointer without throwing, a generic to_string, and a return value for emplace_back.

Full release notes.

v3.6.1 (2019-03-20)

Fixes a regression (GCC 7/8 compilation) and a <Windows.h> build error introduced in 3.6.0. All changes are backward-compatible. Full release notes.

v3.6.0 (2019-03-20)

Feature release. All changes are backward-compatible.

Reworks the JSON pointer interface (operator/, push_back, parent_pointer, …).
Adds a contains function to test for an object key and greatly improves the performance of integer serialization.

Full release notes.

v3.5.0 (2018-12-22)

Feature release. All changes are backward-compatible.

Adds structured-binding support via the items function and reading from FILE* in the parse function.
Fixes the eofbit handling on input streams and a bug in the BSON SAX parser.

Full release notes.

v3.4.0 (2018-10-30)

Feature release. All changes are backward-compatible.

Adds BSON read/write support.
Adds configurable Unicode error handlers to dump (throw, replace with U+FFFD, or ignore) and the NLOHMANN_JSON_SERIALIZE_ENUM macro for enum conversion.
Improves parse-error messages with line/column positions and context.

Full release notes.

v3.3.0 (2018-10-05)

Feature release. All changes are backward-compatible.

Adds GCC 4.8 support, the get_to function, and an overhauled and documented CMake integration.

Full release notes.

v3.2.0 (2018-08-20)

Feature release. All changes are backward-compatible.

Adds a SAX interface and a non-recursive parser.
Adds parsing from wide-string types (std::wstring, std::u16string, std::u32string) and std::string_view (C++17), and round-tripping of std::map/std::unordered_map with non-string keys.

Full release notes.

v3.1.2 (2018-03-14)

Bug-fix release. All changes are backward-compatible.

Fixes a memory leak in the parser callback and adds user-defined string-type support to the parser and serializer.

Full release notes.

v3.1.1 (2018-02-13)

Bug-fix release. All changes are backward-compatible.

Fixes parsing of indefinite-length CBOR strings, a user-defined conversion to vector types, and overflow detection for UBJSON containers.

Full release notes.

v3.1.0 (2018-02-01)

Feature release. All changes are backward-compatible.

Adds UBJSON read/write support and JSON Merge Patch via merge_patch.
Switches to the Grisu2 algorithm for short, round-trippable floating-point output, and splits the header into multiple files with a forward-declaration header.

Full release notes.

v3.0.1 (2017-12-29)

Fixes small issues in the JSON Pointer and JSON Patch implementations (invalid "copy" targets and non-integer array indices). All changes are backward-compatible. Full release notes.

v3.0.0 (2017-12-17)

First 3.x release — a major release with breaking changes (see the migration guide).

Introduces user-defined exceptions (json::exception and subtypes, each with an identifier).
Adds a non-throwing accept function and an allow_exceptions flag for parse, and an update function to merge objects.
Adds streaming for CBOR and MessagePack and allows storing NaN/infinity.
Non-UTF-8 strings now throw on serialization, and the iterator category changed to bidirectional.

Full release notes.

v2.1.1 (2017-02-25)

Bug-fix release. All changes are backward-compatible.

Makes number parsing and serialization locale-independent with correct floating-point round-tripping; released files are now GPG-signed.

Full release notes.

v2.1.0 (2017-01-28)

Feature release. All changes are backward-compatible.

Adds conversions from and to arbitrary user-defined types via to_json/from_json, the meta function, and the option to switch off exceptions (JSON_NOEXCEPTION).

Full release notes.

v2.0.10 (2017-01-02)

Fixes several security-relevant bugs in the CBOR and MessagePack parsers found by OSS-Fuzz. All changes are backward-compatible. Full release notes.

v2.0.9 (2016-12-16)

Adds the CBOR and MessagePack binary formats. All changes are backward-compatible. Full release notes.

v2.0.8 (2016-12-02)

Adds the emplace and emplace_back functions and improves parsing and serialization performance. All changes are backward-compatible. Full release notes.

v2.0.7 (2016-11-02)

Fixes several parser bugs found through the "Parsing JSON is a Minefield" study (short files, encoding detection, surrogate pairs). All changes are backward-compatible. Full release notes.

v2.0.6 (2016-10-15)

Fixes operator[] for JSON pointers so that it creates missing values like the other overloads. All changes are backward-compatible. Full release notes.

v2.0.5 (2016-09-14)

Fixes a remaining stream end-of-file detection bug in the parser. All changes are backward-compatible. Full release notes.

v2.0.4 (2016-09-11)

Fixes stream end-of-file detection in the parser. All changes are backward-compatible. Full release notes.

v2.0.3 (2016-08-31)

Generalizes the parser to accept any contiguous sequence of one-byte elements and deprecates the input-stream constructor in favor of the parse function. All changes are backward-compatible. Full release notes.

v2.0.2 (2016-07-31)

Overhauls the parser (now rejecting unescaped control characters), tightens the class invariants, and cleans up the code. All changes are backward-compatible. Full release notes.

v2.0.1 (2016-06-28)

Fixes a performance regression in the dump function by adjusting the stream locale once per serialization. All changes are backward-compatible. Full release notes.

v2.0.0 (2016-06-24)

Feature release with a minor (potentially non-backward-compatible) API change from added noexcept and constexpr specifiers.

Adds JSON Pointer support in at and operator[], plus flatten and unflatten.
Adds JSON Patch via diff and patch, unsigned 64-bit integer support, and locale-independent serialization.

Full release notes.

v1.1.0 (2016-01-24)

Bug-fix and feature release. All changes are backward-compatible.

Improves floating-point round-tripping, adds a get_ref accessor for stored values, and introduces runtime assertions.

Full release notes.

v1.0.0 (2015-12-28)

First official release. Full release notes.

20 KiB Raw Blame History Unescape Escape

Releases

v3.12.0 (2025-04-11)

v3.11.3 (2023-11-28)

v3.11.2 (2022-08-12)

v3.11.1 (2022-08-01)

v3.11.0 (2022-08-01)

v3.10.5 (2022-01-03)

v3.10.4 (2021-10-16)

v3.10.3 (2021-10-08)

v3.10.2 (2021-08-26)

v3.10.1 (2021-08-24)

v3.10.0 (2021-08-17)

v3.9.1 (2020-08-06)

v3.9.0 (2020-07-27)

v3.8.0 (2020-06-14)

v3.7.3 (2019-11-17)

v3.7.2 (2019-11-10)

v3.7.1 (2019-11-06)

v3.7.0 (2019-07-28)

v3.6.1 (2019-03-20)

v3.6.0 (2019-03-20)

v3.5.0 (2018-12-22)

v3.4.0 (2018-10-30)

v3.3.0 (2018-10-05)

v3.2.0 (2018-08-20)

v3.1.2 (2018-03-14)

v3.1.1 (2018-02-13)

v3.1.0 (2018-02-01)

v3.0.1 (2017-12-29)

v3.0.0 (2017-12-17)

v2.1.1 (2017-02-25)

v2.1.0 (2017-01-28)

v2.0.10 (2017-01-02)

v2.0.9 (2016-12-16)

v2.0.8 (2016-12-02)

v2.0.7 (2016-11-02)

v2.0.6 (2016-10-15)

v2.0.5 (2016-09-14)

v2.0.4 (2016-09-11)

v2.0.3 (2016-08-31)

v2.0.2 (2016-07-31)

v2.0.1 (2016-06-28)

v2.0.0 (2016-06-24)

v1.1.0 (2016-01-24)

v1.0.0 (2015-12-28)

See also

20 KiB

Raw Blame History