json/docs/mkdocs/docs/community/roadmap.md

Roadmap

This page describes what the project intends to do, and what it does not intend to do, over the next year. Concrete work items are tracked in the GitHub milestones and the issue tracker.

What the project will do

• Keep the C++11 baseline. The library will continue to compile with every supported C++11 compiler. Features of later standards are only used when they are guarded by the JSON_HAS_CPP_* macros.
• Stay conformant to JSON. The parser and serializer follow RFC 8259. Extensions such as comments or trailing commas remain opt-in.
• Keep the 3.x public API stable. Releases follow semantic versioning. Changes that would break existing code are only added behind a feature macro, so users can opt in and test their code before a next major release, see Version 4.0.
• Support a broad range of compilers and platforms. The CI keeps testing old and new versions of GCC, Clang, MSVC, and other compilers on Linux, macOS, and Windows.
• Keep the quality assurance up. Every change keeps the test coverage at 100%, passes the static and dynamic analysis, and is fuzz-tested by OSS-Fuzz, see Quality assurance.
• Harden the library against hostile input. Handling deeply nested values without exhausting the call stack is ongoing work.
• Fix bugs and security issues reported through the issue tracker and the security policy.

What the project will not do

• Break the public API of version 3.x. See API stability for what this covers.
• Require a newer C++ standard than C++11.
• Break JSON conformance or enable non-standard extensions by default.
• Add dependencies or require a build step. The library remains header-only, and the single header json.hpp remains a complete distribution.
• Trade simplicity for speed or memory efficiency. Performance improvements are welcome, but the library is not meant to compete with the fastest JSON libraries, see Design goals.

API stability

Releases follow semantic versioning: a minor or patch release of version 3.x does not break code that uses the public API, unless that code opts in to a change with a macro as described below. In particular, a 3.x release does not:

• make breaking changes to the signature of a function: the types or order of its existing parameters, its return type, its noexcept or constexpr specifier, or the const-ness of a member function. New parameters may be added if they have a default value;
• remove or rename a function or class, or change the template parameters of a public class template;
• change which exceptions a function throws, or the exception ids;
• change access specifiers, or change or remove existing default arguments. New default arguments may be added;
• change the JSON type that a valid input parses to, or the text that dump() produces for a valid value;
• accept input that was rejected before, or reject input that was accepted before;
• change the order in which the keys of an object are iterated. The default type sorts keys, and ordered_json keeps insertion order;
• change when iterators, pointers, or references are invalidated, or the state of a moved-from basic_json;
• add or remove implicit conversions from basic_json;
• change how to_json and from_json functions are found, or the behavior of adl_serializer;
• add pure virtual functions to the json_sax interface;
• remove, rename, renumber, or add enumerators of value_t;
• remove or rename a documented macro, CMake option, CMake target, or header, or change what a documented macro does.

Exceptions to these rules, for instance when fixing a bug requires changing the exception a function throws, are documented in the release notes.

The following are not part of the public API and may change in any release, including patch releases:

• The text of exception messages returned by what(). Use the exception id to tell errors apart.
• The ABI, including sizeof(basic_json) and the memory layout of its values. The versioned inline namespace turns mixing versions into a link error.
• The hash values returned by std::hash for basic_json. Numbers that compare equal still hash equally.
• Everything in namespace nlohmann::detail, and macros and type traits that are not documented in the API reference.

Breaking changes are only added behind a macro whose default keeps the 3.x behavior. See Version 4.0 and the macro overview.

Version 4.0

There is no release date for version 4.0 yet. Proposals that need a major version, for instance stricter type conversions, are collected in issue #3453.

!!! note "Not final"

The plan for version 4.0 described below is not final and may still change: macros may be added to or removed from
the list, and planned defaults may be revised. Any such change will be documented on this page.

Trying out 4.0 today

Version 4.0 will not be developed on a separate branch. Instead, every breaking change is first added to a 3.x release behind a macro whose default keeps the 3.x behavior. Version 4.0 then switches the defaults and removes the macros. Version 4.0 is therefore the sum of these macros: you can try it on the 3.x release train today by defining each macro to its 4.0 value and fixing what no longer compiles or behaves differently. Once your code works with all of them, it is ready for version 4.0.

Each macro has a default value in 3.x and a different value in version 4.0. Define the macro to the 4.0 value to try it on the 3.x release train today; version 4.0 makes that value the default:

--8<-- "images/roadmap_lanes.svg"

Each row is one macro: the 3.x release that added it, its default in 3.x, and its value in version 4.0 (highlighted) or "removed". Versions on the 3.x lane are not to scale.

The following macros guard changes that are planned to become the default in version 4.0:

Macro	3.x default	4.0 behavior	CMake option	Added
JSON_USE_IMPLICIT_CONVERSIONS	1	0: no implicit conversions from basic_json to other types; use get instead	JSON_ImplicitConversions	3.9.0
JSON_USE_GLOBAL_UDLS	1	0: the string literals _json and _json_pointer are only available in namespace nlohmann::literals	JSON_GlobalUDLs	3.11.0
JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON	0	removed: the deprecated legacy comparison of discarded values can no longer be enabled	JSON_LegacyDiscardedValueComparison	3.11.0
JSON_BRACE_INIT_COPY_SEMANTICS	0	1: single-element brace initialization such as #!cpp json j{obj}; copies the element instead of creating an array	–	3.13.0
JSON_PRECISE_STREAM_POSITION	0	1: reading from a stream does not consume the character after a number	–	3.13.0
JSON_STRICT_NUL_HANDLING	0	1: a NUL byte in the input is a parse error instead of the end of input	JSON_StrictNulHandling	3.13.0
JSON_STRICT_BINARY_UTF8	0	1: to_cbor, to_ubjson, to_bjdata, and to_bson throw for strings that are not valid UTF-8 by default	JSON_StrictBinaryUTF8	3.13.0
JSON_DISABLE_TUPLE_REFERENCE_CONVERSION	0	1: a basic_json value can no longer be created from a one-element tuple of a reference to it, such as std::forward_as_tuple(j)	JSON_DisableTupleReferenceConversion	3.13.0
JSON_DELETE_DEPRECATED_FUNCTIONS	0	removed: the deprecated functions are removed (see below); the from_*(ptr, len) overloads stay deleted	JSON_DeleteDeprecatedFunctions	3.13.0

Opt-in macros for the version 4.0 behavior. "3.x default" is the value the library uses when the macro is not defined, "Added" is the release that introduced the macro, and – means there is no CMake option.

For example, the following makes a 3.x release behave like version 4.0 with respect to these changes:

#define JSON_USE_IMPLICIT_CONVERSIONS 0
#define JSON_USE_GLOBAL_UDLS 0
#define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON 0
#define JSON_BRACE_INIT_COPY_SEMANTICS 1
#define JSON_PRECISE_STREAM_POSITION 1
#define JSON_STRICT_NUL_HANDLING 1
#define JSON_STRICT_BINARY_UTF8 1
#define JSON_DISABLE_TUPLE_REFERENCE_CONVERSION 1
#define JSON_DELETE_DEPRECATED_FUNCTIONS 1
#include <nlohmann/json.hpp>

The macros must be defined before the library header is included; setting them once in the build system is the easiest way to achieve this.

Removal of deprecated functions

Version 4.0 will remove all deprecated functions. Compiling with deprecation warnings enabled shows which of them your code still uses. Defining JSON_DELETE_DEPRECATED_FUNCTIONS to 1 turns these warnings into errors, as the deprecated functions are then deleted. The migration guide shows how to replace each of them.

The from_* overloads taking a pointer and a length are not removed in version 4.0, but stay deleted. Without them, a call like from_cbor(ptr, len) would still compile: it would read ptr as a NUL-terminated string and convert len to the strict parameter.

Deprecated	Since	Migration
#!cpp operator<<(basic_json&, std::istream&)	3.0.0	Parsing
#!cpp operator>>(const basic_json&, std::ostream&)	3.0.0	Miscellaneous functions
iterator_wrapper	3.1.0	Miscellaneous functions
parse, accept, and sax_parse with an initializer list {ptr, len} or {first, last}	3.8.0	Parsing
from_bson, from_cbor, from_msgpack, and from_ubjson with (ptr, len) or an initializer list	3.8.0	Parsing
json_pointer::operator string_t	3.11.0	JSON Pointers
json_pointer with a basic_json type as template argument, and the overloads of value, contains, operator[], and at accepting such a pointer	3.11.0	JSON Pointers
Comparing a json_pointer with a string via operator== or operator!=	3.11.2	JSON Pointers
from_bjdata and from_bon8 with (ptr, len)	3.13.0	Parsing

Deprecated functions, with the release that deprecated each one and the section of the migration guide that shows its replacement.

The deprecated legacy comparison of discarded values is controlled by a macro and therefore listed in the table above.

New breaking changes will follow the same path: they are added to these tables when they land in a 3.x release.