Extended JSON

Overview

In this guide, you can learn how to use the Extended JSON data format when interacting with MongoDB documents.

JSON is a human-readable data format that represents the values of objects, arrays, numbers, strings, booleans, and nulls. This format supports only a subset of BSON data types, which is the format that MongoDB uses to store data. The Extended JSON format supports more BSON types, defining a reserved set of keys prefixed with "$" to represent field type information that directly corresponds to each type in BSON.

To learn more about JSON, BSON, and Extended JSON, see the JSON and BSON resource and Extended JSON MongoDB Server manual entry.

Extended JSON Formats

MongoDB Extended JSON provides string formats to represent BSON data. Each format conforms to the JSON RFC and meets specific use cases.

The following table describes each Extended JSON format:

Name	Description
Canonical	A string format that avoids loss of BSON type information during data conversions. This format prioritizes type preservation at the loss of human-readability and interoperability with older formats. To specify this mode, pass `bsoncxx::ExtendedJsonMode::k_canonical` as a `mode` argument to the `to_json()` method.
Relaxed	A string format that describes BSON documents with some type information loss. This format prioritizes human-readability and interoperability at the loss of certain type information. To specify this mode, pass `bsoncxx::ExtendedJsonMode::k_relaxed` as a `mode` argument to the `to_json()` method.
Legacy	A string format that describes BSON documents with some type information loss. This format matches Relaxed Extended JSON with some exceptions. The C++ driver uses this mode by default.

Note

The C++ driver parses the $uuid Extended JSON type from a string to a b_binary object of binary subtype 4. For more information about $uuid field parsing, see the special rules for parsing $uuid fields section in the extended JSON specification.

Extended JSON Examples

The following examples show a document containing an ObjectId, date, and long number field represented in each Extended JSON format. Click the tab that corresponds to the format of the example you want to see:

{
  "_id": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": { "$numberLong": "1601499609" }},
  "numViews": { "$numberLong": "36520312" }
}

{
  "_id": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": "2020-09-30T18:22:51.648Z" },
  "numViews": 36520312
}

{
  "_id": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": "1601499771648" },
  "numViews": 36520312
}

Read Extended JSON

You can read an Extended JSON string into a C++ BSON document by calling the bsoncxx::from_json() method. This method parses an Extended JSON string and returns a bsoncxx::document::value containing the data.

The following example shows how you can read an Extended JSON string into a BSON document by using the from_json() method:

bsoncxx::document::value doc = bsoncxx::from_json(R"(
        {
            "_id": {"$oid": "507f1f77bcf86cd799439011"},
            "myNumber": {"$numberLong": "4794261"}
        }
    )");

Write Extended JSON

You can write an Extended JSON string by using the bsoncxx::to_json() method. By default, this method returns the Extended JSON string in the legacy format, but you can specify canonical or relaxed formats by passing a mode argument.

Note

Legacy Version

The legacy format option tells the C++ driver to serialize BSON types with the Libbson Legacy Extended JSON format. The driver uses this as the default mode.

For more information, see the Legacy Extended JSON page in the C Driver API documentation.

The bsoncxx::to_json() method is available for several core and standard library types, including array and document. The following example converts a document value into an Extended JSON string in the canonical format:

bsoncxx::builder::basic::document doc_builder;
doc_builder.append(kvp("myNumber", 11223344));
doc_builder.append(kvp("myString", "String value"));
bsoncxx::document::value doc = doc_builder.extract();
std::string json_str =
    bsoncxx::to_json(doc, bsoncxx::ExtendedJsonMode::k_canonical);
std::cout << json_str << std::endl;

{"myNumber":{"$numberInt":"11223344"},"myString":"String value"}

Additional Information

API Documentation

To learn more about the types and methods mentioned in this guide, see the following API documentation:

Server Manual Pages

To learn more about Extended JSON, see MongoDB Extended JSON (v2) in the MongoDB Server manual.

Back

BSON

Indexes