JSON for Modern C++ (nlohmann/json) — Admin & Integrator Guide

This guide is for the engineer who integrates, builds, ships, or extends JSON for Modern C++ — not the day-to-day API consumer (that audience is served by the companion User Guide). Here you'll find the library's internal architecture, the complete compile-time configuration surface, the single-header amalgamation and ABI machinery, the build and test system, security considerations, and guidance for extending or contributing.

The library is header-only, so "deployment" means integration into a downstream build and control of compile-time behavior rather than running a service. That reframing drives the structure below.

Note

Documented version: 3.12.0 (source commit d10879b). The library has no runtime configuration and no server component. Its "operational surface" is the preprocessor macro set, the CMake package, and the amalgamation tooling. The canonical online reference is json.nlohmann.me.

Table of Contents

1. Executive Summary
2. Architecture Overview
3. Source Layout
4. The basic_json Value Model
5. Pipelines: Parsing, Serialization, Binary Formats
6. The Serialization Customization System (ADL)
7. Compile-Time Configuration: Full Macro Reference
8. Build & Integration
9. The Amalgamation & ABI Machinery
10. Test & Quality Infrastructure
11. Tooling
12. Security Analysis
13. Code Quality & Conventions
14. Extending the Library
15. Known Issues & Improvement Areas
16. Quick Reference

1. Executive Summary

What it is. A single-class-centric C++ library that models a JSON document as the class template basic_json, with the alias nlohmann::json providing the common instantiation. It emphasizes intuitive syntax over raw speed, treating JSON values like STL containers and supporting bidirectional conversion to arbitrary C++ types.

How it ships. Two consumable forms generated from the same include/nlohmann/ source tree:

• Multi-header (include/nlohmann/json.hpp + the detail/ tree) — for developers who want only the parts they use and faster incremental rebuilds.
• Single-header (single_include/nlohmann/json.hpp) — one amalgamated file for drop-in use, generated by the tools/amalgamate pipeline.

Key architectural properties for an integrator:

2. Architecture Overview

The public surface is small — essentially one class template plus a few helpers — but it sits on a layered internal stack under detail/.

                    Public API (include/nlohmann/*.hpp)
   ┌───────────────────────────────────────────────────────────────┐
   │  basic_json<...>    json (alias)    ordered_json (alias)        │
   │  json_pointer       json_sax        adl_serializer             │
   │  byte_container_with_subtype        ordered_map                 │
   └───────────────────────────────────────────────────────────────┘
                                  │  uses
   ┌───────────────────────────────────────────────────────────────┐
   │                    detail/  (internal implementation)          │
   │                                                                 │
   │  input/    lexer → parser → json_sax_dom_(callback_)parser      │
   │            binary_reader (CBOR/MsgPack/UBJSON/BSON/BJData)       │
   │            input_adapters (string / stream / iterator / array)  │
   │                                                                 │
   │  output/   serializer (text dump, UTF-8 handling)               │
   │            binary_writer (binary formats)                       │
   │            output_adapters (string / stream / vector)           │
   │                                                                 │
   │  conversions/  from_json.hpp  to_json.hpp  (ADL hooks)          │
   │                                                                 │
   │  iterators/  iter_impl  json_reverse_iterator                   │
   │              iteration_proxy  primitive_iterator                │
   │                                                                 │
   │  meta/    type_traits  cpp_future  detected  call_std           │
   │           (SFINAE, feature detection, C++ version shims)        │
   │                                                                 │
   │  value_t.hpp   exceptions.hpp   hash.hpp   json_pointer.hpp     │
   │  json_ref.hpp  macro_scope.hpp  abi_macros.hpp  string_*.hpp    │
   └───────────────────────────────────────────────────────────────┘

Two design decisions dominate everything:

1. basic_json is a template, json is a typedef. Almost every type in the library — the object map, array vector, string, number types, allocator, and even the serializer — is a template parameter with a sensible default. nlohmann::json is the default instantiation; nlohmann::ordered_json swaps the object container for an insertion-ordered map.
2. Customization happens through ADL (Argument-Dependent Lookup), not inheritance. To make a type serializable you provide free to_json/from_json functions (directly or via macros); the library finds them through the adl_serializer indirection. No base class, no virtual dispatch.

3. Source Layout

The triage of the repository (HIGH = source/docs that define behavior; LOW = leaf detail headers and per-integration fixtures) maps to these areas:

Note

By raw character count the repository is dominated by tests/src (~2 MB of unit tests across 79 files) and the example corpus. The library itself is the comparatively small include/nlohmann/ tree. When reasoning about behavior, the headers are ground truth; the tests are the executable specification.

4. The basic_json Value Model

basic_json stores exactly one JSON value at a time using a tagged union.

Type tag — value_t

The discriminant is the enum detail::value_t (exposed as json::value_t):

null, object, array, string, boolean, number_integer, number_unsigned, number_float, binary, discarded.

The ordering matters: it defines the comparison order between values of different types. discarded is a special internal state produced when a parser callback rejects a subtree.

Storage — the json_value union

The payload is a union. Variable-length types are heap-allocated (pointer in the union) so the union itself stays small — at most 64 bits with the default type parameters:

The default type parameters are: object = std::map, array = std::vector, string = std::string, integer = std::int64_t, unsigned = std::uint64_t, float = double, boolean = bool. All are template arguments — ordered_json differs only by substituting an insertion-ordered map for the object type.

Invariants and iterative destruction

The class enforces an invariant — checked by assert_invariant() at the end of every mutating operation — that the type tag and the active union member always agree (a non-null object/array/string/binary pointer when the tag says so).

Important

Destruction of nested containers is iterative, not recursive. json_value::destroy() flattens the value into a heap-allocated stack and tears it down in a loop. This is a deliberate defense against stack overflow when destroying very deeply nested documents (e.g. adversarial input) — a recursive destructor would blow the stack. Keep this in mind if you ever fork the storage layer.

Diagnostics: parent pointers

When JSON_DIAGNOSTICS=1, each value additionally tracks an m_parent pointer maintained by set_parents() / set_parent(). This lets exceptions report the JSON Pointer path to the offending element. Because it adds a member and changes layout, it is an ABI-affecting flag (see §7 and §9).

5. Pipelines: Parsing, Serialization, Binary Formats

Input path (text → value)

input source ──▶ input_adapter ──▶ lexer ──▶ parser ──▶ json_sax_dom_parser ──▶ basic_json
   (string,         (uniform           (tokens)   (grammar)   (builds DOM)
    stream,          byte feed)
    iterator,
    bytes)

• input_adapters normalize every input kind (string, std::istream, iterator pair, contiguous byte container) into a uniform byte feed.
• The lexer turns bytes into tokens, with optional comment skipping.
• The parser drives the grammar and emits SAX events, optionally invoking the user parser_callback_t to accept/reject/transform elements (rejected subtrees become discarded).
• json_sax_dom_parser (or the callback variant) consumes the events and materializes the basic_json.

accept() runs the same front end but discards the result, returning only validity. sax_parse() exposes the SAX layer directly so you can consume events without ever building a DOM — essential for streaming very large inputs.

Output path (value → text)

The serializer walks the value and writes to an output_adapter (string, stream, or vector). It owns indentation, the indent character, ensure_ascii escaping, and UTF-8 error handling via error_handler_t (strict throws, replace emits U+FFFD, ignore drops bad bytes).

Binary formats

binary_reader and binary_writer implement five formats behind the symmetric from_<fmt> / to_<fmt> static functions: CBOR, MessagePack, UBJSON, BSON, BJData. They reuse the same SAX/DOM plumbing as text parsing. The binary_t type (a byte_container_with_subtype<BinaryType>) carries an optional integer subtype so formats that support tagged binary (CBOR, BSON) can round-trip it.

Note

The SAX interface (json_sax<basic_json>) is a first-class extension point. Implement its callbacks (null, boolean, number_integer, string, start_object, key, end_object, start_array, end_array, binary, parse_error) to build your own consumer — for example, validating or streaming-transforming a multi-gigabyte document without materializing it.

6. The Serialization Customization System (ADL)

The mechanism that lets json j = my_struct; compile is worth understanding because it is where most integration effort goes.

1. basic_json's converting constructor and get<T>() delegate to JSONSerializer<T> — by default adl_serializer<T>.
2. adl_serializer<T>::to_json / from_json simply call unqualified to_json / from_json, triggering ADL in T's namespace.
3. The library ships to_json/from_json overloads for all standard types (arithmetic, std::string, std::vector, std::map, std::array, std::optional (C++17), tuples, etc.) in detail/conversions/.
4. For your own types you provide the two free functions — by hand, or generated by a macro.

The macro families

The NLOHMANN_DEFINE_TYPE_* and NLOHMANN_DEFINE_DERIVED_TYPE_* macros generate those two functions for you. They form a matrix along three axes:

NLOHMANN_DEFINE_DERIVED_TYPE_* variants additionally serialize a base class's members. NLOHMANN_JSON_SERIALIZE_ENUM (and its _STRICT form) generate the enum ↔ JSON mapping.

Tip

Choose the variant by your input contract: WITH_DEFAULT for tolerant config-style inputs, the plain variant for strict schemas where a missing field is a hard error, ONLY_SERIALIZE for write-only DTOs (logs, telemetry), and WITH_NAMES when the wire format's keys differ from your C++ identifiers (e.g. "first-name" ↔ firstName).

7. Compile-Time Configuration: Full Macro Reference

Because the library has no runtime configuration, macros are the entire configuration surface. Define them before including the header or, preferably, on the CMake target so they propagate consistently.

Behavior toggles

Feature-detection macros (read-only)

These are set by the library based on the active standard, but you can override the unsupported-compiler/version checks:

Advanced hooks

Caution

The four ABI-affecting macros change basic_json's memory layout or symbol names. If two translation units — or your code and a prebuilt dependency — disagree on any of them, you get One-Definition-Rule violations that manifest as link errors or, worse, silent memory corruption. The inline-namespace scheme (§9) turns some of these into clean link-time errors instead of runtime UB, but the safe rule is: define ABI macros once, on the target, for the whole build graph. Issue #3106 is the canonical report of getting this wrong via find_package.

8. Build & Integration

Consuming the library (downstream)

Always link the imported target; never hand-roll include paths.

find_package(nlohmann_json 3.12.0 REQUIRED)
target_link_libraries(my_app PRIVATE nlohmann_json::nlohmann_json)

Equivalent acquisition methods — FetchContent, CPM, add_subdirectory, single-header drop-in, and the system package managers — all surface the same nlohmann_json::nlohmann_json target. (Full snippets are in the User Guide §2.) Other build systems are first-class too: Meson (dependency('nlohmann_json')), Bazel, Buildroot/Buildsystem fixtures under docs/mkdocs/docs/integration/, and Swift Package Manager (Package.swift targets single_include/nlohmann, C++11).

Building the library's own test/dev tree

mkdir build && cd build
cmake .. -DJSON_BuildTests=ON
cmake --build . -j
ctest -j

Relevant CMake options (from tests/CMakeLists.txt and the project options):

Note

The test build compiles each unit file against every supported C++ standard the toolchain provides (11, 14, 17, 20, 23), guarded by per-compiler capability checks in tests/CMakeLists.txt (e.g. Clang < 5.0 has no C++17, GCC < 9.0 has flaky C++20). This is why a full test run is large — the matrix is files × standards.

C++20 modules

The library can be consumed as a C++20 module (import nlohmann.json;), exercised by tests/module_cpp20. There are known rough edges on some compilers (GCC redefinition warnings are suppressed via pragmas in json.hpp; MSVC C++23-module issues are tracked in #5002). Treat module support as available-but-evolving and pin compiler versions if you depend on it.

9. The Amalgamation & ABI Machinery

Single-header generation

single_include/nlohmann/json.hpp is generated, never hand-edited. tools/amalgamate/amalgamate.py walks the multi-header include graph, inlines each #include <nlohmann/...> exactly once (tracking already-included files), and emits one self-contained header. The Amalgamation/TranslationUnit classes drive this; tools/serve_header watches the source tree and re-amalgamates on change for local docs/dev.

Important

If you patch the library in place, edit files under include/nlohmann/ and regenerate the amalgamation — do not edit single_include/ directly, or your change will be silently overwritten on the next build and will not match the multi-header form that find_package may install.

The inline-namespace ABI guard

The real symbols live not in nlohmann but in a nested inline namespace whose name encodes the library version and the active ABI-affecting flags — produced by NLOHMANN_JSON_NAMESPACE_BEGIN/_END. The effect: a json compiled with JSON_DIAGNOSTICS=1 and a json compiled with it off are different types with different mangled names. Linking incompatible objects then fails at link time (a clear error) rather than corrupting memory at runtime.

The tests/abi/ tree exists solely to verify this: it links translation units built with mismatched JSON_DIAGNOSTICS settings (tests/abi/diag/) and old-vs-new inline-namespace builds (tests/abi/inline_ns/, e.g. use_v3_10_5.cpp linked with use_current.cpp) and asserts they coexist safely.

Tip

If you intentionally need to mix versions in one binary (rare — e.g. a transitive dependency pins an older release), the inline-namespace scheme makes that possible because the versions are distinct types. NLOHMANN_JSON_NAMESPACE_NO_VERSION opts out of version encoding when you specifically want cross-version source compatibility.

10. Test & Quality Infrastructure

Note

The example corpus doubles as documentation and a regression test: docs/Makefile's check_output_portable target compiles each example with -DJSON_USE_GLOBAL_UDLS=0 and diffs stdout, excluding a few platform-dependent ones (meta, max_size, std_hash, basic_json__CompatibleType). This is why the examples are trustworthy to copy verbatim — CI fails if they drift.

The project participates in OSS-Fuzz (continuous fuzzing of all six parsers), runs the suite under Valgrind, and uses astyle (tools/astyle) for enforced formatting.

11. Tooling

Tip

For day-to-day debugging, install the GDB pretty-printer (tools/gdb_pretty_printer/nlohmann-json.py) or the generated .natvis file. Without them, a basic_json shows as its raw union/tag members; with them you see the actual JSON value.

12. Security Analysis

This is a parsing library that routinely processes untrusted input, so its security posture matters to any integrator.

Warning

When parsing untrusted input at scale, prefer accept() (or sax_parse() with your own bounded consumer) over building a full DOM. A maliciously large or deeply nested document still consumes memory proportional to its size when fully materialized. Impose your own input-size limits upstream; the library does not cap document size for you.

Caution

JSON_NOEXCEPTION converts every error into abort(). In a service that must not crash, do not enable it without also supplying JSON_THROW_USER/JSON_TRY_USER/JSON_CATCH_USER hooks that route errors to your own recovery path — otherwise a single malformed request can take down the process.

13. Code Quality & Conventions

• Single-class architecture. Nearly all behavior hangs off basic_json; the public surface is intentionally narrow and STL-mirroring (begin/end, size, at, insert, erase, swap, comparison operators) so it composes with standard algorithms.
• Template-everything with defaults. Every storage type is a parameter, enabling ordered_json and fully custom instantiations without touching the core.
• SFINAE-heavy metaprogramming. detail/meta/ provides the type-trait and feature-detection layer (enable_if_t, is_compatible_type, detected, C++-version shims) that makes the implicit conversions and macro generators work across C++11–23.
• Doxygen @sa links. Every public member carries an @sa https://json.nlohmann.me/api/... link tying source to the rendered reference — the in-repo docs and the headers are kept in lockstep.
• Hedley macros provide portable compiler-attribute wrappers (JSON_HEDLEY_*) for warnings, likely/unlikely, and unused-result hints.
• Exception design. A single exception base with five typed subclasses, each error carrying a stable numeric id (101+/2xx/3xx/4xx/5xx) — ids are a public contract and don't change meaning across releases.

14. Extending the Library

Tip

The lightest-weight way to add per-value metadata (e.g. source positions, annotations) without forking the library is the CustomBaseClass template parameter — basic_json publicly derives from it. This is how JSON_DIAGNOSTIC_POSITIONS layers in start_pos()/end_pos() without bloating the default type.

15. Known Issues & Improvement Areas

Derived from the project's open issue tracker and source observations. These are integration-relevant caveats, not a changelog.

Note

None of the above blocks production use — the library is mature and extremely widely deployed. They are edge cases an integrator should know before enabling modules, JSON_NOEXCEPTION, or aggressive diagnostic flags in a large multi-library build.

16. Quick Reference

Integration (CMake)

find_package(nlohmann_json 3.12.0 REQUIRED)
target_link_libraries(app PRIVATE nlohmann_json::nlohmann_json)
# enable richer diagnostics for the whole target graph:
target_compile_definitions(app PRIVATE JSON_DIAGNOSTICS=1)

ABI-affecting macros (define once, build-wide)

JSON_DIAGNOSTICS · JSON_DIAGNOSTIC_POSITIONS · JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON · the inline-namespace version encoding.

Build & test the source tree

cmake -B build -DJSON_BuildTests=ON && cmake --build build -j && ctest --test-dir build -j

Regenerate the single header

# after editing include/nlohmann/** :
python3 tools/amalgamate/amalgamate.py -c <config> -s include  # then commit single_include/

Internal layer map

Exception id ranges