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 the contribution guidelines for what counts as a breaking change.
• 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.

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.

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

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

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.