MongoDB Extended JSON (v2)

MongoDB Extended JSON v2 Usage

BSON Data Types and Associated Representations

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

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

Array

[ <elements> ]

<Same as Canonical>

Where the array elements are as follows:

• <elements>

  • Array elements use Extended JSON.

  • To specify an empty array, omit the content [ ].

Binary

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

<Same as Canonical>

Where the values are as follows:

• "<payload>"

  • Base64 encoded (with padding as "=") payload string.

• "<t>"

  • A one- or two-character hex string that corresponds to a BSON binary subtype. See the extended bson documentation http://bsonspec.org/spec.html for subtypes available.

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>

Where the values are as follows:

• "<millis>"

  • A 64-bit signed integer as string. The value represents milliseconds relative to the epoch.

• "<ISO-8601 Date/Time Format>"

  • A date in ISO-8601 Internet Date/Time Format as string.

  • The date/time has a maximum time precision of milliseconds:

    • Fractional seconds have exactly 3 decimal places if the fractional part is non-zero.

    • Otherwise, fractional seconds SHOULD be omitted if zero.

Decimal128

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

<Same as Canonical>

Where the values are as follows:

• "<number>"

  • A high-precision decimal as a string.

Document

{ <content> }

<Same as Canonical>

Where the document contents are as follows:

• <content>

  • Name:value pairs that use Extended JSON.

  • To specify an empty document, omit the content { }.

Double

For finite numbers:

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

<non-integer number>

For infinite numbers or NAN:

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

<Same as Canonical>

Where the values are as follows:

• "<decimal string>"

  • A 64-bit signed floating point as a string.

• <non-integer number>

  • A non-integer number. Integer numbers are parsed as an integer instead of a double.

Int64

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

<integer>

Where the values are as follows:

• "<number>"

  • A 64-bit signed integer as string.

• <integer>

  • A 64-bit signed integer.

Int32

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

<integer>

Where the values are as follows:

• "<number>"

  • A 32-bit signed integer as a string.

• <integer>

  • A 32-bit signed integer.

MaxKey

{ "$maxKey": 1 }

<Same as Canonical>

The MaxKey BSON data type compares higher than all other types. See Comparison/Sort Order for more information on comparison order for BSON types.

MinKey

{ "$minKey": 1 }

<Same as Canonical>

The MinKey BSON data type compares lower than all other types. See Comparison/Sort Order for more information on comparison order for BSON types.

ObjectId

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

<Same as Canonical>

Where the values are as follows:

• "<ObjectId bytes>"

  • A 24-character, big-endian hexadecimal string that represents the ObjectId bytes.

Regular Expression

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

<Same as Canonical>

Where the values are as follows:

• "<regexPattern>"

  • A string that corresponds to the regular expression pattern. The string can contain valid JSON characters and unescaped double quote (") characters, but may not contain unescaped forward slash (/) characters.

• "<options>"

  • A string that specifies BSON regular expression options ('g', 'i', 'm' and 's') or an empty string "".

  • Options other than ('g', 'i', 'm' and 's') will be dropped when converting to this representation.

  Important

  The options MUST be in alphabetical order.

Timestamp

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

<Same as Canonical>

Where the values are as follows:

• <t>

  • A positive integer for the seconds since epoch.

• <i>

  • A positive integer for the increment.

Example