DRAFT: Release notes for upcoming release

[nlohmann]

Below are the closed issues and pull requests for the upcoming release. This page will be updated to include the final release notes. The content is a work in progress.

---

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. (json start/end position implementation #4517 Retrieving raw text from subobjects #4455 fix diagnostic positions related compilation errors #4570 Compilation issue with cmake option "JSON_Diagnostic_Positions" ON #4569 fix the abi tests for diagnostics positions feature #4572 Couple of ABI tests failed upon enabling JSON_Diagnostic_Positions cmake option #4571 add a ci step for Json_Diagnostic_Positions #4579 use diagnostic positions in exceptions #4585 Use diagnostic positions in exceptions #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. (Generate template functions with NLOHMANN_DEFINE_TYPE macros #4597 Cannot assign from ordered_json vector<CustomStruct> to value in not ordered json #2528 nlohmann::ordered_json: not compatible with NLOHMANN_DEFINE_TYPE_INTRUSIVE #4377 Templated versions of NLOHMANN_DEFINE_TYPE_INTRUSIVE and NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE #2532 Add templated version of DEFINE_TYPE macros #2843 ordered_json doesn't support construction from C array of custom type #3810)
  • Derived classes can now be seamlessly converted to/from JSON using the new NLOHMANN_DEFINE_DERIVED_TYPE_* macros. (Add NLOHMANN_DEFINE_DERIVED_TYPE_* macros #4033 How to Serialize derived class to JSON object?  #2199 Add ONLY_SERIALIZE for NLOHMANN_DEFINE_DERIVED_TYPE_* macros #4562)
• Support for std::optional: The library now supports conversions from/to std::optional types when compiled with C++17. ([C++17] Allow std::optional to convert to nlohmann::json #1749 feat: Rebase feature/optional to develop #4036)
• Flexible String Compatibility: Functions patch, diff, and flatten now work with arbitrary string types. (Allow patch and diff to be used with arbitrary string types #4536 patch_inplace assumes StringType is std::string #4134 fix compilation issue #4613 flatten() function does not compile if an alternative string type is used #4019)
• Binary Format Enhancements:
  • The BJData mapping now supports draft 3, including optimized binary array types. (BJData optimized binary array type #4513 BJData Fixes #4588)
  • The BSON mapping has added support for unsigned 64-bit integers. (Support BSON uint64 de/serialization #4590 uint64_t being converted to int64_t in to_json #4535 json::to_bson does not handle unsigned 64 bit integers #3894)
• Multi-Dimensional Array Conversion: Multi-dimensional C-style arrays can now be directly converted to JSON. (Add support of multi-dim C-style array member of struct. #4262 Is there any special consideration/limitation that multi-dimensional C-style array member of struct is not supported? #4248)

Changes

• The iteration_proxy is now a forward_iterator instead of just an 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. iteration_proxy has limited usefulness in C++20 range views #4371 Make iterator_proxy_value a forward_iterator (#4371) #4372

Optimization

• The get_number function used in the binary format implementations has been optimized to read multiple bytes at once. Optimize binary get_number implementation by reading multiple bytes at once #4391

Fix

• Fixed the conversion from enums with unsigned underlying type to JSON. to_json is erroneously converting enums with underlying unsigned types to signed numbers #4236 Fix to_json for enums when the enum has an unsigned underlying type. #4237
• Fix gdb pretty printer which was broken since m_data added Fix gdb pretty printer #4343 gdb-pretty-print broken since m_data added #4309
• Update natvis to reflect 3.11.3 and the current structure of basic_json Update natvis to reflect 3.11.3 and the current structure of basic_json #4451 Structure declared in natvis file template doesn't seem to match current structure of basic_json<> #4438 Structure declared in natvis file template doesn't seem to match current structure of basic_json<> #4438
• Fix crash when passing nullptr to parse function expecting FILE* Crash when parsing nullptr #4485 Possible fix for #4485 #4487
• Fix: integer parsed as float when EINTR set in errno fix: integer parsed as float when EINTR set in errno #4506
• Make SAX output of number_float locale-independent Make SAX output locale-independent #4505 SAX interface unexpectedly gets locale-altered float representation. #4084
• Allow comparing default initialized iterators Allow comparing default initialized iterators #4512 Default initialized iterators are not comparable #4493
• Fix return value of get_ptr for unsigned integers Fix return value of get_ptr for unsigned integers #4525 Invalid union access for get_ref/get_ptr with unsigned integer #4475
• Replace EOF with char_traits Replace EOF with char_traits #4532 (regression of Undefined symbol EOF  #2755)
• Fix: JSON_DIAGNOSTICS trigger assertion Set parents after insert call #4537 JSON_DIAGNOSTICS trigger assertion #3915
• NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT throw an exception with an empty json NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT throw an exception with an empty json #4507 Fix NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT with an empty JSON instance #4508
• Modernize integer comparison Modernize integer comparison #4577 Modernize integer comparison #4559
• Serialize empty tuple into '[]' instead of null Serialize empty tuple into '[]' instead of null #4594 Empty std::tuple<> cannot be serialized and de-serialized #4530

Documentation

• Fix version history Fix version in json_has_static_rtti.md #4269 #4307 Updated docx to 3.10.5 from 3.10.4 #4310 Docs have incorrect info for update() #4307 #4307 Updated docx to 3.10.5 from 3.10.4 #4310
• Remove broken link in Contribution Guidelines Remove broken link from CONTRIBUTING.md #4274 Update CONTRIBUTING.md #4486
• Fixed custom data source example in README. Fixed an error in the Custom data source example. #4335
• Fixed example to catch exception by reference. Updated exception handling to catch const reference in out_of_range #4331
• Fixed example for JSON Pointer usage Docs: Fix wrong code usage in the Value access section of json_pointer.md #4255
• Fixed wrong function in documentation Update is_structured.md #4472
• Fix for incorrect function name in documentation example Fix for incorrect function name in documentation example #4342 Wrong function name in documentation example #4334
• Fix typos chore: fix some typos in comments #4345 Docs: fix typos of 'whether' in operator_{gt,le,lt}.md #4412 Fix typo in nlohmann_define_derived_type.md #4565
• Overwork documentation Overwork documentation #4516
  • update Python requirements
  • fix style warnings
  • fix links
  • update navigation
  • replace PlantUML by Mermaid Missing requirement on plantuml binary package #4026
  • add customer section to README
  • extend documentation of parse and accept with respect to Crash when parsing nullptr #4485 Possible fix for #4485 #4487
  • fix ci_test_api_documentation CI step
  • add "which enum to choose?" decision tree
  • extend documentation of package managers with more examples
  • add comment about iterator invalidation (ordered json pointer corruption #4289, Program crashes with ordered_json, but works fine with json #4279).
• Extend documentation of supported package managers Add more package managers #4533
• Add missing macros in README and link to docs for more info Add missing macros in README and link to docs for more info #4582 Newer serialization macros not listed in README #4260
• Add note to Jetbrains support Add note to Jetbrains support #4592
• Clean up and document project files Clean up and document project files #4560
  • update GitHub community documents
    • update code of conduct
    • update contribution guidelines
    • update pull request template
    • update security policy
  • document non-code files in FILES.md
  • add community section to documentation
    • governance (new)
    • code of conduct (link)
    • contribution guidelines (link)
    • security policy (link)
    • quality assurance (new)
    • architecture (new, draft)
  • add DCO requirement
  • update GitHub actions
    • migrate stalebot to GitHub action
    • remove deprecated .lgtm.yml file
    • add CI steps for C++26
    • add Xcode 16.2 (macOS) and Clang 3.4 (Ubuntu) action
    • simplify Ubuntu workflow to use ubuntu-latest more often and reduce dependencies to more exotic containers
  • overwork documentation
    • remove duplicate documentation files
    • fix index file for mkdocs after merging json start/end position implementation #4517
    • update customers
    • update docset table of contents
    • overwork documentation of all serialization macros (cross references, decision table, removed redundancies)
    • fix duplicate keys in navigation (fixes Documentation for macros show wrong names #4564)
    • fix broken links
    • add documentation for start_pos and end_pos
    • add glossary
    • serve assets (fonts, CSS) locally
  • overwork README
    • move package manager section to documentation
    • shortened serialization macro section (fixes Newer serialization macros not listed in README #4260)
    • compilers use in the CI to documentation
    • add quick reference to README
  • overwork package manager documentation
    • add Swift Package Manager and xmake
    • add example for Conda
    • add overview with logos
    • annotate Buckaroo, CocoaPods, and wsjcpp as outdated
  • cleanup
    • remove .pre-commit-config.yml file
    • pull update for tests/thirdparty/imapdl/filterbr.py
    • move compiler flags to separate CMake files
• Documentation for macros show wrong names Documentation for macros show wrong names #4564
• Newer serialization macros not listed in README Newer serialization macros not listed in README #4260
• Fix broken links Fix broken links #4605
• Add note on derived return type for value function Add note on derived return type for value function #4628 basic_json::operator[key] and basic_json::value(key) return different values #4626

Warnings

• Suppress Clang-Tidy warnings (modernize-use-std-numbers ,
  readability-redundant-member-init, bugprone-unused-local-non-trivial-variable) Suppress Clang-Tidy warnings #4276
• Add explanation for suppressed CodeQL issues Add lgtm explanation #4362 CodeQL suppressions lack justification #4361
• Suppress modernize-type-traits and modernize-avoid-c-arrays Clang-Tidy warnings in NLOHMANN_JSON_SERIALIZE_ENUM Suppress warnings in NLOHMANN_JSON_SERIALIZE_ENUM #4497 modernize-avoid-c-arrays clang-tidy warning when using NLOHMANN_JSON_SERIALIZE_ENUM macro #3924
• Suppress weak-vtables warning for exceptions. Fix weak-vtables warning #4500 Getting a weak-vtables warning with clang on ubuntu 22.04 #4087
• Add more GCC warning flags Add more GCC warning flags #4524
• Suppress modernize-use-integer-sign-comparison Suppress modernize-use-integer-sign-comparison #4558
• Suppressed the following warnings: Another desperate try to fix the CI #4489
  • boost-use-ranges: we don't want to rely on Boost
  • modernize-use-designated-initializers: designated initializers are a C++20 feature
  • modernize-use-ranges: ranges are a C++20 feature

CI/Build

• Adjust flags for Artistic Style Align astyle flags in Makefile with CI #4277 Can't run make amalgamate #4275 Overwork astyle call #4573
• Allow overriding the CMake target name via variable NLOHMANN_JSON_TARGET_NAME Allow overriding the CMake target name #4483
• Update GitHub actions Another desperate try to fix the CI #4489
  • 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'
  • add macos-13 image to test Xcode versions '14.2', '14.3', '14.3.1', '15.0.1', '15.1', '15.2'
  • add macos-14 image to test Xcode versions '15.3', '15.4'
  • add macos-15 image to test Xcode versions '16.0', '16.1'
  • 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)
  • add tests for GCC versions '13', '14'
  • add tests for Clang versions '16', '17', '18', '19'
  • update REAMDE with table of compilers/OS used in the CI
• Add CPack support Add CPack support #4459
• Remove alwayslink=True Bazel flag Remove alwayslink=True Bazel flag #4396
• Add test for libstdc++ Add test for libstdc++ #4495
• Add comment on reproducible builds Inclusion of <nlohmann/json.hpp> imprints header path to binary, destroying path-independent reproductive builds #4494 Add comment for #4494 #4496
• Fix deprecation warning in amalgamation CI check Deprecation warning on save action in check-amalgamation CI step #4227
• Skip enum tests when JSON_DisableEnumSerialization=ON Skip enum tests when JSON_DisableEnumSerialization=ON #4504 JSON_BuildTests fail when JSON_DisableEnumSerialization is set to ON #4384
• CMake: generate a pkg-config file that follow pkg-config conventions CMake: generate a pkg-config file that follow pkg-config conventions #4456
• [StepSecurity] Apply security best practices [StepSecurity] Apply security best practices #4539 Clean up  #4546 Feat: hash pin github workflow dependencies #4058 Move reuse dependency to requirements.txt file #4547 Fix token permissions warnings #4550 [StepSecurity] ci: Harden GitHub Actions #4551
• Use Dependabot to automatically update GitHub actions and Python tools used in the CI. Another desperate try to fix the CI #4489 ⬆️ Bump pyyaml from 6.0 to 6.0.2 in /tools/serve_header #4541 ⬆️ Bump actions/github-script from 6.4.0 to 7.0.1 #4540 ⬆️ Bump github/codeql-action from 2.27.9 to 3.27.9 #4543 ⬆️ Bump lukka/get-cmake from 3.31.0 to 3.31.2 #4544 ⬆️ Bump ossf/scorecard-action from 2.3.3 to 2.4.0 #4545 ⬆️ Bump watchdog from 2.1.7 to 6.0.0 in /tools/serve_header #4542 Bump mkdocs-material from 9.5.48 to 9.5.49 in /docs/mkdocs #4548 Bump actions/upload-artifact from 4.4.3 to 4.5.0 #4557 Bump cppcheck from 1.4.6 to 1.4.7 in /cmake/requirements #4567 Bump lukka/get-cmake from 3.31.2 to 3.31.4 #4600 Bump github/codeql-action from 3.27.9 to 3.28.1 #4601 Bump srvaroa/labeler from 1b3cdb1af3e59155a08b9b2436d0d54feaff49e2 to e216fb40e2e6d3b17d90fb1d950f98bee92f65ce #4602 Bump actions/upload-artifact from 4.5.0 to 4.6.0 #4603 Bump step-security/harden-runner from 2.10.2 to 2.10.3 #4604 Bump mkdocs-material from 9.5.49 to 9.5.50 in /docs/mkdocs #4615 Bump step-security/harden-runner from 2.10.3 to 2.10.4 #4614 Bump actions/stale from 9.0.0 to 9.1.0 #4616 Bump github/codeql-action from 3.28.1 to 3.28.2 #4617 Bump github/codeql-action from 3.28.2 to 3.28.3 #4620 Bump github/codeql-action from 3.28.3 to 3.28.4 #4624 Bump lukka/get-cmake from 3.31.4 to 3.31.5 #4625 ⬆️ Bump coverallsapp/github-action from 2.3.4 to 2.3.6 #4634 ⬆️ Bump github/codeql-action from 3.28.4 to 3.28.6 #4635
• Add step to build the documentation Add step to build the documentation #4549
• Clean up CI Clean up CI #4553
  • use Python to install cppcheck
  • move requirements files for cppcheck, cpplint, and reuse to central location
  • adjust cppcheck call
  • add code exclusions to source file
  • adjust permissions in workflows
• Use ubuntu-latest image to run Valgrind Use ubuntu-latest image to run Valgrind #4575
• Use Clang image to run iwyu Use Clang image to run iwyu #4574
• Improve Bazel support: Switch to Bzlmod Improve Bazel support: Switch to Bzlmod #4584
• Fix coverage job Fix coverage job #4595
• Add VisionOS support to Swift Package Manager Package.swift definition file Add VisionOS support to Swift Package Manager Package.swift definition file #4611

Misc

• Update the REUSE integration Update licenses #4521
• Bump the copyright years Bump the copyright years #4606