Work with Extended JSON Data

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.

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 bit width of numeric fields.

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

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

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

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

Write Extended JSON

You can write an Extended JSON string from a BSON document object by using the EJSON.stringify() method.

The following example outputs an Extended JSON string in the Relaxed format:

import { Code, BSON } from 'mongodb';
const EJSON = BSON.EJSON;
const doc = {
   foo: [1, 2],
   bar: { hello: "world" },
   code: new Code("function x() { return 1; }", {}),
   date: new Date(2024, 6, 20, 10, 30, 0),
};
const ejsonStr = EJSON.stringify(doc);
console.log(ejsonStr);

{"foo":[1,2],"bar":{"hello":"world"},"code":{"$code":"function x() { return 1; }","$scope":{}},"date":{"$date":"2024-07-20T14:30:00Z"}}

By default, the stringify() method returns the Extended JSON string in the Relaxed format. To specify the Canonical format, set the relaxed option to false.

The following example shows how to output Extended JSON in the Canonical format:

import { Code, BSON } from 'mongodb';
const EJSON = BSON.EJSON;
const doc = {
   foo: [1, 2],
   bar: { hello: "world" },
   code: new Code("function x() { return 1; }", {}),
   date: new Date(2024, 6, 20, 10, 30, 0),
};
const ejsonStr = EJSON.stringify(doc, { relaxed: false });
print(ejsonStr)

{"foo":[{"$numberInt":"1"},{"$numberInt":"2"}],"bar":{"hello":"world"},"code":{"$code":"function x() { return 1; }","$scope":{}},"date":{"$date":{"$numberLong":"1721485800000"}}}

Read Extended JSON

You can read an Extended JSON string into the JavaScript value or object described by the string by using the EJSON.parse() method.

The following example shows how you can read an Extended JSON string into a JavaScript value or object by using the parse() method:

import { BSON } from 'mongodb';
const EJSON = BSON.EJSON;
const ejsonStr = `{
   "foo": [
      { "$numberInt": "1" },
      { "$numberInt": "2" }
   ],
   "bar": { "hello": "world" },
   "code": {
      "$code": "function x() { return 1; }",
      "$scope": {}
   },
   "bin": { "$binary": { "base64": "AQIDBA==", "subType": "00" } }
}`;
const doc = EJSON.parse(ejsonStr);
console.log(doc);

{
  foo: [ 1, 2 ],
  bar: { hello: 'world' },
  code: new Code('function x() { return 1; }', {}),
  bin: Binary.createFromBase64('AQIDBA==', 0)
}

API Documentation

To learn more about any of the methods or types discussed in this guide, see the EJSON API documentation.