Reactive Scala Driver for MongoDB

Asynchronous & Non-Blocking

The ReactiveMongo Play JSON library provides a JSON serialization pack for ReactiveMongo, based on the Play Framework JSON library.


You can setup this serialization pack by adding the following dependency in your project/Build.scala (or build.sbt).

libraryDependencies ++= Seq(
  "org.reactivemongo" %% "reactivemongo-play-json" % "1.0.0-rc.1-SNAPSHOT-play27"

Maven Central Build Status Test coverage

If the dependency for the Play plugin (with the right version) is present, it already provides the JSON support and this JSON serialization pack must not be added as a separate dependency.

Then, the following code enables this JSON serialization pack.


API documentations: ReactiveMongo Play JSON API

If you want to use this JSON serialization outside of Play application, the dependency to the standalone Play JSON library must then be added: "" %% "play-json" % version.

Documents and values

There is one Play JSON class for most of the BSON types, from the play.api.libs.json package:

All these JSON types extend JsValue, thus any JSON value can be converted to an appropriate BSON value.

This serialization is based on the MongoDB Extension JSON syntax (e.g. { "$oid": "<id>" } for a Object ID):

BSONDocument JsObject
BSONArray JsArray
BSONBinary JsObject with a $binary JsString field containing the value in hexadecimal representation
BSONBoolean JsBoolean
BSONDBPointer No JSON type
BSONDateTime JsObject with a $date JsNumber field with the timestamp (milliseconds) as value
BSONDouble JsNumber or JsObject with $numberDouble value
BSONInteger JsNumber or JsObject with $numberInt value
BSONJavaScript JsObject with a $javascript JsString value representing the JavaScript code
BSONLong JsNumber or JsObject with $numberLong value
BSONMaxKey JsObject as constant { "$maxKey": 1 }
BSONMinKey JsObject as constant { "$minKey": 1 }
BSONNull No JSON type
BSONObjectID JsObject with a $oid JsString field with the stringified ID as value
BSONRegex JsObject with a $regex JsString field with the regular expression, and optionally an $options JsString field with the regex flags (e.g. "i" for case insensitive)
BSONString JsString
BSONSymbol JsObject with a $symbol JsString field with the symbol name as value
BSONTimestamp JsObject with a $timestamp nested object having a t and a i JsNumber fields
BSONUndefined JsObject of the form { "$undefined": true }

Furthermore, the whole library is articulated around the concept of Writes and Reads. These are typeclasses whose purpose is to serialize/deserialize objects of arbitrary types into/from JSON.

Using that, any type that can be serialized as JSON can be also be serialized as BSON.

A document is represented by JsObject, which is basically an immutable list of key-value pairs. Since it is the most used JSON type when working with MongoDB, the ReactiveMongo Play JSON library handles such JsObjects as seamless as possible. The encoding of such JSON object needs an instance of the typeclass OWrites (a Writes specialized for object).

The default JSON serialization can also be customized, using the functions BSONFormats.readAsBSONValue and BSONFormats.writeAsJsValue.

Next: Integration with Play Framework

Suggest changes