There is a particular kind of bug that only shows up in production. It is not a syntax error. It is not a 500. It is a record that looks fine in the dashboard, returns fine from the API, and only reveals itself three weeks later when an analytics query comes back with 1970-01-01 stamped on every entry from a specific day. The cause, almost every time, is that somewhere between the producer and the consumer, the data crossed the JSON-to-BSON boundary without anyone noticing that the wire format cares about types in ways JSON does not.
That boundary is the focus of this guide. The BSON Converter sits exactly at that seam: it takes JSON on one side and emits typed bytes on the other, in either hexadecimal or Base64, and lets you watch the conversion happen so the wire dump stops being a black box.
What BSON actually changes about JSON
JSON has six types. BSON has more, and the extras are the ones that quietly rescue you from ambiguity.
- a 32-bit and a 64-bit integer, kept apart on the wire
- a real datetime stored as int64 milliseconds since the Unix epoch
- a real binary type (
BinData) for blobs that should not be mistaken for text - a decimal128 type for money that round-trips through floating point without losing cents
- an ObjectId that is twelve bytes and not a string pretending to be twelve bytes
- a
nullthat is distinct from missing, and a missing that is distinct from an empty string
JSON cannot tell any of those apart. A JSON integer is just a JSON integer, which means a JavaScript Number, which means a 64-bit float, which means anything bigger than 2^53 starts to lose precision the moment it crosses. BSON keeps 42 as an int32 and 4294967296 as an int64 and 3.14 as a double and 0.10 as a decimal128, and the bytes for each one are different. You notice the difference the day an order ID round-trips from 9007199254740993 (the first unsafe JSON Number) and arrives as 9007199254740992.
This matters because the moment your payload is destined for MongoDB, for the Kafka Connect MongoDB source, for any gRPC bridge that uses BSON under the hood, or for a partner that expects bytes not strings, you are no longer writing JSON. You are writing a JSON-shaped projection of BSON. The shape survives the round-trip; the types do not, unless you take the conversion seriously.
Where the wire format quietly fails
Three failure modes show up often enough to be worth naming.
The first is the epoch regression. A client sends "createdAt": "2026-03-14T12:00:00Z" as a JSON string. A MongoDB driver that receives it stores it as a string, not a date. The next service that queries by date range gets nothing. The fix is on the producer side: encode the value as an actual BSON datetime, which means putting the int64 milliseconds on the wire, not the ISO string. The BSON Converter lets you build the right payload in advance, in either hex or Base64, so the bytes you hand to the driver are the bytes you want stored.
The second is the silent UUID mutation. A UUID v7 looks like a 36-character string in JSON. In BSON it is most often a BinData with subtype 4, which is sixteen bytes, not thirty-six characters. A consumer that treats the UUID as a string compares the stringified bytes against the original and finds no match. The lesson is that the wire format is the canonical form, and the string is a rendering of it, not the other way around.
The third is the integer overflow. JavaScript apps that read from MongoDB often receive numbers that came from int64 fields. The Number type cannot represent the full range. If the field happens to be a timestamp in the next century, the value silently becomes 9007199254740992 and downstream math goes quietly wrong. Encoding the value as a BSON int64 first, then transporting it as a string, then parsing it back to a BigInt on the consumer, is the only round-trip that survives.
A pre-flight habit that catches all three
The habit is simple. Before you ship any payload that crosses a JSON/BSON boundary, run it through the converter twice — encode to BSON and decode back to JSON — and diff the result against the original. If the JSON that comes out is structurally identical to the JSON that went in, you are safe. If anything changed, the encoding is leaking information, and you need to decide whether the change is intentional (a stringification, a normalization) or a bug (a precision loss, a type widening, a missing field).
This habit is cheap. It runs in milliseconds. It catches the entire family of bugs where the wire format silently reshapes your data. And it produces an artifact — the hex or Base64 dump of the encoded bytes — that you can attach to a code review or paste into a test fixture so the contract is visible to the next person who has to touch the wire.
Reading the hex dump
A BSON document has a predictable structure: a 4-byte little-endian length prefix, the field-value pairs in order, and a trailing 0x00. Each field is type_byte + cstring_name + value. Once you can read the prefix and the type bytes, you can diagnose most wire-format problems without leaving your terminal.
The converter renders this dump in two encodings. Hex is the readable form — every byte is two characters, the prefix is at the top, the type bytes march down the left. Base64 is the transport form — it survives any text channel, including logs that strip non-ASCII, copy-paste through web forms, and JSON strings where control characters need escaping. Knowing both gives you one format to read and one format to ship.
Where the converter earns its place in the stack
The sweet spot for a BSON converter is the layer between your application code and any storage or transport that is byte-shaped: the MongoDB driver, a Kafka Connect source, a gRPC bridge that uses BSON internally, a partner API whose payload is typed bytes. Anywhere your data goes from “JSON in memory” to “bytes on the wire”, the converter sits one layer above the actual driver and lets you see exactly what the driver is going to receive.
This matters because the driver libraries are not debuggable in the same way. A driver that silently coerces a string to a date, or a number to a string, or a missing field to a null, is correct from its own perspective and wrong from yours. The only way to argue with the driver is to inspect what you handed it. The converter is the argument.
What changes when you adopt the converter as a pre-flight step
Three things shift, and they are all subtle.
The first is that your code reviews start to include the wire format. A pull request that changes a payload now attaches the BSON hex dump of the new shape, and the reviewer can see whether the new field is an int32 or a double or a string before they read the code that produces it.
The second is that your test fixtures become richer. Instead of comparing JSON strings, you compare BSON bytes, which means the test catches type drift that JSON comparison would miss. A field that changed from int32 to int64 shows up in the byte comparison even though the JSON renders look identical.
The third is that your debugging gets faster. When a payload arrives wrong, you can paste the bytes back into the converter, decode to JSON, and read the structure in plain text. No driver, no language binding, no MongoDB instance required. The wire format becomes debuggable from anywhere you have a browser.
The contract that JSON never gave you
JSON’s contract is “be parseable”. BSON’s contract is “be typed”. The difference shows up in every system that needs to know whether a field is a date, a number with a specific precision, or a binary blob, without re-deriving the answer from the structure. If your data crosses the wire as bytes, the type is in the bytes. If your data crosses the wire as a string, the type has to be re-derived, and that is where the bugs live.
Treating the wire format as the contract means owning it end to end. Encode at the producer. Decode at the consumer. Diff at the boundary. Ship the bytes, not the wish.
Where this leaves you
The next time a payload looks fine in the dashboard and wrong in the database, the answer is almost never “the database is broken”. The answer is “the wire format has a type your code did not preserve”. A pre-flight BSON round-trip is the cheapest way to make that answer visible before production does.
Open the BSON Converter, paste a JSON payload, encode it, decode it back, and read what survived. The bytes you see are the contract you ship.
Explore more tools at elysiatools.com.
