JSON for Modern C++ version 3.12.0

Release date: 2025-04-11
SHA-256: aaf127c04cb31c406e5b04a63f1ae89369fccde6d8fa7cdda1ed4f32dfc5de63 (json.hpp), b8cb0ef2dd7f57f18933997c9934bb1fa962594f701cd5a8d3c2c80541559372 (include.zip), 42f6e95cad6ec532fd372391373363b62a14af6d771056dbfc86160e6dfff7aa (json.tar.xz)

Summary

This release fixes some bugs found in the 3.11.3 release and adds some new features.

All changes are backward-compatible.

💰 Note you can support this project via GitHub sponsors or PayPal.

Key updates and enhancements

• Diagnostic byte positions: A new macro, JSON_DIAGNOSTIC_POSITIONS, introduces member functions to query the byte positions of values in the input they were parsed from. When enabled, this information is also included in exceptions to help pinpoint errors. #4517 #4455 #4570 #4569 #4572 #4571 #4579 #4585 #4561
• Enhanced conversion macros: The conversion macros for arbitrary types now include several upgrades:
  • All macros are templated, supporting json, ordered_json, and any other basic_json specialization. #4597 #2528 #4377 #2532 #2843 #3810 #4608
  • Derived classes can now be seamlessly converted to/from JSON using the new NLOHMANN_DEFINE_DERIVED_TYPE_* macros. #4033 #2199 #4562
• Support for std::optional: The library now supports conversions from/to std::optional types when compiled with C++17. #1749 #4036
• Flexible string compatibility: Functions patch, diff, and flatten now work with arbitrary string types. #4536 #4134 #4613 #4019
• Binary format enhancements:
  • The BJData mapping now supports draft 3, including optimized binary array types. #4513 #4588
  • The BSON mapping has added support for unsigned 64-bit integers. #4590 #4535 #3894
  • The get_number function used in the binary format implementations has been optimized to read multiple bytes at once. #4391
• Multidimensional array conversion: Multidimensional C-style arrays can now be directly converted to JSON. #4262 #4248
• Filesystem paths in UTF-8: The conversions from/to std::filesystem::path are now encoded to UTF-8 strings by default on all operating systems. #4271 #4631
• CMake 4.0 support. By adjusting the CMake minimal version to 3.5, CMake 4.0 can be used without warning or error. #4709

Changes and fixes

• The iteration_proxy is now a std::forward_iterator instead of just an std::input_iterator. This allows more use cases when items() is fed into C++20 std::views. The iterator always satisfied all requirements for a forward iterator, but was exposed as only an input iterator by the used iterator tag. #4371 #4372
• Fix the conversion from enums with unsigned underlying type to JSON. #4236 #4237
• Fix GDB pretty printer which was broken since m_data added. #4343 #4309
• Update natvis to reflect 3.11.3 and the current structure of basic_json. #4451 #4438 #4438
• Fix crash when passing nullptr to parse function expecting FILE*. Instead, now an exception is thrown. #4485 #4487
• Fix number parsing such that integers are not parsed to float when EINTR set in errno. #4506
• Fix SAX output of number_float to be locale-independent. #4505 #4084
• Fix iterators to allow comparing default-initialized iterators. #4512 #4493
• Fix return value of get_ptr for unsigned integers. #4525 #4475
• Fix regression of #2755 and replace EOF with char_traits. #4532
• Fix extended diagnostics to not trigger an assertion. #4537 #3915
• Fix NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT throw an exception with an empty json #4507 #4508
• Modernize integer comparison. #4577 #4559
• Serialize empty tuple into [] instead of null. #4594 #4530

Warnings

The quality assurance page gives an overview of the warning flags used during the tests.

Compiler warnings

• Suppress weak-vtables warning for exceptions. #4500 #4087
• Add 40+ GCC warning flags for GCC 14.2.0. #4524
• Fix ignored attribute warning during build. #4670
• Add explanation for suppressed CodeQL issues. #4362 #4361
• Move compiler flags to separate CMake files (GCC, Clang). #4560

Clang-Tidy

• Suppress warnings modernize-use-std-numbers,
  readability-redundant-member-init, and bugprone-unused-local-non-trivial-variable. #4276
• Suppress warnings modernize-type-traits and modernize-avoid-c-arrays in NLOHMANN_JSON_SERIALIZE_ENUM. #4497 #3924
• Suppress warning boost-use-ranges as we do not want to rely on Boost. #4489
• Suppress warning modernize-use-designated-initializers as designated initializers are a C++20 feature. #4489
• Suppress warning modernize-use-ranges as ranges are a C++20 feature. #4489
• Suppress warning clang-analyzer-webkit.NoUncountedMemberChecker as we are using pointers internally. #4701
• Fix warning modernize-use-integer-sign-comparison . #4558

Build

CMake

• Adjust CMake minimal version to 3.5. #4709
• Allow overriding the CMake target name via variable NLOHMANN_JSON_TARGET_NAME. #4483
• Add CPack support. #4459
• Adjust CMake to generate a pkg-config file that follows the pkg-config conventions. #4456

Package Managers

• Remove alwayslink=True Bazel flag. #4396
• Improve Bazel support by switching to Bzlmod. #4584
• Add VisionOS support to Swift Package Manager Package.swift definition file. #4611
• Remove wsjcpp package manager support. #4623

CI

Tests

• Add test for libstdc++. #4495
• Skip enum tests when JSON_DisableEnumSerialization=ON. #4504 #4384
• Add a build step to build the documentation. #4549
• Fix the coverage job. #4595
• Add comment on reproducible builds. #4494 #4496

Infrastructure

• Remove unsupported macos-11 image; the following Xcode versions are no longer tested in the CI: '11.7', '12.4', '12.5.1', '13.0'. #4489
• Add macos-13 image to test Xcode versions '14.2', '14.3', '14.3.1', '15.0.1', '15.1', '15.2'. #4489
• Add macos-14 image to test Xcode versions '15.3', '15.4'. #4489
• Add macos-15 image to test Xcode versions '16.0', '16.1'. #4489
• Test GCC versions '4.8', '4.9', '5', '6' on json-ci image as these versions are no longer work on the respective gcc images (checkout fails). #4489
• Add tests for GCC versions '13', '14'. #4489
• Add tests for Clang versions '16', '17', '18', '19'. #4489
• Update README with a table of compilers/OS used in the CI. #4489
• Apply security best practices by StepSecurity. #4539 #4546 #4058 #4547 #4550 #4551
• Use Dependabot to automatically update GitHub actions and Python tools used in the CI. #4489 #4541 #4540 #4543 #4544 #4545 #4542 #4548 #4557 #4567 #4600 #4601 #4602 #4603 #4604 #4615 #4614 #4616 #4617 #4620 #4624 #4625 #4634 #4635 #4646 #4648 #4652 #4659 #4661 #4664 #4665 #4668 #4672 #4680 #4683 #4688 #4689 #4695 #4697 #4698 #4700 #4707 #4711 #4715 #4716 #4718 #4719 #4726
• Use ubuntu-latest image to run Valgrind. #4575
• Use Clang image to run iwyu. #4574
• Adjust permissions in workflows. #4553
• Use Python to install cppcheck. #4553
• Move requirements.txt files for cppcheck, cpplint, and reuse to central location. #4553
• Adjust cppcheck call. #4553
• Add code exclusions to source files. #4553
• Migrate stalebot to GitHub action. #4560
• Remove deprecated .lgtm.yml file. #4560
• Add CI steps for C++26. #4560
• Add Xcode 16.2 (macOS) and Clang 3.4 (Ubuntu) action. #4560
• Simplify Ubuntu workflow to use ubuntu-latest more often and reduce dependencies to more exotic containers. #4560
• Add DCO requirement: all commits since January 17, 2025, need to be signed off. #4560
• Remove .pre-commit-config.yml file. #4560
• Pull update for tests/thirdparty/imapdl/filterbr.py. #4560
• Make gdb-pretty-printer work with older Python versions. #4691 #4693
• Update the REUSE integration. #4521

Indentation and amalgamation

• Adjust and modernize flags for Artistic Style. #4277 #4275 #4573
• Fix deprecation warning in amalgamation CI check. #4227

Documentation

The documentation website contains all project documentation.

Fixed documentation

• Fix version history. #4269 #4310 #4307 #4310
• Remove broken link in Contribution Guidelines. #4274 #4486
• Fix custom data source example in README. #4335
• Fix an example to catch an exception by reference. #4331
• Fix example for JSON Pointer usage. #4255
• Fix using a wrong function in documentation. #4472
• Fix for incorrect function name in a documentation example. #4342 #4334
• Fix typos. #4345 #4412 #4565 #4679 #4723
• Fix style warnings. #4516
• Fix broken links. #4516 #4560 #4605
• Fix ci_test_api_documentation CI step. #4516
• Remove duplicate documentation files. #4560
• Fix the index file for mkdocs after merging. #4517
• Fix duplicate keys in navigation. #4560
• Add missing macros in README and link to docs for more info. #4582 #4260
• Fix documentation for macros to show correct names. #4564

Added documentation

• Add customer section to README. #4516 #4560
• Add ”which macro to choose?” decision tree. #4560
• Add comment about iterator invalidation. #4289 #4279
• Add a note to JetBrains support. #4592
• Add a community section to the documentation. #4560
• Document non-code files in FILES.md. #4560
• Add documentation for start_pos and end_pos. #4560
• Add glossary. #4560
• Add newer serialization macros to README. #4260
• Add a note on the derived return type for value function. #4628 #4626
• Add more "see also" links. #4636
• Add JSON_DIAGNOSTIC_POSITIONS to macro feature page. #4636

Improved documentation

• Update navigation. #4516
• Extend documentation of parse and accept with respect to #4485 #4487 #4516
• Update code of conduct. #4560
• Update contribution guidelines. #4560
• Update pull request template. #4560
• Update security policy. #4560
• Update docset table of contents. #4560
• Overwork documentation of all serialization macros (cross references, decision table, removed redundancies). #4560
• Shorten README serialization macro section. #4560
• Document the compilers used in the CI. #4560
• Add a quick reference to README. #4560
• Bump the copyright years. #4606

Package Manager documentation

• Extend the documentation of package managers with more examples. #4516
• Move package manager section to documentation. #4560
• Add Swift Package Manager and xmake. #4560
• Add an example for Conda. #4560
• Add an overview with logos. #4560
• Annotate Buckaroo, CocoaPods, and wsjcpp as outdated. #4560

Documentation implementation

• Replace PlantUML by Mermaid. #4026
• Serve assets (fonts, CSS) locally. #4560
• Update Python requirements. #4516