Add json_document and json_view: parse, accept, types, materialize

[nlohmann]

Part of the stack for the zero-copy view (#5295). This PR adds the new header <nlohmann/json_view.hpp> with the public classes, built on the parser from the PR below. Element access, values, dump(), and comparisons follow in the next PRs, so each one stays reviewable.

Summary

json_document parses JSON text into a compact, read-only index. json_view is a cheap handle to one value in it. Strings and numbers are not copied out of the text.

#include <nlohmann/json_view.hpp>

std::string text = receive();
auto doc = nlohmann::json_document::parse(text);   // borrows text
nlohmann::json_view root = doc.root();
if (root.is_object() && !root.empty())
{
    nlohmann::json j = root.materialize();          // the value json::parse(text) returns
}

• basic_json_document<BasicJsonType>: parse, parse_copy, accept, read (reuses the document's memory), root, is_discarded, source, owns_source, node_count, memory_usage, shrink_to_fit.
• basic_json_view<BasicJsonType>: type, the is_* queries, operator bool, size, empty, materialize, source_offset.
• Aliases: json_document, json_view, ordered_json_document, ordered_json_view.
• Input:
  • borrowed: lvalue contiguous byte containers, std::string_view, C strings, character arrays, pointer ranges, and (in C++20) other contiguous iterator ranges;
  • owned: an rvalue std::string (moved in) and anything else parse() accepts (copied or read).
• Errors: a parse error throws the exception basic_json::parse would throw for the same input. The library parser is run on the failing input (a cold path), so message, position, and id are the same. Inputs of 4 GiB or more are rejected with the new out_of_range.416.
• Floats are converted when read, with the library's converter from Speed up the lexer: own float parser, string scan, and \u table #5738: the value does not depend on the locale at the time of the access, and reading a float or double does not allocate.
• materialize(): builds the value with the SAX handler parse() uses, so JSON_DIAGNOSTICS parent pointers are set as usual.

Changes

area	files
header	include/nlohmann/json_view.hpp, detail/view/{errors,input,materialize,number}.hpp, single_include/nlohmann/json_view.hpp (amalgamated with the external key from the first PR of the stack, so it includes json.hpp instead of copying it)
build	Makefile (amalgamate, check-amalgamation, include.zip, release), cmake/ci.cmake, check_amalgamation.yml, meson.build, Bazel, the C++20 module, labeler.yml
tests	unit-json_view.cpp, unit-json_view_macros.cpp, fuzzer-parse_json_view.cpp
benchmarks	tests/benchmarks/src/benchmarks_view.cpp (ViewParse, ViewRead, ViewParseIndented, ViewAccept, ViewMaterialize; built only if the header exists) and Accept for json::accept
docs	API pages for both classes and the aliases, features/json_view.md with a "which representation to choose" section (linked from the feature overview, last in the Features navigation), 23 examples, the exceptions page, README, and a "Node index of JSON views" section on the architecture page (the 16-byte node: fields, navigation, and a worked example), linked from the feature page and the pages that mention the 16 bytes

Tests

• unit-json_view.cpp:
  • materialize() equals parse() for handwritten and generated documents, with duplicate keys, 100,000 levels of nesting, and JSON_DIAGNOSTICS parents;
  • parse errors equal parse()'s, message included, for malformed inputs under all option combinations;
  • every input kind, borrowed or owned;
  • reuse with read(), moves, shrink_to_fit(), and source offsets.
• unit-json_view_macros.cpp: includes the header without JSON_TEST_KEEP_MACROS, as users do. It checks that the view does not rely on macros json.hpp undefines, and that none of its own NLOHMANN_VIEW_* macros leak.
• Fuzzer: accept, value, and exception parity with json::parse; 637,000 runs without a finding at this PR, and 14.5 million on the complete stack.

Benchmarks

tests/benchmarks at this PR (Google Benchmark, Apple M1, median of 5):

file	json::parse	json_document::parse	speedup	json::accept	json_document::accept	speedup
jeopardy	151.7 ms	26.1 ms	5.8×	82.0 ms	26.1 ms	3.1×
canada	9.18 ms	1.03 ms	8.9×	6.16 ms	1.03 ms	6.0×
citm_catalog	3.13 ms	0.42 ms	7.5×	2.03 ms	0.42 ms	4.9×
twitter	1.48 ms	0.24 ms	6.1×	0.80 ms	0.24 ms	3.3×

materialize() of the whole document (ViewMaterialize) takes 80.1, 4.65, 1.06, and 0.72 ms. So even when a json value is needed in the end, json_document::parse followed by materialize() is 1.4–2.1× faster than json::parse.

x86-64 numbers are still missing.

Public API

No breaking change. This PR adds a new header, new class templates, and the exception id out_of_range.416; nothing existing changes. The C++20 module exports the new names. The label aspect: json_view used by labeler.yml has to be created in the repository.

---

Written by Claude Code.

🤖 Generated with Claude Code

[nlohmann]

CI fixes for this PR (commits a8e9ce9 and 94cd91c, plus the fixes from #5617/#5618/#5620 merged in):

• check (Check amalgamation): FileNotFoundError: .../tools/tools/amalgamate/config_json_view.json. The workflow runs develop's amalgamate.py and read all configs from the develop checkout, where config_json_view.json does not exist yet. That config is now read from the PR checkout ($MAIN_DIR/tools/amalgamate/config_json_view.json); the tool is still develop's. No other step of the workflow reads from $TOOL_DIR. Remaining dependency: develop's amalgamate.py does not know the "external" key yet (Keep external headers as #include when amalgamating #5615). Until Keep external headers as #include when amalgamating #5615 is on develop, this job regenerates json_view.hpp with json.hpp inlined and will fail on the diff. I checked this locally with develop's tool. It resolves itself once Keep external headers as #include when amalgamating #5615 lands.
• ci_cmake_options (ci_test_noexceptions): test-json_view aborted in "parse errors are those of parse()". parse_exception()/view_exception() catch outside a CHECK_THROWS, and with JSON_NOEXCEPTION the first parse error calls abort(). Those comparisons are now compiled only without JSON_NOEXCEPTION, as in unit-class_parser.cpp.
• ci_test_gcc (hidden behind the inherited lexer errors): -Werror=unused-result for CHECK_THROWS_AS(json_document::parse(...)). The result is assigned to a dummy document.
• ci_test_compilers_clang (3.6): const json_view invalid; needs a user-provided default constructor on old clang (CWG 253). It is now value-initialized with {}. The same fix was applied to the later tests in Add element access, iteration, values, and JSON pointers to json_view #5622, Add values and JSON pointers to json_view #5623 and Add images of json_documents: save() and load() #5632.
• ci_test_single_header: unit-json_view_builder.cpp now includes <nlohmann/json_view.hpp> (which contains the internal view headers) in single-header mode. The exclusion from Add json_document and json_view: node index, parser, and document #5620 is removed.
• single_include/nlohmann/json_view.hpp was regenerated for the builder change merged from Add json_document and json_view: node index, parser, and document #5620.
• msvc Win32 / clang_tidy / gcc standards: inherited, fixed in Convert floats with Eisel-Lemire when std::from_chars is unavailable #5617/Find the stop byte of a string run without a byte loop #5618/Add json_document and json_view: node index, parser, and document #5620. clang 14 [Windows]: infra (a curl certificate revocation check was offline).

Verified with gcc:16 (linux/amd64) and the CI flags (C++11 and C++20), and with a JSON_NOEXCEPTION build run as --no-throw: unit-json_view, unit-json_view_macros and unit-json_view_builder pass. make amalgamate leaves the tree clean.

— posted by Claude Code on behalf of @nlohmann

[github-actions]

🔴 Amalgamation check failed! 🔴

The source code has not been amalgamated and/or formatted correctly, or BUILD.bazel is out of date.

[nlohmann]

Restacked #5621–#5635 onto the current json-view/08-view-builder (e96e2982a), which now contains develop's json_literals.hpp (#5610). The old branches conflicted with it.

Conflicts (only in this PR, 10-view-document): develop added json_literals.hpp in the same places where this PR adds json_view.hpp. Every resolution keeps both:

• Makefile: amalgamate/pretty/zip/check-amalgamation/release targets and shasum list
• BUILD.bazel, meson.build, src/modules/json.cppm
• .github/workflows/check_amalgamation.yml, cmake/ci.cmake
• docs/mkdocs/docs/integration/index.md

The upper 14 branches rebased without conflicts; git range-diff shows no content changes beyond the resolutions above.

Checked before pushing, for every branch head:

• Regenerating single_include/ (json.hpp, json_fwd.hpp, json_literals.hpp, json_view.hpp) and BUILD.bazel changes nothing.
• unit-json_view*, unit-udl and unit-no_automatic_udls pass with Clang at C++11 and C++17.
• 10 and 24 also compile with GCC 16 using CI's warning flags, at C++11 and C++20.

Pushed with --force-with-lease against the previous heads; the old heads are kept locally as backup refs.

— posted by Claude Code on behalf of @nlohmann

[nlohmann]

The zero-copy view stack (#5295) was rebased onto develop and regrouped from 20 PRs into 10, one squashed commit each. The changes of this PR are now in #5620; its review comments stay here for reference.

---

Written by Claude Code.