Binary JSON Formats

Learning Focus

When JSON's text format becomes a bottleneck — payload size, parse time, or missing types — binary formats offer order-of-magnitude improvements.

Why Go Binary?

JSON Limitation	Binary Solution
No native binary/blob type	BSON Binary, CBOR bytes
No native Date type	BSON Date, CBOR datetime
Large text payloads	MessagePack: 50–80% smaller
No integer vs float distinction	Protocol Buffers: strongly typed

Format Comparison

Format	Self-Describing	Schema Required	Common Users
BSON	✓	✗	MongoDB
MessagePack	✓	✗	Redis, Fluentd
Protocol Buffers	✗	✓	Google, gRPC
CBOR	✓	✗	IoT, WebAuthn
Avro	✗	✓	Apache Kafka

BSON (Python)

from bson import ObjectId, encode, decode
from datetime import datetime

document = {"_id": ObjectId(), "name": "Alice", "createdAt": datetime.utcnow()}
raw  = encode(document)    # BSON bytes
back = decode(raw)         # Python dict with native types

MessagePack (Python)

# pip install msgpack
import msgpack

data   = {"name": "Alice", "scores": [98, 87, 92]}
packed = msgpack.packb(data, use_bin_type=True)
print(f"JSON: {len(json.dumps(data))} bytes | MsgPack: {len(packed)} bytes")

unpacked = msgpack.unpackb(packed, raw=False)

Decision Flowchart

Format Selection Guide

• Need human-readable / debug output? → JSON
• Using MongoDB? → BSON
• Building a gRPC service with strict types? → Protocol Buffers
• IoT device or IETF protocol? → CBOR
• General-purpose binary serialization? → MessagePack

Common Pitfalls

Pitfall	Consequence	Prevention
Binary format for config	Human-unreadable	Keep config as JSON/YAML
Unversioned Protobuf schemas	Field conflicts break serialization	Follow Protobuf schema evolution rules
BSON over a REST API	Clients expect JSON	Serialize to JSON at the API boundary
Premature optimization	Complexity for minimal gain	Profile first; JSON is fast enough for most APIs

What's Next

• Previous: NDJSON and JSON Lines — Streaming text format.
• Next: Best Practices and Troubleshooting — Production-ready JSON conventions.
• Section Overview — Return to the Advanced module index.