Docs Menu
Docs Home
/
MongoDB Atlas
/
Atlas App Services
/
Data API [Deprecated]

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:

{
   "Name": "Mango",
   "Year": { "$numberLong": "2022" },
   "Weight": { "$numberDecimal": "9823.1297" },
   "Date": { "$date": { "$numberLong": "1641954803067" } }
}
{
   "Name": "Mango",
   "Year": 2022,
   "Weight": "9823.1297",
   "Date": "2022-01-12T02:33:23.067Z"
}

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.

Standard JSON (application/json)

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.

Canonical & Relaxed EJSON (application/ejson)

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.

BSON Types

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

Array

EJSON
JSON

Canonical EJSON

[ <elements> ]

Relaxed EJSON

Same as Canonical

[ <elements> ]

Binary

EJSON
JSON

Canonical EJSON

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

Relaxed EJSON

Same as Canonical

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

Date

EJSON
JSON

Canonical EJSON

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

Relaxed EJSON

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

Decimal128

EJSON
JSON

Canonical EJSON

{ "$numberDecimal": "9823.1297" }

Relaxed EJSON

Same as Canonical

"9823.1297"

Document

EJSON
JSON

Canonical EJSON

{ <content> }

Relaxed EJSON

Same as Canonical

{ <content> }

Double

EJSON
JSON

Canonical EJSON

{ "$numberDouble": "10.5" }

Relaxed EJSON

10.5
10.5

Int32

EJSON
JSON

Canonical EJSON

{ "$numberInt": "10" }

Relaxed EJSON

10
10

Int64

EJSON
JSON

Canonical EJSON

{ "$numberLong": "50" }

Relaxed EJSON

Same as Canonical

50

MaxKey

EJSON
JSON

Canonical EJSON

{ "$maxKey": 1 }

Relaxed EJSON

Same as Canonical

{}

No JSON equivalent

MinKey

EJSON
JSON

Canonical EJSON

{ "$minKey": 1 }

Relaxed EJSON

Same as Canonical

{}

No JSON equivalent

ObjectId

EJSON
JSON

Canonical EJSON

{ "$oid":"5d505646cf6d4fe581014ab2" }

Relaxed EJSON

Same as Canonical

"5d505646cf6d4fe581014ab2"

Regular Expression

EJSON
JSON

Canonical EJSON

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

Relaxed EJSON

Same as Canonical

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

Timestamp

EJSON
JSON

Canonical EJSON

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

Relaxed EJSON

Same as Canonical

{
   "T": 1565545664,
   "I": 1
}

Back

Authenticate Data API Requests

Next