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
Extended or 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.
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. The .NET/C# Driver uses Relaxed mode by default.
Shell	A string format that matches the syntax used in the MongoDB shell. This format prioritizes compatibility with the MongoDB shell, which often uses JavaScript functions to represent types.

Note

The .NET/C# Driver parses the $uuid Extended JSON type from a string to a BsonBinary 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": ObjectId("573a1391f29313caabcd9637"),
  "createdAt": ISODate("2020-09-30T18:22:51.648Z"),
  "numViews": NumberLong("36520312")
}

Read Extended JSON

You can read an Extended JSON documents into a C# object by using the BsonDocument.Parse() method. The following example reads an Extended JSON document into a BsonDocument object:

var ejson = "{\n\"_id\": { \"$oid\": \"573a1391f29313caabcd9637\" },\n  \"createdAt\": { \"$date\": { \"$numberLong\": \"1601499609\" }},\n\"numViews\": { \"$numberLong\": \"36520312\" }\n}\n\n";
var document = BsonDocument.Parse(ejson);
Console.WriteLine(document.ToJson());

{ "_id" : { "$oid" : "573a1391f29313caabcd9637" }, "createdAt" : { "$date" : "1970-01-19T12:51:39.609Z" }, "numViews" : 36520312 }

Write Extended JSON

You can write an Extended JSON string by calling the ToJson() method on a BsonDocument object or custom class. You must specify a JsonWriterSettings object with the OutputMode property set to the desired Extended JSON format as a parameter.

Consider the following custom class:

public class MyDocument
{
    public ObjectId Id { get; set; }
    public DateTime CreatedAt { get; set; }
    public long NumViews { get; set; }
}

The following example outputs an instance of MyDocument in Extended JSON format by specifying the CanonicalExtendedJson value as an OutputMode property:

var document = new MyDocument();
document.Id = ObjectId.GenerateNewId();
document.CreatedAt = DateTime.UtcNow;
document.NumViews = 1234567890;
var json = document.ToJson(new JsonWriterSettings
{
    OutputMode = JsonOutputMode.CanonicalExtendedJson
});
Console.WriteLine(json);

{ "_id" : { "$oid" : "68094769744af81f368ff1c1" }, "CreatedAt" : { "$date" : { "$numberLong" : "1745438569994" } }, "NumViews" : { "$numberLong" : "1234567890" } }

API Documentation

To learn more about the methods and classes you can use to work with JSON documents, see the following API documentation:

Back

BSON

Integrations