JSONCONS

jsoncons is a C++, header-only library for constructing JSON and JSON-like data formats such as CBOR. For each supported data format, it enables you to work with the data in a number of ways:

• As a variant-like, allocator-aware, data structure, basic_json

• As a strongly typed C++ data structure that implements jsoncons reflection traits

• With cursor-level access to a stream of parse events, somewhat analogous to StAX pull parsing and push serializing in the XML world.

Compared to other JSON libraries, jsoncons has been designed to handle very large JSON texts. At its heart are SAX-style parsers and serializers. It supports reading an entire JSON text in memory in a variant-like structure. But it also supports efficient access to the underlying data using StAX-style pull parsing and push serializing. And it supports incremental parsing into a user's preferred types, using information about user types provided by specializations of reflection traits.

The jsoncons data model supports the familiar JSON types - nulls, booleans, numbers, strings, arrays, objects - plus byte strings. In addition, jsoncons supports semantic tagging of datetimes, epoch times, big integers, big decimals, big floats and binary encodings. This allows it to preserve these type semantics when parsing JSON-like data formats such as CBOR that have them.

jsoncons is distributed under the Boost Software License.

jsoncons is free but welcomes support to sustain its development. If you find this library helpful, please consider making a one time donation or becoming a :heart: sponsor.

As the jsoncons library has evolved, names have sometimes changed, see deprecated. To ease transition, jsoncons deprecates the old names but continues to support many of them. The deprecated names can be suppressed by defining the macro JSONCONS_NO_DEPRECATED, and doing so is recommended for new code.

Extensions

• bson implements decode from and encode to the Binary JSON data format.
• cbor implements decode from and encode to the IETF standard Concise Binary Object Representation data format. In addition it supports tags for stringref and tags for typed arrays.
• csv implements decode from and encode to CSV files.
• jmespath implements JMESPath, a query language for transforming JSON documents into other JSON documents.
• jsonpatch implements the IETF standard JavaScript Object Notation (JSON) Patch
• mergepatch implements the IETF standard JSON Merge Patch
• jsonpath implements Stefan Goessner's JSONPath. It also supports search and replace using JSONPath expressions.
• jsonpointer implements the IETF standard JavaScript Object Notation (JSON) Pointer
• jsonschema implements Drafts 4, 6, 7, 2019-9 and 2020-12 of the JSON Schema Specification (since 0.174.0)
• msgpack implements decode from and encode to the MessagePack data format.
• toon implements decode from and encode to toon-format. (since 1.6.0)
• ubjson implements decode from and encode to the Universal Binary JSON Specification data format.

What users say

"Apache Kvrocks consistently utilizes jsoncons to offer support for JSON data structures to users. We find the development experience with jsoncons outstanding!"

"I have been using your library in my native language – R – and have created an R package making it easy for (a) JMESpath and JSONpath queries on JSON strings or R objects and (b) for other R developers to link to your library."

"I’m using your library for an external interface to pass data, as well as using the conversions from csv to json, which are really helpful for converting data for use in javascript"

"Verified that, for my needs in JSON and CBOR, it is working perfectly"

"the JSONPath feature of this library, it's great"

"We use JMESPath implementation quite extensively"

"We love your JSON Schema validator. We are using it in ER/Studio our data modelling tool to parse JSON Schema files so we can create entity relations models from them."

"the serialization lib of choice with its beautiful mappings and ease of use"

"really good" "awesome project" "very solid and very dependable" "my team loves it" "Your repo rocks!!!!!"

Mentions on the web

Get started with HealthImaging image sets and image frames using an AWS SDK

RubyGems.org   rjsoncons   CoppeliaSim   reflect-cpp

Benchmarks

• JSONTestSuite and JSON_checker test suites

• Performance benchmarks with text and integers

• Performance benchmarks with text and doubles

The benchmark code is available here.

JSONPath Comparison shows how jsoncons JsonPath compares with other implementations

Get jsoncons

You can use the vcpkg platform library manager to install the jsoncons package.

Or, download the latest release and unpack the zip file. Copy the directory include/jsoncons to your include directory. If you wish to use extensions, copy include/jsoncons_ext as well.

Or, download the latest code on main.

How to use it

• Quick guide
• Examples
• Reference
• Ask questions and suggest ideas for new features

The library requires a C++ Compiler with C++11 support. In addition the library defines jsoncons::endian, jsoncons::basic_string_view, jsoncons::optional, and jsoncons::span, which will be typedef-ed to their standard library equivalents if detected. Otherwise they will be typedef-ed to internal, C++11 compatible, implementations.

The library uses exceptions and in some cases std::error_code's to report errors. Apart from jsoncons::assertion_error, all jsoncons exception classes implement the jsoncons::json_error interface. If exceptions are disabled or if the compile time macro JSONCONS_NO_EXCEPTIONS is defined, throws become calls to std::terminate.

Examples

Working with JSON data

Working with CBOR data

<div id="E1"/>

Working with JSON data

For the examples below you need to include some header files and initialize a string of JSON data:

#include <jsoncons/json.hpp>
#include <jsoncons_ext/jsonpath/jsonpath.hpp>
#include <iostream>

using namespace jsoncons; // for convenience

std::string data = R"(
    {
       "application": "hiking",
       "reputons": [
       {
           "rater": "HikingAsylum",
           "assertion": "advanced",
           "rated": "Marilyn C",
           "rating": 0.90,
           "generated": 1514862245
         }
       ]
    }
)";

jsoncons allows you to work with the data in a number of ways:

• As a variant-like data structure, basic_json

• As a strongly typed C++ data structure that implements jsoncons reflection traits

• With cursor-level access to a stream of parse events

As a variant-like data structure

int main()
{
    // Parse the string of data into a json value
    json j = json::parse(data);

    // Does object member reputons exist?
    std::cout << "(1) " << std::boolalpha << j.contains("reputons") << "\n\n";

    // Get a reference to reputons array 
    const json& v = j["reputons"]; 

    // Iterate over reputons array 
    std::cout << "(2)\n";
    for (const auto& item : v.array_range())
    {
        // Access rated as string and rating as double
        std::cout << item["rated"].as<std::string>() << ", " << item["rating"].as<double>() << "\n";
    }
    std::cout << "\n";

    // Select all "rated" with JSONPath
    std::cout << "(3)\n";
    json result = jsonpath::json_query(j,"$..rated");
    std::cout << pretty_print(result) << "\n\n";

    // Serialize back to JSON
    std::cout << "(4)\n" << pretty_print(j) << "\n\