MongoDB Extended JSON (v2)

Disambiguation

The following page discusses MongoDB Extended JSON v2. Fordiscussion on the Legacy MongoDB Extended JSON v1, seeMongoDB Extended JSON (v1).

For mongo shell wrapper methods for types, seeData Types in the mongo Shell.

JSON can only directly represent a subset of the typessupported by BSON. To preserve type information, MongoDB addsthe following extensions to the JSON format.

• • Canonical Mode
  • A string format that emphasizes type preservation at the expenseof readability and interoperability. That is, conversion fromcanonical to BSON will generally preserve type information exceptin certain specific cases.
• • Relaxed Mode
  • A string format that emphasizes readability and interoperabilityat the expense of type preservation. That is, conversion fromrelaxed format to BSON can lose type information.

Both formats conform to the JSON RFC and can beparsed by the various MongoDB drivers and tools.

MongoDB Extended JSON v2 Usage

Drivers

The following drivers use the Extended JSON v2.0

For C# and Ruby that use Legacy MongoDB Extended JSON v1, refer toMongoDB Extended JSON (v1).

MongoDB Command-Line Tools

Starting in version 4.2:

BSON Data Types and Associated Representations

The following presents some common BSON data types and the associatedrepresentations in Canonical and Relaxed.

For a complete list, seehttps://github.com/mongodb/specifications/blob/master/source/extended-json.rst#conversion-table.

• Array

[ <elements> ]

<Same as Canonical>

• Binary

{ "$binary":   {      "base64": "<payload>",      "subType": "<t>"   }}

<Same as Canonical>

• Date

For dates between years 1970 and 9999, inclusive:

{"$date": {"$numberLong": "<millis>"}}

{"$date": "<ISO-8601 Date/Time Format>"}

For dates before year 1970 or after year 9999:

{"$date": {"$numberLong": "<millis>"}}

<Same as Canonical>

• Decimal128

New in version 3.4.

{ "$numberDecimal": "<number>" }

<Same as Canonical>

• Document

{ <content> }

<Same as Canonical>

• Double

For finite numbers:

{"$numberDouble": "<decimal string>" }

<non-integer number>

For infinite numbers or NAN:

{"$numberDouble": <"Infinity"|"-Infinity"|"NaN"> }

<Same as Canonical>

• Int64

{ "$numberLong": "<number>" }

<integer>

• Int32

{ "$numberInt": "<number>" }

<integer>

• MaxKey

{ "$maxKey": 1 }

<Same as Canonical>

The MaxKey BSON data type compares higher than all other types. SeeComparison/Sort Order for more information oncomparison order for BSON types.

• MinKey

{ "$minKey": 1 }

<Same as Canonical>

The MinKey BSON data type compares lower than all other types. SeeComparison/Sort Order for more information oncomparison order for BSON types.

• ObjectId

{ "$oid": "<ObjectId bytes>" }

<Same as Canonical>

• Regular Expression

{ "$regularExpression":   {      "pattern": "<regexPattern>",      "options": "<options>"  }}

<Same as Canonical>

• Timestamp

{"$timestamp": {"t": <t>, "i": <i>}}

<Same as Canonical>

Example