JSON vs BSON explained

May 31, 2026 · 14 min read

JSON is the lingua franca of HTTP APIs: human-readable, easy to debug in browser devtools, and supported everywhere. BSON (Binary JSON) looks similar on paper but stores data in a compact binary layout with extra types that JSON cannot represent natively, such as Date, Decimal128, and raw byte arrays.

Teams often discover BSON when they adopt MongoDB or ship high-throughput internal services. The confusion usually starts with a simple question: if BSON is “binary JSON,” why does my document look bigger on the wire as JSON? This guide answers that with concrete examples and conversion habits that prevent subtle data loss.

What JSON and BSON are

JSON (JavaScript Object Notation) is a text format defined by ECMA-404 and RFC 8259. Parsers turn UTF-8 strings into language-native structures. BSON is MongoDB’s binary serialization: each value carries a type byte and length prefixes for strings and documents, which makes random access inside a document cheaper than scanning text.

Neither format is a drop-in substitute for the other at the application boundary. JSON is ideal for public APIs and config checked into Git. BSON is ideal when a database or driver already speaks binary documents and you need types beyond JSON’s small set.

Type systems compared

JSON supports objects, arrays, strings, numbers, booleans, and null. Numbers are IEEE-754 doubles in practice, which is why integers beyond 2^53-1 and decimal money values cause pain. BSON adds distinct integer widths, UTC datetime, ObjectId, binary subtype, regular expressions, JavaScript code (legacy), and Decimal128 for exact decimals.

When you round-trip BSON → JSON → BSON, types can change shape: a BSON datetime becomes an ISO-8601 string in JSON unless you use Extended JSON conventions. Always document how your API represents dates and large integers so clients do not guess wrong.

// JSON (API response)
{ "userId": "507f1f77bcf86cd799439011", "balance": 19.99, "active": true }

// BSON Extended JSON (debug export)
{ "userId": { "$oid": "507f1f77bcf86cd799439011" },
  "balance": { "$numberDecimal": "19.99" },
  "createdAt": { "$date": "2026-06-08T10:00:00.000Z" } }

Size and performance

BSON is not always smaller than JSON. Field names are stored in BSON documents, so short keys help both formats. For tiny payloads, JSON can win because there is no per-field type overhead. For nested documents with many numeric fields, BSON’s typed integers can be smaller and faster to parse than converting decimal text.

Throughput matters at the driver boundary: MongoDB drivers speak BSON end to end. Converting to JSON for every read adds CPU and allocations. Expose JSON to browsers and partner APIs; keep BSON inside your data layer unless you have a strong reason to materialize text.

BSON in MongoDB

MongoDB stores documents as BSON on disk and in the replication oplog. Drivers serialize your objects to BSON before sending them over the wire protocol. Tools like mongosh pretty-print JSON for humans, but the server never stores that text form directly.

ObjectId is a 12-byte BSON type encoding timestamp, machine, process, and counter - handy for rough sorting by creation time. When you export collections to JSON lines for analytics, confirm whether ids appear as {"$oid": "..."} strings or plain hex so downstream pipelines join correctly.

Choosing a format

Choose JSON for REST and GraphQL responses, webhooks, CLI output, and files humans edit. Choose BSON (via your database driver) when you need rich types, efficient storage in MongoDB, or binary-safe fields without Base64 expansion in JSON.

If both sides of an integration are under your control, standardize on ISO-8601 strings for timestamps and strings for decimals in JSON, or adopt JSON Schema to lock shapes. That discipline costs less than debugging a production mismatch where a date field silently became a string.

Browse all tools