MongoDB Extended JSON (v1)

Disambiguation

The following page discusses MongoDB Extended JSON v1 (Legacyextended JSON). For discussion on MongoDB Extended JSON v2, seeMongoDB Extended JSON (v2).

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

JSON can only represent a subset of the types supported byBSON. To preserve type information, MongoDB adds the followingextensions to the JSON format:

  • Strict mode. Strict mode representations of BSON types conform tothe JSON RFC. Any JSON parser can parsethese strict mode representations as key/value pairs; however, onlythe MongoDB internal JSON parser recognizes the typeinformation conveyed by the format.
  • mongo Shell mode. The MongoDB internal JSON parser and themongo shell can parse this mode.

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

MongoDB Extended JSON v1 and MongoDB Drivers

The following drivers use the Extended JSON v1.0 (Legacy)

  • C#
  • Ruby

For the other drivers, refer to MongoDB Extended JSON (v2).

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, can parsestrict 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.

  • mongoimport version 4.0 and earlier
  • —query option of various MongoDB tools
  • mongo shell

Output in Strict mode

Before version 4.2, mongoexport and REST andHTTP Interfaces output data in _Strict mode_of MongoDB Extended JSON v1.

Output in mongo Shell Mode

Before version 4.2, bsondump outputs in mongo Shellmode.

BSON Data Types and Associated Representations

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

Binary

  • data_binary

Strict Mode mongo Shell Mode

  1. { "$binary": "<bindata>", "$type": "<t>" }
  1. BinData ( <t>, <bindata> )
  • <bindata> is the base64 representation of a binary string.
  • <t> is a representation of a single byte indicating the data type. InStrict mode it is a hexadecimal string, and in Shell mode it is an integer.See the extended bson documentation. http://bsonspec.org/spec.html

Date

  • data_date

Strict Mode mongo Shell Mode

  1. { "$date": "<date>" }
  1. new Date ( <date> )

In Strict mode, <date> is an ISO-8601 date format with a mandatory timezone field following the template YYYY-MM-DDTHH:mm:ss.mmm<+/-Offset>.

In Shell mode, <date> is the JSON representation of a 64-bit signedinteger giving the number of milliseconds since epoch UTC.

Timestamp

  • data_timestamp

Strict Mode mongo Shell Mode

  1. { "$timestamp": { "t": <t>, "i": <i> } }
  1. Timestamp( <t>, <i> )
  • <t> is the JSON representation of a 32-bit unsigned integer forseconds since epoch.
  • <i> is a 32-bit unsigned integer for the increment.

Regular Expression

  • data_regex

Strict Mode mongo Shell Mode

  1. { "$regex": "<sRegex>", "$options": "<sOptions>" }
  1. /<jRegex>/<jOptions>
  • <sRegex> is a string of valid JSON characters.
  • <jRegex> is a string that may contain valid JSON characters andunescaped double quote (") characters, but may not containunescaped forward slash (/) characters.
  • <sOptions> is a string containing the regex options representedby 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 andmongo Shell representations support a limited range of options,any nonconforming options will be dropped when converting to thisrepresentation.

OID

  • data_oid

Strict Mode mongo Shell Mode

  1. { "$oid": "<id>" }
  1. ObjectId( "<id>" )

<id> is a 24-character hexadecimal string.

DB Reference

  • data_ref

Strict Mode mongo Shell Mode

  1. { "$ref": "<name>", "$id": "<id>" }
  1. 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

  1. { "$undefined": true }
  1. undefined

The representation for the JavaScript/BSON undefined type.

You cannot use undefined in query documents.Consider the following document inserted into the people collection:

  1. db.people.insert( { name : "Sally", age : undefined } )

The following queries return an error:

  1. db.people.find( { age : undefined } )
  2. db.people.find( { age : { $gte : undefined } } )

However, you can query for undefined values using $type, asin:

  1. db.people.find( { age : { $type : 6 } } )

This query returns all documents for which the age field hasvalue undefined.

MinKey

  • data_minkey

Strict Mode mongo Shell Mode

  1. { "$minKey": 1 }
  1. MinKey

The representation of the MinKey BSON data type that compares lowerthan all other types. SeeComparison/Sort Order for more information oncomparison order for BSON types.

MaxKey

  • data_maxkey

Strict Mode mongo Shell Mode

  1. { "$maxKey": 1 }
  1. MaxKey

The representation of the MaxKey BSON data type that compares higherthan all other types. SeeComparison/Sort Order for more information oncomparison order for BSON types.

NumberLong

New in version 2.6.

  • data_numberlong

Strict Mode mongo Shell Mode

  1. { "$numberLong": "<number>" }
  1. NumberLong( "<number>" )

NumberLong is a 64 bit signed integer. You must include quotationmarks or it will be interpreted as a floating point number, resultingin a loss of accuracy.

For example, the following commands insert 9223372036854775807 as aNumberLong with and without quotation marks around the integer value:

  1. db.json.insert( { longQuoted : NumberLong("9223372036854775807") } )
  2. db.json.insert( { longUnQuoted : NumberLong(9223372036854775807) } )

When you retrieve the documents, the value of longUnQuoted haschanged, while longQuoted retains its accuracy:

  1. db.json.find()
  2. { "_id" : ObjectId("54ee1f2d33335326d70987df"), "longQuoted" : NumberLong("9223372036854775807") }
  3. { "_id" : ObjectId("54ee1f7433335326d70987e0"), "longUnQuoted" : NumberLong("-9223372036854775808") }

NumberDecimal

New in version 3.4.

  • data_numberdecimal

Strict Mode mongo Shell Mode

  1. { "$numberDecimal": "<number>" }
  1. NumberDecimal( "<number>" )

NumberDecimal is a high-precision decimal. You must include quotation marks, or theinput number will be treated as a double, resulting in data loss.

For example, the following commands insert 123.40 as aNumberDecimal with and without quotation marks around the value:

  1. db.json.insert( { decimalQuoted : NumberDecimal("123.40") } )
  2. db.json.insert( { decimalUnQuoted : NumberDecimal(123.40) } )

When you retrieve the documents, the value of decimalUnQuoted haschanged, while decimalQuoted retains its specified precision:

  1. db.json.find()
  2. { "_id" : ObjectId("596f88b7b613bb04f80a1ea9"), "decimalQuoted" : NumberDecimal("123.40") }
  3. { "_id" : ObjectId("596f88c9b613bb04f80a1eaa"), "decimalUnQuoted" : NumberDecimal("123.400000000000") }