> This page location: /docs.md > /docs/development.md > /docs/manual/reference/mql.md > /docs/manual/reference/mql/expressions.md

> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# $deserializeEJSON (expression operator)

## Definition

**New in version 8.3**

Converts Extended JSON (EJSON) format to native BSON values. You can use this expression to transform EJSON type wrappers into their corresponding BSON types after you parse a JSON string with [`$convert`.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert)

## Syntax

```javascript
{
   $deserializeEJSON: {
      input: <expression>,
      onError: <expression>
   }
}
```

`$deserializeEJSON` takes a document with the following fields:

| Field | Type | Necessity | Description |
| --- | --- | --- | --- |
| `input` | Expression | Required | The Extended JSON value to convert to native BSON format. This should be a BSON document containing EJSON type wrappers. |
| `onError` | Expression | Optional | Value to return if the operation encounters an error during conversion. If unspecified, when an error occurs, the operation throws an error and stops. |

## Behavior

### Type Wrapper Parsing

`$deserializeEJSON` converts Extended JSON type wrappers to their corresponding BSON types:

| Extended JSON Type Wrapper | BSON Type | Example |
| --- | --- | --- |
| `{"$numberInt": "42"}` | Int32 | `42` |
| `{"$numberLong": "42"}` | Int64 | `NumberLong(42)` |
| `{"$numberDouble": "42.5"}` | Double | `42.5` |
| `{"$oid": "507f1f77bcf86cd799439011"}` | ObjectId | `ObjectId("507f1f77bcf86cd799439011")` |
| `{"$date": "2021-01-01T00:00:00.000Z"}` | Date | `ISODate("2021-01-01T00:00:00.000Z")` |
| `{"$date": {"$numberLong": "1609459200000"}}` | Date | `ISODate("2021-01-01T00:00:00.000Z")` |
| `{"$binary": {"base64": "AQIDBA==", "subType": "00"}}` | Binary | `BinData(0, "AQIDBA==")` |
| `{"$regularExpression": {"pattern": "abc", "options": "i"}}` | Regular Expression | `/abc/i` |

### Null and Missing Values

If the `input` value is null or missing, `$deserializeEJSON` returns null.

## Examples

The examples on this page use data from the [sample\_mflix dataset](https://www.mongodb.com/docs/manual/sample-data/sample-mflix.md#std-label-sample-mflix). For details on how to load this dataset into your self-managed MongoDB deployment, see [Load the Sample Dataset](https://www.mongodb.com/docs/manual/sample-data/load-sample-data-local.md#std-label-sample-dataset-local). If you made any modifications to the sample databases, you may need to drop and recreate the databases to run the examples on this page.

### Deserialize Extended JSON Document

The following example deserializes an Extended JSON document back to native BSON types:

```javascript
db.movies.aggregate([
  {
    $match: { title: "Inception" }
  },
  {
    $project: {
      original: "$$ROOT",
      serialized: { $serializeEJSON: { input: "$$ROOT" } }
    }
  },
  {
    $project: {
      title: "$original.title",
      deserialized: { $deserializeEJSON: { input: "$serialized" } }
    }
  }
])
```

**Output:**

```javascript
{
  _id: ObjectId("573a1398f29313caabcea974"),
  title: "Inception",
  deserialized: {
    _id: ObjectId("573a1398f29313caabcea974"),
    title: "Inception",
    year: 2010,
    runtime: 148,
    released: ISODate("2010-07-16T00:00:00.000Z"),
    cast: [
      "Leonardo DiCaprio",
      "Joseph Gordon-Levitt",
      "Ellen Page",
      "Tom Hardy"
    ],
    genres: [ "Action", "Sci-Fi", "Thriller" ],
    directors: [ "Christopher Nolan" ]
  }
}
```

### Parse JSON String and Deserialize

The following example combines [`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert) with `$deserializeEJSON` to parse a JSON string and convert EJSON type wrappers to BSON:

```javascript
db.aggregate([
  {
    $documents: [
      {
        jsonData: '{"_id":{"$oid":"507f1f77bcf86cd799439011"},' +
          '"title":"The Matrix",' +
          '"year":{"$numberInt":"1999"},' +
          '"rating":{"$numberDouble":"8.7"}}'
      }
    ]
  },
  {
    $project: {
      parsed: {
        $convert: {
          input: "$jsonData",
          to: "object"
        }
      }
    }
  },
  {
    $project: {
      movie: { $deserializeEJSON: { input: "$parsed" } }
    }
  }
])
```

**Output:**

```javascript
{
  _id: ObjectId("..."),
  movie: {
    _id: ObjectId("507f1f77bcf86cd799439011"),
    title: "The Matrix",
    year: 1999,
    rating: 8.7
  }
}
```

### Deserialize Specific Fields

You can deserialize specific fields containing EJSON type wrappers:

```javascript
db.movies.aggregate([
  {
    $match: { title: "Inception" }
  },
  {
    $project: {
      title: 1,
      serializedMetadata: {
        $serializeEJSON: {
          input: {
            releaseDate: "$released",
            runtime: "$runtime",
            rating: "$imdb.rating"
          }
        }
      }
    }
  },
  {
    $project: {
      title: 1,
      metadata: { $deserializeEJSON: { input: "$serializedMetadata" } }
    }
  }
])
```

**Output:**

```javascript
{
  _id: ObjectId("573a1398f29313caabcea974"),
  title: "Inception",
  metadata: {
    releaseDate: ISODate("2010-07-16T00:00:00.000Z"),
    runtime: 148,
    rating: 8.8
  }
}
```

### Use onError for Error Handling

The following example uses `onError` to provide a fallback value if deserialization fails:

```javascript
db.data.aggregate([
  {
    $project: {
      result: {
        $deserializeEJSON: {
          input: "$ejsonField",
          onError: { error: "Invalid EJSON format" }
        }
      }
    }
  }
])
```

## Learn More

- [`$serializeEJSON`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/serializeejson.md#mongodb-expression-exp.-serializeEJSON)

- [`$convert`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/convert.md#mongodb-expression-exp.-convert)

- [`$toString`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/tostring.md#mongodb-expression-exp.-toString)

- The MongoDB Shell provides built-in methods to help work with Extended JSON. To learn more, see [EJSON.](https://www.mongodb.com/docs/mongodb-shell/reference/ejson.md#std-label-mongosh-ejson)
