Extended JSON

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 byte size of number 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
}

{
  "_id": ObjectId("573a1391f29313caabcd9637"),
  "createdAt": ISODate("2020-09-30T18:22:51.648Z"),
  "numViews": NumberLong("36520312")
}

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

Read Extended JSON

You can read an Extended JSON string into a Python object by calling the bson.json_util.loads() method. This method parses an Extended JSON string and returns a Python list containing the data.

The following example shows how you can read an Extended JSON string into a list of dictionaries by using the loads() method:

from bson.json_util import loads
ejson_str = '''[
   {"foo": [1, 2]},
   {"bar": {"hello": "world"}},
   {"code": {
      "$scope": {},
      "$code": "function x() { return 1; }"
   }},
   {"bin": {
      "$type": "80",
      "$binary": "AQIDBA=="
   }}
]'''
doc = loads(ejson_str)
print(doc)

[
   {'foo': [1, 2]},
   {'bar': {'hello': 'world'}},
   {'code': Code('function x() { return 1; }', {})},
   {'bin': Binary(b'\x01\x02\x03\x04', 128)}
]

from bson.json_util import loads
doc = loads('{"b": {"$binary': b'this is a byte string'})
print(doc)

{u'b': Binary('this is a byte string', 0)}

from bson.json_util import loads
doc = loads('{"b": {"$binary': b'this is a byte string'})
print(doc)

{'b': b'this is a byte string'}

Write Extended JSON

You can write an Extended JSON string from a list of dictionaries by calling the bson.json_util.dumps() method. The following example outputs an Extended JSON string in the Relaxed format:

from bson import Code, Binary
from bson.json_util import dumps
doc = [
   {'foo': [1, 2]},
   {'bar': {'hello': 'world'}},
   {'code': Code('function x() { return 1; }', {})},
   {'bin': Binary(b'\x01\x02\x03\x04', 128)}
]
ejson_str = dumps(doc)
print(ejson_str)

'''[
   {"foo": [1, 2]},
   {"bar": {"hello": "world"}},
   {"code": {
      "$code": "function x() { return 1; }",
      "$scope": {}
   }},
   {"bin": {
      "$binary": {
         "base64": "AQIDBA==",
         "subType": "80"
   }}}
]'''

By default, the dumps() method returns the Extended JSON string in the Relaxed format. To specify a different format, pass one of the following values for the json_options parameter:

• CANONICAL_JSON_OPTIONS: Returns the Extended JSON string in Canonical format.

• LEGACY_JSON_OPTIONS: Returns the Extended JSON string in Legacy format. We recommend using Relaxed or Canonical format instead.

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

from bson import Code, Binary
from bson.json_util import dumps, CANONICAL_JSON_OPTIONS
doc = [
   {'foo': [1, 2]},
   {'bar': {'hello': 'world'}},
   {'code': Code('function x() { return 1; }', {})},
   {'bin': Binary(b'\x01\x02\x03\x04', 128)}
]
ejson_str = dumps(doc, json_options=CANONICAL_JSON_OPTIONS)
print(ejson_str)

'''[
   {"foo": [
      {"$numberInt": "1"},
      {"$numberInt": "2"}
   ]},
   {"bar": {"hello": "world"}},
   {"code": {
      "$code": "function x() { return 1; }",
      "$scope": {}
   }},
   {"bin": {
      "$binary": {
         "base64": "AQIDBA==",
         "subType": "80"
   }}}
]'''

Additional Information

The resources in the following sections provide more information about working with Extended JSON.