Extended JSON

On this page

Overview

Extended JSON Formats
Extended JSON Examples
Read Extended JSON
Write Extended JSON
API Documentation

Overview

JSON is a data format that represents the values of objects, arrays, numbers, strings, booleans, and nulls. The Extended JSON format defines a reserved set of keys prefixed with "$" to represent field type information that directly corresponds to each type in BSON, the format that MongoDB uses to store data.

To learn more about JSON, BSON, and Extended JSON, see our article about JSON and BSON and Extended JSON in the MongoDB Server manual.

Extended JSON Formats

MongoDB Extended JSON features different string formats to represent BSON data. Each of the different formats conform to the JSON RFC and meet specific use cases. The extended format, also known as the canonical format, features specific representations for every BSON type for bidirectional conversion without loss of information. The Relaxed mode format is more concise and closer to ordinary JSON, but does not represent all the type information such as the specific byte size of number fields.

See the following table to see a description of each format:

Name	Description
Extended	Also known as the canonical format, this JSON representation avoids loss of BSON type information. This format prioritizes type preservation at the loss of human-readability and interoperability with older formats.
Relaxed	JSON representation 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	JSON representation 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 BsonSerializer.Deserialize<T>() 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 = BsonSerializer.Deserialize<BsonDocument>(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 used on this page, see the following API documentation:

Back

BSON

Custom Types