Docs Menu

Docs HomeAtlas App Services

Data Formats

On this page

  • Standard JSON (application/json)
  • Canonical & Relaxed EJSON (application/ejson)
  • BSON Types
  • Array
  • Binary
  • Date
  • Decimal128
  • Document
  • Double
  • Int32
  • Int64
  • MaxKey
  • MinKey
  • ObjectId
  • Regular Expression
  • Timestamp

MongoDB stores data in a format called BSON, which is similar to a JSON object in structure but supports additional data types and uses a binary encoding. BSON is efficient for computers but is not human readable, so you can't work with it directly.

Instead, the Data API uses two formats to represent data in requests and responses: JSON and EJSON.

You define a single default return type for all generated Data API endpoints and individually for each custom endpoint. Incoming requests can also specify a preferred data format that overrides the default using an Accept header.

Example

This document can be represented in either JSON or EJSON shows BSON types represented in JSON and EJSON:

You define a single default return type for all generated Data API endpoints and individually for each custom endpoint. Incoming requests can also specify a preferred data format that overrides the default using an Accept header.

The JSON format uses standard types that any tool can parse and understand. However, JSON cannot represent all BSON types so JSON responses may lose type information for some fields. For example, BSON has distinct types for 32-bit integers and 64-bit floats but a JSON response represents both as a number.

The EJSON format, short for MongoDB Extended JSON, is a superset of standard JSON that uses structured fields to represent BSON data that don't have corresponding JSON types. This fully represents your data but requires your client to understand how to work with EJSON.

There are two variants of EJSON:

  • Canonical EJSON uses a verbose structure that emphasizes type preservation at the expense of readability and interoperability. It fully represents BSON types but you may need to use a library or custom code to work with it.

  • Relaxed EJSON uses a more compact structure that is easier to read and work with but may lose type information for some BSON types. For example, a number field in an inserted document may be inferred as a different numeric BSON type than you expect.

You can use either Canonical or Relaxed EJSON in request bodies. Data API endpoints that are configured to return EJSON always return Canonical EJSON.

This sections lists the BSON types that the Data API supports and shows how each type is represented in JSON and EJSON format.

EJSON
JSON

Canonical EJSON

[ <elements> ]

Relaxed EJSON

Same as Canonical

[ <elements> ]
EJSON
JSON

Canonical EJSON

{
"$binary": {
"base64": "e67803a39588be8a95731a21e27d7391",
"subType": "05"
}
}

Relaxed EJSON

Same as Canonical

{
"Subtype": 5,
"Data": "e67803a39588be8a95731a21e27d7391"
}
EJSON
JSON

Canonical EJSON

{
"$date": {
"$numberLong": "1641954803067"
}
}

Relaxed EJSON

{
"$date": "2022-01-12T02:33:23.067Z"
}
"2022-01-12T02:33:23.067Z"
EJSON
JSON

Canonical EJSON

{ "$numberDecimal": "9823.1297" }

Relaxed EJSON

Same as Canonical

"9823.1297"
EJSON
JSON

Canonical EJSON

{ <content> }

Relaxed EJSON

Same as Canonical

{ <content> }
EJSON
JSON

Canonical EJSON

{ "$numberDouble": "10.5" }

Relaxed EJSON

10.5
10.5
EJSON
JSON

Canonical EJSON

{ "$numberInt": "10" }

Relaxed EJSON

10
10
EJSON
JSON

Canonical EJSON

{ "$numberLong": "50" }

Relaxed EJSON

Same as Canonical

50
EJSON
JSON

Canonical EJSON

{ "$maxKey": 1 }

Relaxed EJSON

Same as Canonical

{}

No JSON equivalent

EJSON
JSON

Canonical EJSON

{ "$minKey": 1 }

Relaxed EJSON

Same as Canonical

{}

No JSON equivalent

EJSON
JSON

Canonical EJSON

{ "$oid":"5d505646cf6d4fe581014ab2" }

Relaxed EJSON

Same as Canonical

"5d505646cf6d4fe581014ab2"
EJSON
JSON

Canonical EJSON

{
"$regularExpression": {
"pattern":"^H",
"options":"i"
}
}

Relaxed EJSON

Same as Canonical

{
"Pattern": "^H",
"Options": "i"
}
EJSON
JSON

Canonical EJSON

{
"$timestamp": {
"t":1565545664,
"i":1
}
}

Relaxed EJSON

Same as Canonical

{
"T": 1565545664,
"I": 1
}
←  Data API Examples →