Document Data Format: Extended JSON

Overview

JSON is a data format that represents the values of objects, arrays, numbers, strings, booleans, and nulls. The Extended JSON format defines a reserved set of keys prefixed with the $ character to represent field type information that directly corresponds to each type in BSON, the format that MongoDB uses to store data.

Extended JSON Formats

MongoDB Extended JSON features different string formats to represent BSON data. Each of the formats conforms to the JSON RFC and meets specific use cases.

The Extended format, also known as the Canonical format, features specific representations for every BSON type for bidirectional conversion without loss of information. The Relaxed format is more concise and closer to ordinary JSON, but does not represent all the type information such as the specific byte size of number fields.

The following table provides descriptions of the JSON formats:

To learn more about JSON, BSON, and Extended JSON, see our article about JSON and BSON and the Extended JSON reference in the MongoDB Server manual.

{
  "_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")
}

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

Read Extended JSON

You can read an Extended JSON string into a Go struct by calling the bson.UnmarshalExtJSON() method. This method parses an Extended JSON string and stores the result in the specified value parameter.

This example shows how you can read an Extended JSON string into the following Person struct:

type Person struct {
	ID       bson.ObjectID `bson:"_id"`
	Name     string
	Age      int
	Birthday bson.DateTime
	Address  Address
	Hobbies  []string
}
type Address struct {
	Street string
	City   string
	State  string
}

The following code uses the UnmarshalExtJSON() method to read an Extended JSON string and unmarshal the data into an instance of Person:

var extJsonString = "{\"_id\":{\"$oid\":\"578f6fa2df35c7fbdbaed8c5\"},\"name\":\"Liana Ruiz\",\"age\":46,\"birthday\":{\"$date\":\"1988-01-15T00:00:00Z\"},\"address\":{\"street\":\"500 Slippery Rock Road\",\"city\":\"Round Rock\",\"state\":\"AR\"},\"hobbies\":[\"cycling\", \"baking\"]}"
var p Person
err := bson.UnmarshalExtJSON([]byte(extJsonString), false, &p)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Go Struct Representation:\n%+v\n", p)

Go Struct Representation:
{ID:ObjectID("578f6fa2df35c7fbdbaed8c5") Name:Liana Ruiz Age:46 Birthday:569203200000 Address:{Street:500 Slippery Rock Road City:Round Rock State:AR} Hobbies:[cycling baking]}

Write Extended JSON

You can produce an Extended JSON string from an instance of a Go struct by calling the bson.MarshalExtJSON() method. The following example creates an Extended JSON string in the Relaxed format from an instance of Person:

var person = Person{
	ID:       bson.NewObjectID(),
	Name:     "Matteo Carisi",
	Age:      49,
	Birthday: bson.NewDateTimeFromTime(time.Date(1975, 10, 30, 0, 0, 0, 0, time.UTC)),
	Address:  Address{Street: "14a Corner Court", City: "Springfield", State: "IL"},
	Hobbies:  []string{"cooking", "birdwatching"},
}
newExtJsonString, err := bson.MarshalExtJSON(person, false, true)
if err != nil {
	log.Fatal(err)
}
fmt.Printf("Extended JSON Representation:\n%s\n", newExtJsonString)

Extended JSON Representation:
{"_id":{"$oid":"686688fa7c1a2e75405f4697"},"name":"Matteo Carisi","age":49,"birthday":{"$date":"1975-10-30T00:00:00Z"},"address":{"street":"14a Corner Court","city":"Springfield","state":"IL"},"hobbies":["cooking","birdwatching"]}

The second parameter to MarshalExtJSON() determines if the output string is in Canonical (Extended) format or Relaxed format. The preceding example passes false as the canonical parameter, so the output is Relaxed JSON.

formattedString, err := bson.MarshalExtJSONIndent(person, false, true, "", "  ")
if err != nil {
	log.Fatal(err)
}
fmt.Printf("%s\n", formattedString)

{
  "_id": {
    "$oid": "686688fa7c1a2e75405f4697"
  },
  "name": "Matteo Carisi",
  "age": 49,
  "birthday": {
    "$date": "1975-10-30T00:00:00Z"
  },
  "address": {
    "street": "14a Corner Court",
    "city": "Springfield",
    "state": "IL"
  },
  "hobbies": [
    "cooking",
    "birdwatching"
  ]
}

API Documentation

To learn more about the methods and types used in this guide, see the following API documentation:

• UnmarshalExtJSON()

• MarshalExtJSON()

• MarshalExtJSONIndent()