OPTIONS

MongoDB Extended JSON

JSON can only represent a subset of the types supported by BSON. To preserve type information, MongoDB adds the following extensions to the JSON format:

  • Strict mode. Strict mode representations of BSON types conform to the JSON RFC. Any JSON parser can parse these strict mode representations as key/value pairs; however, only the MongoDB’s internal JSON parser also recognizes the type information conveyed by the format.
  • mongo Shell mode. The MongoDB’s internal JSON parser and the mongo shell can parse this mode.

The representation used for the various data types depends on the context in which the JSON is parsed.

Parsers and Supported Format

Input in Strict Mode

The following can parse representations in strict mode with recognition of the type information.

Other JSON parsers, including mongo shell and db.eval(), can parse strict mode representations as key/value pairs, but without recognition of the type information.

Input in mongo Shell Mode

The following can parse representations in mongo shell mode with recognition of the type information.

Output in Strict mode

mongoexport and REST and HTTP Interfaces output data in Strict mode.

Output in mongo Shell Mode

bsondump outputs in mongo Shell mode.

BSON Data Types and Associated Representations

The following presents the BSON data types and the associated representations in Strict mode and mongo Shell mode.

Binary

data_binary
Strict Mode   mongo Shell Mode
{ "$binary": "<bindata>", "$type": "<t>" }
 
BinData ( <t>, <bindata> )
  • <bindata> is the base64 representation of a binary string.
  • <t> is the hexadecimal representation of a single byte that indicates the data type. See the extended bson documentation. http://bsonspec.org/spec.html

Date

data_date
Strict Mode   mongo Shell Mode
{ "$date": <date> }
 
new Date ( <date> )

<date> is the JSON representation of a 64-bit signed integer for milliseconds since epoch UTC (unsigned before version 1.9.1).

Timestamp

data_timestamp
Strict Mode   mongo Shell Mode
{ "$timestamp": { "t": <t>, "i": <i> } }
 
Timestamp( <t>, <i> )
  • <t> is the JSON representation of a 32-bit unsigned integer for seconds since epoch.
  • <i> is a 32-bit unsigned integer for the increment.

Regular Expression

data_regex
Strict Mode   mongo Shell Mode
{ "$regex": "<sRegex>", "$options": "<sOptions>" }
 
/<jRegex>/<jOptions>
  • <sRegex> is a string of valid JSON characters.
  • <jRegex> is a string that may contain valid JSON characters and unescaped double quote (") characters, but may not contain unescaped forward slash (/) characters.
  • <sOptions> is a string containing the regex options represented by the letters of the alphabet.
  • <jOptions> is a string that may contain only the characters ‘g’, ‘i’, ‘m’ and ‘s’ (added in v1.9). Because the JavaScript and mongo Shell representations support a limited range of options, any nonconforming options will be dropped when converting to this representation.

OID

data_oid
Strict Mode   mongo Shell Mode
{ "$oid": "<id>" }
 
ObjectId( "<id>" )

<id> is a 24-character hexadecimal string.

DB Reference

data_ref
Strict Mode   mongo Shell Mode
{ "$ref": "<name>", "$id": "<id>" }
 
DBRef("<name>", "<id>")
  • <name> is a string of valid JSON characters.
  • <id> is any valid extended JSON type.

Undefined Type

data_undefined
Strict Mode   mongo Shell Mode
{ "$undefined": true }
 
undefined

The representation for the JavaScript/BSON undefined type.

MinKey

data_minkey
Strict Mode   mongo Shell Mode
{ "$minKey": 1 }
 
MinKey

The representation of the MinKey BSON data type that compares lower than all other types. See What is the compare order for BSON types? for more information on comparison order for BSON types.

MaxKey

data_maxkey
Strict Mode   mongo Shell Mode
{ "$maxKey": 1 }
 
MaxKey

The representation of the MaxKey BSON data type that compares higher than all other types. See What is the compare order for BSON types? for more information on comparison order for BSON types.

NumberLong

New in version 2.6.

data_numberlong
Strict Mode   mongo Shell Mode
{ "$numberLong": "<number>" }
 
NumberLong( <number> )

Number long is a 64 bit signed integer.