jsoncons: a header-only C++ library for JSON and the formats shaped like it

One library for JSON and the formats shaped like it

The stated problem is broader than parsing JSON. jsoncons is a C++, header-only library for constructing JSON and JSON-like data formats, and the format list in the project description runs from the obvious ones to the exotic: JSON, CBOR, MessagePack, BSON, UBJSON, CSV and TOON, alongside the tooling layers of JSON Pointer, JSON Patch, JSON Schema, JSONPath and JMESPath. The design goal stated in the README is that the library has been designed to handle very large JSON texts, and that the reason is a SAX-style core. It can also read a whole JSON text into memory in a variant-like structure, so you are not forced to choose between streaming and a tree. The library offers three distinct access patterns for the same data, and choosing between them is the main design decision a user makes. The first is `basic_json`, described as a variant-like, allocator-aware data structure. The second is a strongly typed C++ data structure that implements jsoncons reflection traits, which lets a parser fill your own types instead of a generic tree. The third is cursor-level access to a stream of parse events, which the README compares to StAX pull parsing and push serializing in the XML world. On top of that, the library supports incremental parsing into a user's preferred types, using information about those types supplied by specializations of the reflection traits.

A data model that keeps types the format gave you

The jsoncons data model covers the familiar JSON types, meaning nulls, booleans, numbers, strings, arrays and objects, and adds byte strings on top. What matters more is semantic tagging. The library supports tagging of datetimes, epoch times, big integers, big decimals, big floats and binary encodings, and the README explains why: it allows the library to preserve those type semantics when parsing JSON-like formats that have them. CBOR is the clear example, since a tagged value there can mean something that plain JSON cannot express. If your pipeline ingests CBOR and emits JSON, this is the part of the library that stops a tagged number or a timestamp from collapsing into a string on the way through.

Getting the headers into your project

Installation is deliberately plain, because there is nothing to compile. The README offers the vcpkg platform library manager, which carries a jsoncons package, and the alternative of downloading the latest release, unpacking the zip and copying a directory into your include path. The directory to copy is named in the README as `include/jsoncons`:

include/jsoncons

Because the library is header only, that copy is the whole installation step. There is no build configuration to match your compiler flags and no library to link, which also means the compile time cost of including the parts you need is entirely in the headers you pull in. The project ships a `CMakeLists.txt` and a `cmake/` directory, so a CMake based project can consume it as a source dependency instead of copying files by hand.

Extensions for pointers, patches, schemas and queries

The extensions are where the library earns its keep in applications. `jsonpointer` implements the IETF standard JSON Pointer, `jsonpatch` implements the IETF standard JSON Patch, and `mergepatch` implements JSON Merge Patch. `jsonschema` implements Drafts 4, 6, 7, 2019-9 and 2020-12 of the JSON Schema specification, a range the README dates to version 0.174.0. For queries there are two: `jsonpath` implements Stefan Goessner's JSONPath and also supports search and replace with JSONPath expressions, while `jmespath` implements JMESPath, the query language for transforming JSON documents into other JSON documents. `csv` handles decode from and encode to CSV files, which is often where a JSON pipeline actually starts.

Binary formats: CBOR, MessagePack, BSON, UBJSON and TOON

The binary side is not a single codec but a family of them. `cbor` implements the IETF standard Concise Binary Object Representation, with extra support for stringref tags and for tags for typed arrays. `msgpack` implements MessagePack, `bson` implements the Binary JSON format, and `ubjson` implements the Universal Binary JSON Specification. `toon` was added more recently, decoding from and encoding to TOON-format and available since version 1.6.0. The pattern is consistent across all of them: because the underlying model understands semantic tags, a value that arrives as a tagged CBOR item can be surfaced as a datetime or a big integer rather than being flattened into a generic value.

Deprecated names and the macro that hides them

The library has been around long enough to carry its own history, and the project documents that openly. As jsoncons evolved, names sometimes changed, and the README points to a deprecated list. The transition policy is stated plainly: old names are deprecated but many of them continue to be supported. There is a switch for this. Defining the macro `JSONCONS_NO_DEPRECATED` suppresses the deprecated names entirely:

JSONCONS_NO_DEPRECATED

The README recommends that for new code. The practical reasoning is easy to see in a large codebase. Keeping deprecated declarations in the headers slows every compile that includes them, and the names add noise to overload resolution. For a maintained project, the migration is worth doing once, at a known point, rather than letting old symbols accumulate.

Boost Software Licence, and a release cadence you can plan around

The licence is stated in the README as the Boost Software License, which is a permissive licence requiring only that the notice and licence text accompany copies and redistributions. The repository metadata classifies the licence as Other because GitHub cannot map it to one of its own categories, so read the LICENSE file directly if your compliance process needs a specific identifier. The release line has been moving steadily: version 1.10.0 was published on 2026-10-05, after 1.9.0 on 2026-08-07 and 1.8.1 on 2026-06-09, and the last push was on 2026-10-15. The project is not archived. It also asks for support, with a donation and sponsorship options listed in the README, and it carries a SECURITY.md, a fuzzers directory and a `.clang-tidy` configuration.

Where the library sits against other JSON tooling

The honest comparison is not a head to head with another C++ library but a choice of approach. A DOM only parser gives you a tree and nothing else, which is fine for small payloads and awkward for a multi gigabyte document. jsoncons keeps the SAX core in the middle, so the tree is one consumer of the event stream rather than the only mode. For evaluation the project points at published comparisons rather than asking for trust: benchmarks against the JSONTestSuite and JSON_checker test suites, reports on text with integers and text with floating point numbers, with the benchmark code published in a separate repository, plus a JSONPath comparison page that compares its implementation against others. A separate mention is reflect-cpp, which is linked as another serialization option and is the closer fit if you only need struct mapping.

Editorial conclusion

Adopt jsoncons when your C++ service has to read very large JSON or swap between JSON and a binary encoding such as CBOR or MessagePack, since the SAX core and the format extensions cover both without a second dependency. Do not adopt it for a small project that only serialises a fixed struct, where a reflection library such as reflect-cpp would be less machinery. Verify first which header set you copy in, and define `JSONCONS_NO_DEPRECATED` if you are starting fresh, since the README notes many older names remain available and the macro is recommended for new code.

Frequently asked questions

Official sources

1. danielaparker/jsoncons on GitHub
2. Issues
3. Project website
4. README
5. Releases