Introduction
BSON is the binary serialization format MongoDB uses to store documents and exchange them over the wire. It is JSON-like in structure but supports types JSON does not: ObjectId, Date, Binary, Decimal128, RegExp, and 64-bit integers. If you have ever queried a MongoDB collection and wondered what the wire bytes look like, or you need to inspect a BSON payload from a driver log, this bson encoder decoder does both directions in the browser. It uses the official bson package from MongoDB and supports Extended JSON so types survive the round trip. No data leaves your device.
What this tool does
- Encodes JSON (or Extended JSON) into BSON bytes, output as hex and base64.
- Decodes BSON bytes back into Extended JSON, preserving ObjectId, Date, Binary, Decimal128, and other BSON-specific types.
- Supports Extended JSON syntax: $oid for ObjectId, $date for dates, $binary for binary, $numberLong for 64-bit ints, and more.
- Auto-detects hex or base64 input when decoding.
- Uses the official bson npm package maintained by MongoDB, so output matches what real drivers produce.
- Runs entirely client-side with no network requests.
How this tool works
In encode mode, paste a JSON or Extended JSON document. The tool parses it with EJSON.parse in relaxed:false mode, which means types like {"$oid": "..."} and {"$date": "..."} are converted to their BSON equivalents. The resulting document is serialized with BSON.serialize into a Uint8Array, displayed as both hex and base64.
In decode mode, paste hex or base64 BSON bytes. The tool auto-detects the format, converts to a Uint8Array, and calls BSON.deserialize. The result is stringified with EJSON.stringify in relaxed:false mode, so ObjectId becomes {"$oid": "..."} and Date becomes {"$date": "..."} rather than being flattened to plain strings. This preserves the types across a round trip.
How BSON encoding works
BSON stands for Binary JSON. It was designed by MongoDB to be a binary serialization format that is efficient to traverse and supports types JSON lacks. The BSON specification defines the wire format.
A BSON document is a sequence of elements preceded by a 4-byte length prefix and terminated by a null byte. Each element has a 1-byte type tag, a null-terminated key string, and a value whose encoding depends on the type. The type tags cover double (0x01), string (0x02), document (0x03), array (0x04), binary (0x05), ObjectId (0x07), boolean (0x08), date (0x09), null (0x0A), regex (0x0B), 32-bit integer (0x10), timestamp (0x11), 64-bit integer (0x12), Decimal128 (0x13), and others.
ObjectId is a 12-byte identifier: 4 bytes of timestamp, 5 bytes of random value, 3 bytes of incrementing counter. It is the default _id type in MongoDB. Decimal128 is a 128-bit IEEE 754 decimal floating point type for financial data where binary floating point rounding is unacceptable. The Date type is a 64-bit integer of milliseconds since the Unix epoch.
Extended JSON is MongoDB's convention for representing BSON types in JSON. Instead of a plain string for an ObjectId, you write {"$oid": "507f1f77bcf86cd799439011"}. Instead of a plain ISO string for a date, you write {"$date": "2024-01-15T00:00:00.000Z"}. The Extended JSON specification defines the full set of type wrappers. This tool uses relaxed:false mode so every type is preserved across the round trip.
How to use this tool
- Select mode: Encode or Decode.
- For encoding: paste a JSON or Extended JSON document. Output shows hex and base64.
- For decoding: paste hex or base64 BSON bytes. The tool auto-detects the format.
- Use Extended JSON syntax ($oid, $date, $binary, $numberLong) to preserve BSON-specific types.
- Use the Swap button to switch between modes.
Real-world examples
Inspecting a MongoDB wire payload
A developer debugging a MongoDB driver captures a BSON document from the wire and extracts it as hex. They paste the hex into the decode mode and see the Extended JSON representation, with ObjectId shown as {"$oid": "..."} and dates as {"$date": "..."}. This tells them exactly what the driver sent without needing to run a MongoDB instance.
Building a BSON document with an ObjectId
A developer wants to construct a BSON document with a specific ObjectId for a test fixture. They write {"_id": {"$oid": "507f1f77bcf86cd799439011"}, "name": "test"} in the encode mode and get the hex bytes. They paste those bytes into their test harness, which feeds them directly to the MongoDB driver's BSON decoder.
Round-tripping a Decimal128 value
A financial application stores prices as Decimal128 to avoid binary floating point rounding. The developer writes {"price": {"$numberDecimal": "19.99"}} in the encode mode, decodes the resulting hex back, and confirms the output preserves the Decimal128 type rather than collapsing it to a plain number. This validates that their BSON layer handles Decimal128 correctly.
Comparison with similar methods
| Method | Complexity | Typical use |
|---|---|---|
| BSON | Binary, type-rich, length-prefixed | MongoDB wire protocol and storage |
| MessagePack | Binary, compact, type-tagged | Redis, gRPC, compact APIs |
| CBOR (RFC 8949) | Binary, IETF standard, extensible | IoT, CoAP, WebAuthn, Matter |
| JSON | Text, ubiquitous, limited types | Web APIs, configuration |
Limitations or considerations
BSON documents are limited to 16 MB in MongoDB, and this tool inherits that practical limit because it serializes the entire document in memory. The root value must be an object (document), not an array or scalar, because BSON has no top-level array type; arrays are encoded as documents with numeric string keys. Extended JSON in relaxed:false mode produces more verbose output than relaxed mode (dates use {"$date": {"$numberLong": "..."}} instead of ISO strings), but it preserves types exactly. For plain JSON without BSON-specific types, the MessagePack or CBOR tools produce smaller output.
Frequently asked questions
What is Extended JSON?
Extended JSON is MongoDB's convention for representing BSON types in JSON. It uses type wrappers like $oid, $date, $binary, $numberLong, and $numberDecimal so that ObjectId, Date, Binary, 64-bit integers, and Decimal128 survive a JSON round trip. This tool uses relaxed:false mode, which preserves every type exactly.
Why does BSON produce larger output than JSON for small documents?
BSON adds a 4-byte length prefix to every document and subdocument, a 1-byte type tag to every element, and null terminators to every key string. For small documents with short keys, that overhead can exceed the savings from binary encoding. BSON wins on larger documents and on types that JSON encodes inefficiently, like binary data and 64-bit integers.
Can I decode BSON from a MongoDB oplog?
Yes. Oplog entries are BSON documents. Extract the bytes as hex or base64 and paste them into the decode mode. The tool will show the Extended JSON representation, including nested documents and ObjectId values. This is useful for debugging replication issues without a running MongoDB instance.
How is BSON different from MessagePack and CBOR?
BSON is type-rich (ObjectId, Decimal128, RegExp) and length-prefixed for fast traversal, but verbose for small documents. MessagePack is more compact and type-tagged but lacks MongoDB-specific types. CBOR is an IETF standard (RFC 8949) with extensible tags, used in IoT and WebAuthn. Use BSON when you need MongoDB compatibility; use CBOR or MessagePack for general-purpose binary serialization.
Conclusion
BSON is the binary format MongoDB uses for storage and wire protocol, with types JSON lacks like ObjectId, Date, and Decimal128. This bson encoder decoder uses the official MongoDB bson package and supports Extended JSON so types survive the round trip. For general-purpose binary serialization without MongoDB-specific types, try the MessagePack or CBOR tools.