Back to Updates
DevTool Team

Turning JSON into C++ Structs: Choosing a Library, Type Inference, and the Real Nesting Boundary

Converting an API's JSON into C++ structs starts with the library choice, not the button: most projects take nlohmann/json (smoothest ecosystem), performance-critical parsing takes RapidJSON, Boost shops take Boost.JSON. This guide covers the options (C++ standard, naming style, namespace) and the five blind spots of type inference — integers always infer to int (13-digit timestamps overflow; change to int64_t), null becomes optional<string>, empty arrays default to vector<string>, mixed arrays infer from the first element, and nested objects do NOT expand into sub-structs but land as nlohmann::json dynamic types. Plus the NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE macro's binding to your fields, and verifying the plain struct by pasting it into an online C++ compiler.

Pick the library first: three options by project

The first decision in generating C++ structs isn't clicking the button — it's choosing the JSON library, which determines the shape of the generated code (using this site's JSON to C++ Converter as the example):

Your project Pick Why
New project, no special performance needs nlohmann/json (recommended default) Closest to writing Python, clean exception semantics, single-header include, full macro ecosystem
Parse-performance sensitive (large payloads at high frequency) RapidJSON SAX-style allocation-free parsing is fast; the cost is a verbose API and manual memory management
Already in the Boost ecosystem Boost.JSON Plays well with Boost.Asio et al., one less dependency

Companion options: C++ standard (11/14/17/20 — std::optional needs 17; choosing 11 degrades), naming style (camelCase/snake_case per team convention), namespace and struct name per project. Comments and getters/setters are optional emissions.

Type inference rules and five blind spots

The generator infers from your sample — rules and gaps in one table:

JSON value Inferred C++ type Blind spot
42 int 32-bit ceiling — 13-digit timestamps overflow; change to int64_t
3.14 double Don't use floating point for money; fixed-point cents
"text" std::string —
true bool —
null std::optional<std::string> Semantics are "unknown type, fall back to string" — the real type may be numeric; fix per docs
[] std::vector<std::string> Empty arrays reveal no element type; the string default needs correcting per docs
[1, 2] std::vector<int> First element only — [1, \"a\"] infers vector<int>; mixed arrays are an API design problem
{...} nlohmann::json Dynamic pass-through, no sub-struct generated — see below

The most important boundary: nested objects do not expand into sub-structs. The generator types nested-object fields directly as nlohmann::json — any nesting is covered and can't be mis-inferred, but nested fields lose compile-time checking and access goes through runtime json[\"key\"]. For strong typing, paste the sub-object in separately, generate again, and assemble by hand — worth it for stable hierarchies; dynamic typing is genuinely more comfortable for varying shapes.

The serialization macro: the maintenance point of generated code

Choosing nlohmann also generates NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(StructName, field1, field2, ...) — the macro auto-generates to_json/from_json, giving your struct JSON interconversion.

Memorize the binding: the macro's field list must exactly match the struct members. Three classic failures:

  • Field added, macro forgotten — serialization silently drops the field;
  • Naming style switched (camelCase→snake_case) — struct members changed, the macro list must sync;
  • Field renamed — the old name in the macro fails to compile, which is actually a favor: at least it isn't silent.

Verification: two stages

Generated code splits into two parts with different verification paths:

  • Plain struct part (field definitions, dependency-free standard C++): paste into the online C++ compiler and run a main — print sizeof(Struct) and the fields; layout, alignment, and spelling verify at a glance;
  • Serialization part (macro + nlohmann dependency): compile in a local project and run one round trip (struct→json→struct, compare fields) — more reliable than eyeballing the macro.

The truth: a generated struct is a starting point

  • The sample decides the types: inference sees only the JSON you pasted — null fields, empty arrays, and nested objects are all "insufficient information" signals; reconcile against the API docs or several real samples before it enters the project;
  • int overflow is a C++-specific trap: Java at least has Long to fall back on; C++ int is 32 bits — walking through ID and timestamp fields is a required finishing step;
  • Mixed-type arrays go back to the API owner: [1, \"a\"] inferring vector<int> compiles fine and blows up at runtime — that interface needs fixing, not the C++ side.

Frequently Asked Questions

Why is a nested object's field typed nlohmann::json instead of a sub-struct?

The generator handles nested objects with dynamic pass-through: the field becomes nlohmann::json and the subtree flows through serialization as-is — any nesting works, but nested fields lose compile-time checking. For strongly-typed sub-structs, generate the sub-object separately and assemble by hand — worth it for stable hierarchies; dynamic typing is more comfortable for varying shapes.

What about integer fields like 13-digit timestamps?

The generator infers every integer as int — typically 32-bit with a ceiling around 2.1 billion, and 13-digit millisecond timestamps and snowflake IDs all overflow. Any JSON integer past 10 digits becomes int64_t by hand. Check neighboring fields — created_at and updated_at usually share a type. Money fields shouldn't use double either; fixed-point cents beat floating point.

How do I quickly verify a generated struct?

The plain struct part is dependency-free standard C++ — paste it into an online C++ compiler and run a main printing sizeof and the fields; layout, alignment, and spelling verify at a glance. The macro-bearing serialization code depends on the nlohmann header — verify locally by compiling and running one round trip.

What is the NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE macro, and what must change when fields change?

It's a macro from nlohmann/json that auto-generates to_json/from_json for your struct — you list the field names inside it. The critical binding: the macro's field list must exactly match the struct members — adding a field without updating the macro silently drops it from serialization; after a naming-style switch, the old names in the macro must be updated in sync.