Work with Extended JSON Data

Overview

In this guide, you can learn how to use the Extended JSON data format when interacting with MongoDB documents.

JSON is a human-readable data format that represents the values of objects, arrays, numbers, strings, booleans, and nulls. This format supports only a subset of BSON data types, which is the format that MongoDB uses to store data. The Extended JSON format supports more BSON types, defining a reserved set of keys prefixed with "$" to represent field type information that directly corresponds to each type in BSON.

To learn more about JSON, BSON, and Extended JSON, see the JSON and BSON resource and Extended JSON MongoDB Server manual entry.

Extended JSON Formats

MongoDB Extended JSON provides string formats to represent BSON data. Each format conforms to the JSON RFC and meets specific use cases.

The following table describes each Extended JSON format:

Name	Description
Extended or Canonical	A string format that avoids loss of BSON type information during data conversions. This format prioritizes type preservation at the loss of human-readability and interoperability with older formats. JsonMode.EXTENDED
Relaxed	A string format that describes BSON documents with some type information loss. This format prioritizes human-readability and interoperability at the loss of certain type information. JsonMode.RELAXED
Shell	A string format that matches the syntax used in the MongoDB shell. This format prioritizes compatibility with the MongoDB shell, which often uses JavaScript functions to represent types. JsonMode.SHELL

special rules for parsing $uuid fields

Extended JSON Examples

The following examples show a document containing an ObjectId, date, and long number field represented in each Extended JSON format. Click the tab that corresponds to the format of the example you want to see:

{
  "_id": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": { "$numberLong": "1601499609" }},
  "numViews": { "$numberLong": "36520312" }
}

{
  "_id": { "$oid": "573a1391f29313caabcd9637" },
  "createdAt": { "$date": "2020-09-30T18:22:51.648Z" },
  "numViews": 36520312
}

{
  "_id": ObjectId("573a1391f29313caabcd9637"),
  "createdAt": ISODate("2020-09-30T18:22:51.648Z"),
  "numViews": NumberLong("36520312")
}

Read Extended JSON

You can read an Extended JSON string into Scala objects by using the Scala driver's document classes or by using the BSON library directly. The following sections show how to use each approach.

Document Classes

You can read an Extended JSON string into a Scala document object by calling the parse() static method on BsonDocument and then wrapping the result in a Scala Document instance. This approach parses the Extended JSON string in any of the formats and returns a Document containing the data.

The following example shows how you can read an Extended JSON string into a Document object by calling BsonDocument.parse() and passing the result to the Document factory:

val ejsonStr = """{"_id": {"$oid": "507f1f77bcf86cd799439011"}, "myNumber": {"$numberLong": "4794261"}}"""
val document = Document(BsonDocument.parse(ejsonStr))
println(document)

Iterable((_id,BsonObjectId{value=507f1f77bcf86cd799439011}), (myNumber,BsonInt64{value=4794261}))

To learn more about documents in MongoDB, see Documents in the MongoDB Server manual.

BSON Library

You can also read an Extended JSON string into Scala objects without using the Scala driver's document classes by using the JsonReader class. This class contains methods to sequentially parse the fields and values in any format of the Extended JSON string, and returns them as Scala objects. The driver's document classes also use this class to parse Extended JSON.

The following code example shows how you can use the JsonReader class to convert an Extended JSON string into Scala objects:

val ejsonStr = """{"_id": {"$oid": "507f1f77bcf86cd799439011"}, "myNumber": {"$numberLong": "4794261"}}"""
val reader = new JsonReader(ejsonStr)
reader.readStartDocument()
val id = reader.readObjectId("_id")
val myNumber = reader.readInt64("myNumber")
reader.readEndDocument()
println(s"$id is type: ${id.getClass.getName}")
println(s"$myNumber is type: ${myNumber.getClass.getName}")

507f1f77bcf86cd799439011 is type: org.bson.types.ObjectId
4794261 is type: long

For more information, see the JsonReader API documentation.

Write Extended JSON

You can write an Extended JSON string from your data by using the Scala driver's document classes or by using the BSON library directly. The following sections show how to use each approach.

Document Classes

You can write an Extended JSON string from an instance of Document or BsonDocument by calling the toJson() method. By default, the toJson() method outputs the string in the Relaxed mode format. To use a different format, pass an instance of the JsonWriterSettings class to the toJson() method.

The following example calls the toJson() method without arguments to output the Extended JSON in the default Relaxed mode format:

val document = Document(
  "_id" -> BsonObjectId(new ObjectId("507f1f77bcf86cd799439012")),
  "myNumber" -> BsonInt64(11223344L)
)
val ejsonStr = document.toJson()
println(ejsonStr)

{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "myNumber": 11223344}

BSON Library

You can also output an Extended JSON string from data in Scala objects using the BSON library with the JsonWriter class. To construct an instance of JsonWriter, pass a subclass of a Java Writer to specify how you want to output the Extended JSON. You can optionally pass a JsonWriterSettings instance to specify options such as the Extended JSON format. By default, the JsonWriter uses the Relaxed mode format. The Scala driver's document classes also use this class to convert BSON to Extended JSON.

The following code example shows how you can use JsonWriter to create an Extended JSON string and output it to System.out. The example specifies the format by passing the outputMode() builder method the JsonMode.EXTENDED constant:

val writer = new StringWriter()
val jsonWriter = new JsonWriter(writer,
    JsonWriterSettings.builder().outputMode(JsonMode.EXTENDED).build())
jsonWriter.writeStartDocument()
jsonWriter.writeObjectId("_id", new ObjectId("507f1f77bcf86cd799439012"))
jsonWriter.writeInt64("myNumber", 11223344L)
jsonWriter.writeEndDocument()
println(writer.toString())

{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "myNumber": {"$numberLong": "11223344"}}

For more information about the methods and classes mentioned in this section, see the following API documentation:

Custom BSON Type Conversion

In addition to specifying the outputMode() to format the JSON output, you can further customize the output by adding converters to your JsonWriterSettings.Builder instance. These converter methods detect specific BSON types and execute the logic defined by the Converter passed to them.

The following sample code shows how to append converters, defined as lambda expressions, to simplify the Relaxed mode JSON output:

val settings = JsonWriterSettings.builder()
  .outputMode(JsonMode.RELAXED)
  .objectIdConverter((value, writer) => writer.writeString(value.toHexString))
  .timestampConverter((value, writer) => {
    val instant = Instant.ofEpochSecond(value.getTime.toLong)
    writer.writeString(
      DateTimeFormatter.ISO_LOCAL_DATE_TIME.withZone(ZoneOffset.UTC).format(instant))
  })
  .build()
val document = Document(
  "_id" -> BsonObjectId(new ObjectId("507f1f77bcf86cd799439012")),
  "createdAt" -> new BsonTimestamp(1601516589, 1),
  "myNumber" -> BsonInt64(4794261L)
)
println(document.toJson(settings))

{"_id": "507f1f77bcf86cd799439012", "createdAt": "2020-10-01T01:43:09", "myNumber": 4794261}
// Without specifying the converters, the Relaxed mode JSON output
// would look something like this:
{"_id": {"$oid": "507f1f77bcf86cd799439012"}, "createdAt": {"$timestamp": {"t": 1601516589, "i": 1}}, "myNumber": 4794261}

For more information about the methods and classes mentioned in this section, see the following API documentation:

Back

Codecs

Time Series