json/docs/mkdocs/docs/home/releases.md

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.

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.

See also

• Migration Guide — how to future-proof your code for the next major version and replace deprecated functions.