[C++26] Reflection-based to_json/from_json: 672 lines replace NLOHMANN_DEFINE_TYPE_INTRUSIVE

[joker-charles]

TL;DR

I replaced NLOHMANN_DEFINE_TYPE_INTRUSIVE with a P2996 static reflection
codec on GCC 16 (-std=c++26 -freflection) and measured the trade-offs.

Headline results (single toolchain: g++-16 / nlohmann-json 3.12.0 / x86-64):

• Concepts modernization is free (~0–1% wall, ≤0.6% .o at target standard).
• Reflection saves 1 line per type and cannot silently omit members.
• At -O2, the flat struct path is size-identical to the macro version
  (same exe size at every N; text within 32 B).
• Runtime is never slower than macro on flat/shallow-nested types
  (nested paths ~13–19% faster).
• Unsupported types get one actionable static_assert (11 error lines)
  vs 238 (enable_if) / 376 (concepts) error cascades.
• The one-time cost is 672 lines (ADL-aware recursive codec) or 25 lines
  (naive flat-struct serializer). If the library ships the codec, user-side
  break-even is 1 type.

⚠️ These are single-toolchain measurements, not universal claims.
The methodology and same-toolchain relationships are the durable findings.

---

Why this matters

NLOHMANN_DEFINE_TYPE_INTRUSIVE has two known issues:

1. Silent omission — forget a member in the macro list and it's silently
   dropped from serialization with zero diagnostics.
2. One more thing to maintain — the member list duplicates what the
   compiler already knows.

P2996 reflection promises to solve both. The question I set out to answer:
what does it actually cost?

---

Full report

The complete measurement log, protocol details, and corrections are in the repo:
docs/static-reflection/EVALUATION.md

This discussion post is a summary. The full report includes:

• Complete measurement protocol (flags, scripts, raw runs)
• Corrections vs previous measurements (§5)
• All 38 probe checks and coverage boundary
• Runtime benchmark methodology and driver scripts

[nlohmann]

Thanks for the careful write-up. Measuring this on a real toolchain, with the method and your corrections included, is much more useful than guessing. The silent-omission problem with NLOHMANN_DEFINE_TYPE_* is real, and reflection is the natural fix, so I'm interested in where this goes.

I read the branch and your UPSTREAM_INTEGRATION_PLAN.md. To answer the question it plans to ask: yes, an opt-in, C++26-only extension behind a feature macro is something I'd consider. These conditions would apply:

1. A separate header that isn't included by default. Something like #include <nlohmann/reflection.hpp> that users include explicitly. It shouldn't be pulled into json.hpp or single_include. Without it, nothing changes for anyone.
2. Per-type opt-in. The struct [[=nlohmann::json_serializable{}]] S annotation in your plan is the right approach. Types that aren't annotated must behave exactly as they do today.
3. Public API only. Reflecting into basic_json's private members (json_value via unchecked()) is a no-go. It hasn't changed in a while, but it isn't a contract, and I don't want an extension that silently depends on the internal layout. The extension should build values through the normal public interface, just as a hand-written to_json/from_json would.
4. No changes to core headers in the same effort. The branch currently touches lexer.hpp, binary_reader.hpp, to_json.hpp/from_json.hpp and adds a C++20 concepts layer. Please keep those out of scope. The reflection extension should only add new headers. The binary-format work (msgpack/UBJSON/BSON via reflection) should also stay out, at least for now.
5. Start small. A first PR close to your 25-line flat-struct serializer is what I'd like to review. That means nested types through the normal ADL to_json/from_json, plus the actionable static_assert for unsupported members. Features like renaming or skipping members through annotations can follow once the core is settled. A 7,000-line codec isn't reviewable as one piece.
6. CI and compilers. Today only GCC 16 implements P2996 with -freflection. A GCC 16 CI job for the extension is fine, but I'd treat the feature as experimental until a second implementation exists, most likely Clang. The API may change until then.

Tests should go under tests/src/unit-*.cpp (doctest), gated on the feature macro. Documentation should go under docs/mkdocs/docs/, and your features/reflection.md page looks like a good start.

If this fits your plans, please open an issue proposing the minimal API (header name, annotation name, macro name) before writing more code. Then we can agree on the surface first.

(This reply was drafted with Claude Code and reviewed by me.)

[gregmarr]

Per-type opt-in. The struct [[=nlohmann::json_serializable{}]] S annotation in your plan is the right approach. Types that aren't annotated must behave exactly as they do today.

I agree that this is good approach. I was thinking of this as I was watching a reflection and serialization talk at CppCon a couple weeks ago. I wonder if it would make sense to mimic some of the C# json library annotations.