taoJSON: a header-only C++ JSON library built in two layers

One JSON core that also speaks five other formats

taoJSON is a C++ header-only JSON library from The Art of C++ project, and its stated scope goes past reading and writing JSON text. It provides a generic Value Class, uses Type Traits to interoperate with C++ types, and uses an Events Interface to convert from and to JSON, JAXN, CBOR, MsgPack and UBJSON. The audience is C++ developers working on services or embedded clients that have to speak more than one serialisation format, and who would otherwise bolt a second library onto an existing one. It is also a working example of the Parsing Expression Grammar Template Library, which the project uses for parsing the JSON and JAXN representation formats, so the PEGTL checkout in external/ is not incidental to the design. The library targets C++17 for the 1.x documentation line, and CI badges cover Windows, macOS, Linux and Android.

Two layers instead of one DOM: Value and Events

The central architectural decision is the split between two abstraction levels. The Value Class is the familiar document object model: a JSON data model extended with non-finite number values and binary data, built around STL containers such as std::variant, std::string, std::map and std::vector, with objects and arrays constructed through std::initializer_list. The Events Interface is the lower level, a straightforward and flexible API for streaming input and output, with Events-to-Value and Value-to-Events bridges, and Events transformers that manipulate events on the fly. Reading a document can therefore stop at events if you want a single pass, or be materialised into a Value tree if you want random access. The Value class performs no memory allocations of its own, though the wrapped containers allocate as usual, and strings, binary data and user-defined types can be shared through non-owning pointers.

Type traits carry user-defined types without a code generator

The Type Traits mechanism is how the library moves between JSON and application types. Rather than requiring a macro or a generated serialiser, a type describes its own conversion to and from the Value model, and the same description can be reused by the Events layer. Instance sharing for user-defined types through non-owning pointers extends the same idea to lifetimes, so a large object can be referenced from several places in a document without copying. The Value class also offers an optional base class, documented as an advanced use case, which is the extension point for annotating sub-values with a file name and line number, something that turns a parser into something closer to a diagnostic tool. The trade-off is that traits are boilerplate per type, and the documentation is a separate file from the Value Class page, so both have to be read before the first conversion is written.

JSON Pointer, JSON Patch and validation sit on the Events layer

The specification coverage is broader than the word JSON suggests. The project lists RFC8259 and ECMA-404 for the JSON data interchange format, RFC6901 for JSON Pointer and RFC6902 for JSON Patch, RFC7049 for CBOR, and the JAXN relaxed JSON format, MsgPack without extensions, and UBJSON. On top of the data model it offers comparison, hashing, counting and schema validation over events, plus transformers that can rewrite events as they flow. That ordering is deliberate. Pointer and Patch operate on document locations, so implementing them against a streaming representation avoids building a full tree first, and the same machinery is what makes the binary format conversions possible. The README states that the library achieves a 100% conformance score in the Native JSON Benchmark tests, which the project credits to Milo Yip for providing the reference to measure progress against.

Getting the headers and building the test suite

Because the library is header-only, the practical question is how the headers reach your build. The project points at the Conan package manager for that, and the documented command names a specific version of the package:

    conan install taocpp-json/1.0.0-beta.11@

Note that the command pins beta.11 while the newest tagged release in the repository list is 1.0.0-beta.14, so the command in the README is behind the releases. The project says the Conan package is kept up to date by Conan team members and community contributors, and asks that an out-of-date version be reported as an issue or pull request against the Conan Center Index repository. The repository itself builds with a plain Makefile, and the flag defaults in that Makefile are where the C++ standard and warning policy are set:

CXXSTD := -std=c++17
CPPFLAGS ?= -pedantic -Iinclude -Iexternal/PEGTL/include
CXXFLAGS ?= -Wall -Wextra -Wshadow -Werror -O3 $(MINGW_CXXFLAGS)

The default target compiles and then runs the unit tests, and the include paths show that the PEGTL headers under external/PEGTL/include are expected next to the library headers.

Conversion paths to other JSON libraries

Teams migrating from an existing JSON stack have a middle path. The Events layer supports conversion from and to other JSON libraries, and the repository ships contrib/nlohmann.cpp for exactly that purpose, while the README credits Niels Lohmann and the nlohmann JSON library as the inspiration for taoJSON. That means switching a codebase does not have to be a single cutover: you can move to the Events interface while a translation layer handles the older calls. The difference in approach is worth naming. A Value-centric library treats the document tree as the primary object and streams as an add-on, while taoJSON keeps the event stream primary and treats the Value class as one materialisation of it, which is what makes the binary format conversions and the on-the-fly transformers natural rather than bolted on. The cost is a larger API surface to learn, and the documentation itself warns that it is not quite keeping pace with the development.

Still a beta three years after the last tagged release

The status section draws an unusual distinction. The library is described as stable in the sense of works correctly over months of multiple real-world applications, and as not stable in the sense of under construction, with some parts of the API under discussion and development that might change or be extended before version 1.0. The release history supports that caution: the tagged versions are 1.0.0-beta.12 from 2020-12-23, 1.0.0-beta.13 from 2021-09-23 and 1.0.0-beta.14 from 2023-04-30, and there is no 1.0.0 tag. The last push to the default branch was on 2026-10-15, so work continues on main even though no new tag has been cut since 2023. Licensing is the simple half of the story: the project is MIT licensed and states that it may be used for any purpose, including commercial purposes, with the copyright notice held by Dr. Colin Hirsch and Daniel Frey. The repository also bundles third-party licenses for double-conversion, itoa and ryu, which is what a vendored dependency set looks like in practice.

Editorial conclusion

taoJSON fits C++ teams that need one JSON core to serve several wire formats, or that want a DOM plus a streaming layer in the same library, and the MIT licence lets it ship inside commercial products without separate terms. It is the wrong choice for a project that wants a settled API, since the newest tagged release is still 1.0.0-beta.14 and the status section says parts of the API might change before version 1.0. Before adopting it, read the version 1.x documentation and check that the Events-based features you need, such as JSON Patch and schema validation, are the ones you will actually use rather than the Value shortcuts.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. taocpp/json on GitHub