EVENTGet 50% off your ticket to MongoDB.local NYC on May 2. Use code Web50! Learn more >

Explaining BSON with Examples

Though JSON and BSON have near identical names, they are not identical in purpose. BSON is based on JSON but has its own distinct features and advantages. This article will look at these two object notations, uncover their differences, and address any confusion surrounding BSON and JSON.

What is BSON?

BSON is a binary encoded Javascript Object Notation (JSON)—a textual object notation widely used to transmit and store data across web based applications. JSON is easier to understand as it is human-readable, but compared to BSON, it supports fewer data types. BSON encodes type and length information, too, making it easier for machines to parse.

{"hello": "world"} →
\x16\x00\x00\x00           // total document size
\x02                       // 0x02 = type String
hello\x00                  // field name
\x06\x00\x00\x00world\x00  // field value
\x00                       // 0x00 = type EOO ('end of object')

Just like JSON, BSON supports various programming languages such as C, C++, C#, Java, JavaScript, PHP, Python, Ruby, and Swift.

What Does BSON Stand For?

BSON stands for Binary Javascript Object Notation. It is a bin­ary-en­coded seri­al­iz­a­tion of JSON documents. BSON has been extended to add some optional non-JSON-native data types, like dates and binary data.

BSON can be compared to other binary formats, like Protocol Buffers. The greater difference is that BSON is more "Schema-less" than Protocol Buffers, providing the advantage of flexibility and the slight disadvantage of space efficiency.

BSON Specifications and BSON Types

BSON specification version 1.1 is published at bsonspec.org. The topmost element in the structure must be of type BSON object and should contain one or more elements, where an element can be a field name (string), a type, or a value. The following are some of the types included in BSON.

byte 1 byte (8-bits)
int32 4 bytes (32-bit signed integer, two's complement)
int64 8 bytes (64-bit signed integer, two's complement)
uint64 8 bytes (64-bit unsigned integer)
double 8 bytes (64-bit IEEE 754-2008 binary floating-point)
decimal128 16 bytes (128-bit IEEE 754-2008 decimal floating-point)
date 8 bytes(64-bit integer)
objectId 12 bytes(4-byte timestamp value, 5-byte random value, and 3-byte incrementing counter)
array Storage is based on data (A byte array uses 1 byte, a short array uses 2 bytes, and an integer array uses 4 bytes)

To learn more about BSON specifications, visit BSON documentation.

How is BSON Different from JSON?

JSON BSON
Type JSON files are written in text format. BSON files are written in binary.
Speed JSON is fast to read but slower to build. BSON is slow to read but faster to build and scan.
Space JSON data is slightly smaller in byte size. BSON data is slightly larger in byte size.
Encode and Decode We can send JSON through APIs without encoding and decoding. BSON files are encoded before storing and decoded before displaying.
Parse JSON is a human-readable format that doesn't require parsing. BSON needs to be parsed as they are machine-generated and not human-readable.
Data Types JSON has a specific set of data types—string, boolean, number for numeric data types, array, object, and null. Unlike JSON, BSON offers additional data types such as bindata for binary data, decimal128 for numeric.
Usage Used to send data through the network (mostly through APIs). Databases use BSON to store data.

To know more about the differences between BSON and JSON, visit JSON and BSON.

Advantages of BSON

The fol­low­ing three char­ac­ter­ist­ics make BSON advantageous to use.

Lightweight and Traversable

BSON is lightweight: This makes it possible for a large amount of data to be stored in BSON file format. Additionally, BSON files are easily stored and sent through the network, making them perfect for storing and sending data.

Efficient

BSON was made to efficiently store space and scan: In a BSON document, large elements are prefixed with a length field. Documents in BSON use more space than JSON due to the length prefixes and explicit array indices, but thanks to those prefixes, we are able to scan and query much faster. The prefixes make it easy to compare and calculate directly on data, simplifying application code consumption.

Handles Additional Data Types

Unlike in JSON, you can find data types such as Bindata, Minkey, Maxkey, Binary Data, ObjectID, Regular Expression, JavaScript, Decimal128, and Date for datetime in BSON. These data types are crucial when working with specialty programs.

For example, when working with financial systems data, you can use BSON’s Decimal128 for 128 bits of high precision decimal representation.

Many modern systems use binary-based floating-point arithmetic to represent exact decimal fractions through Float and double data types. These data types provide approximation but not the precise value. Using BSON in such cases gives you high precision.

Visit BSON data types to find the list of datatypes exclusive to BSON but not to JSON.

How to Convert JSON to BSON

You can use various converters between JSON and BSON formats. One such example is OnlineJSONTools. A quick Google search will give you various online converters that easily change the JSON format to BSON format and vice versa.

BSON is the format used both for data storage and network transfer in MongoDB. After storing data in MongoDB, you may want to get your data back as JSON, among many other formats. When you want to export your files as JSON, you can use MongoDB’s database tool, bsondump, to convert BSON documents to JSON. To learn how to export BSON documents as JSONs in MongoDB, read below.

How to Import and Export a BSON File in MongoDB

There are plenty of online BSON text viewers that are capable of opening BSON files. If you have a large set of BSON files, you can import BSON files to MongoDB to see the contents of the file from there.

First, you need to install the MongoDB database tools. MongoDB database tools are a suite of command-line utilities for working with MongoDB. You can learn about installing them from this documentation.

After installing those tools, you can easily import and export BSON files in MongoDB by using a few simple commands. The mongorestore command loads data from either a binary database dump created by mongodump or the standard input into a mongod or mongos instance.

To import a .bson file, run the following command on your system command line.

mongorestore -d db_name /path/file.bson

Here, db_name is the name of the database you want to import. Path denotes the absolute path of your .bson file, while file represents the BSON file’s name.

For a single collection, run the following command on your system command line.

mongorestore --drop -d db_name -c collection_name /path/file.bson

Here, collection_name defines the name of the collection that you want to import.

For restoring the complete folder exported by mongodump.

mongorestore -d db_name /path/

To export BSON documents, use the database tool bsondump.

Run the following command from the system command line to export the collection as BSON.

bsondump collection.bson

You can use the --outFile option by running the following command from the system command line to export the collection as JSON.

bsondump --outFile=collection.json collection.bson

You can check out the official documentation for bsondump to learn how to install bsondump to convert BSON files to human-readable formats, including JSON.

In case of a problem with the programming language, be sure to update the MongoDB driver to the version that supports the language.

BSON Example: How BSON is Stored in MongoDB Database

Let’s take the following JSON document example.

{
"hello" : "world"
}

When storing the JSON document, it will be converted to the following.

\x16\x00\x00\x00             // total document size
\x02                         // 0x02 = type String
hello\x00                    // field name
\x06\x00\x00\x00world\x00    // field value (size of value, value, null terminator         
\x00                         // 0x00 = type EOO ('end of object')

Ready to get started?

Launch a new cluster or migrate to MongoDB Atlas with zero downtime.

Relevant FAQs

Can a BSON string be null?

Yes. They can contain null values.

What is a BSON data type?

BSON has various data types which are not included in JSON, such as Date for datetime and ObjectID.

What does BSON look like?

BSON is a bin­ary-en­coded seri­al­iz­ed format of JSON documents. It provides type and length information in characters that are not human-readable but make it easier for machines to parse.

{"hello": "world"} →
\x16\x00\x00\x00           // total document size
\x02                       // 0x02 = type String
hello\x00                  // field name
\x06\x00\x00\x00world\x00  // field value
\x00                       // 0x00 = type EOO ('end of object')

Why does MongoDB use BSON rather than JSON?

BSON is easier to generate and parse for machines and also supports more data types than JSON.