system-design

Serialization: JSON, Protobuf, Avro, Thrift

Turning objects into bytes and back. Usually the biggest CPU cost in a service, and the thing that breaks when you deploy a new version.

Prerequisites: Computer Fundamentals Time to read: ~16 minutes

The problem

Your service has a User object in memory. Another service, on another machine, in another language, needs it. Memory layouts don’t travel — you must convert it to a byte sequence, ship it, and reconstruct it on the other side.

Every choice you make here shows up in three places:

CPU: serialization is frequently the single largest CPU consumer in a service that “just returns data.”
Bandwidth and latency: payload size directly determines transfer time.
Deployability: when you add a field and deploy to half your fleet, does the other half break?

That third one is the one that causes outages.

The main options

JSON

{"id": 42, "name": "Bilal", "email": "b@example.com", "active": true}

The default for public APIs, and rightly so. Human-readable, debuggable with curl, supported everywhere, no schema or code generation required.

Costs:

Verbose. Field names are repeated in every single record. In an array of 10,000 users, the string "email" appears 10,000 times.
Slow to parse. Text parsing, string allocation, and number conversion. Often 5–10× slower than binary formats.
Weakly typed. No distinction between int and float; int64 values silently lose precision in JavaScript (which is why every serious API returns large IDs as strings).
No schema by default. Nothing enforces that active is a boolean. (JSON Schema exists and is underused.)

📐 A user record is ~70 bytes as JSON, ~25 bytes as protobuf. At 100,000 QPS that’s 4.5 MB/s of pure field-name overhead.

Protocol Buffers (protobuf)

Schema-first, binary, from Google. The default for internal service-to-service communication.

syntax = "proto3";

message User {
  int64  id     = 1;      // field NUMBERS are the wire identity, not names
  string name   = 2;
  string email  = 3;
  bool   active = 4;
}

You compile this into generated classes for Go, Java, Python, C++, etc. On the wire, only the field number, type, and value are sent — never the name.

Gains: 3–10× smaller, 5–10× faster to parse, statically typed, and the schema is a real contract enforced by the compiler.

Costs: unreadable on the wire (you need the schema to decode it), a build step, and coordination when schemas change.

The killer feature — safe evolution. Because fields are identified by number:

message User {
  int64  id     = 1;
  string name   = 2;
  string email  = 3;
  bool   active = 4;
  string phone  = 5;      // NEW: old readers ignore field 5. Nothing breaks.
}

Rules that make this work:

✅ Add new optional fields with new numbers.
✅ Remove a field — but reserved 5; the number so nobody reuses it.
❌ Never change a field’s number. Field 3 meaning email in one version and phone in another means one service will read a phone number into an email field, silently.
❌ Never change a field’s type incompatibly.

🚨 That “never reuse a field number” rule is the most important operational fact about protobuf, and it’s a great thing to mention in an interview about API evolution.

Apache Avro

Schema-first, binary, from the Hadoop ecosystem. Dominant in data pipelines and Kafka.

Its distinguishing idea: the schema travels with the data — either embedded in the file header (for batch files) or referenced by ID via a schema registry (for streaming).

Why this matters for data: the reader uses both the writer’s schema and its own, and resolves between them. That gives you excellent schema evolution for long-lived data — you can read a file written three years ago with today’s code.

Gains: no code generation required (dynamic typing possible), very compact, best-in-class schema evolution, first-class integration with Kafka via Confluent Schema Registry.

Costs: you need the schema to read anything (so the registry becomes critical infrastructure), and it’s less convenient for RPC than protobuf.

Apache Thrift

From Facebook. Similar to protobuf, but ships with an RPC framework and transport layer built in. Used at Facebook, Uber, Evernote. Largely superseded by gRPC + protobuf in new systems, but you’ll meet it in older codebases.

MessagePack, CBOR, BSON

“Binary JSON” — schemaless binary formats. Smaller and faster than JSON, no schema or build step, still self-describing. A good middle ground when you want JSON’s flexibility with less overhead. MongoDB uses BSON internally; Redis clients and IoT protocols often use MessagePack or CBOR.

Language-native serialization — don’t

Java Serializable, Python pickle, Ruby Marshal, .NET BinaryFormatter.

🚨 Avoid these for anything crossing a process boundary. Three reasons:

Security. Deserializing untrusted pickle or Java-serialized data is remote code execution. This has caused numerous major CVEs.
No cross-language support. You’ve permanently coupled to one runtime.
Fragile versioning. Class changes break deserialization of old data in unpredictable ways.

Fine for a local cache you control end to end. Never for an API, a queue, or persisted data.

The comparison

	JSON	Protobuf	Avro	MessagePack
Human-readable	✅	❌	❌	❌
Schema required	❌	✅	✅	❌
Relative size	1×	0.2–0.4×	0.2–0.4×	0.6–0.8×
Relative parse speed	1×	5–10×	5–10×	2–3×
Schema evolution	Manual/convention	Excellent (field numbers)	Excellent (reader+writer schemas)	Manual
Code generation	No	Yes	Optional	No
Best for	Public APIs, config, debugging	Internal RPC (gRPC)	Data pipelines, Kafka, long-lived storage	Compact messaging without a build step

Choosing

Simple decision rules that hold up in interviews:

Situation	Use	Why
Public REST API	JSON	Every client can consume it; debuggability wins
Internal service-to-service, high volume	Protobuf + gRPC	Size, speed, and a compiler-enforced contract
Kafka topics, event streams, data lake	Avro + Schema Registry	Schema evolution for data that outlives the code
Browser-facing	JSON	It’s what the platform speaks
Mobile with constrained bandwidth	Protobuf	Payload size directly costs users money and battery
Config files	YAML/JSON/TOML	Humans edit them
Caching in Redis	MessagePack or protobuf	Compact, fast; readability rarely matters

🎙️ “I’d use JSON at the public edge for compatibility and debuggability, and protobuf over gRPC internally — at our internal call volume, the CPU spent on JSON parsing is a real cost, and the schema gives us a contract that breaks at build time instead of in production.”

Schema evolution: the part that causes outages

Whatever format you pick, you will deploy version N and version N+1 simultaneously. Rolling deploys guarantee it. Mobile apps guarantee it for years.

Two directions, and you need both:

Backward compatible — new code can read old data. (You deploy new servers; old messages are still in the queue.)
Forward compatible — old code can read new data. (You deploy to half the fleet; old servers receive messages from new ones.)

Rules that keep you safe:

✅ Safe	❌ Breaking
Add an optional field with a default	Add a required field
Remove an optional field (and reserve its number/name)	Remove a field others still read
Add a new enum value — if readers handle unknowns	Rename a field
Widen a type where the format allows	Change a field’s type or number
Add a new endpoint / message type	Change a field’s meaning while keeping its name

🚨 That last one is the nastiest: repurposing status from "active"/"inactive" to "active"/"paused"/"cancelled" doesn’t break parsing — it breaks logic, silently, in every consumer that has an if status == "inactive" branch. No schema system catches this. Only a new field does.

🚨 New enum values are a classic production bug. Producer adds PENDING_REVIEW; a consumer’s switch statement has no case for it and either throws or falls into a wrong default. Always design consumers to handle unknown enum values explicitly.

A schema registry (Confluent Schema Registry for Avro/protobuf, or Buf for protobuf) makes this enforceable: it stores schema versions and rejects a producer whose new schema breaks compatibility with what consumers expect. This turns a production incident into a CI failure, which is exactly where you want it.

Compression: usually worth it

Compression is a separate layer, and it’s usually a clear win.

Algorithm	Ratio	Speed	Use
gzip	Good	Moderate	The safe default; universally supported
brotli	Better (~15–20% over gzip)	Slower to compress	Static web assets, precompressed
Snappy	Modest	Very fast	Internal data, Kafka, databases
zstd	Excellent	Fast, tunable	Increasingly the best all-round choice
LZ4	Modest	Fastest	When CPU is the constraint

📐 The trade is lopsided in compression’s favour. Compressing 1 KB costs ~2 µs of CPU. Sending 700 fewer bytes over a link with 50–150 ms RTT and limited bandwidth saves vastly more. Enable gzip or brotli on HTTP responses by default.

When not to compress: already-compressed data (JPEG, MP4, PNG), very small payloads (under ~1 KB the overhead isn’t worth it), and situations where you’re CPU-bound and bandwidth-rich (some in-datacenter paths — use Snappy or LZ4 there rather than nothing).

⚖️ Trade-offs

Choice	Gain	Cost
JSON	Universal, debuggable, no build step	3–5× larger, 5–10× slower to parse, no enforced schema
Binary + schema	Small, fast, contract-enforced	Build step, opaque on the wire, registry to operate
Schema registry	Breaking changes caught in CI	New critical infrastructure to run
Compression	Big bandwidth savings	CPU cost; nothing for already-compressed data
Language-native	Trivial to use	Insecure, single-language, fragile versioning

In the real world

Google runs essentially all internal RPC on protobuf. The scale argument is simple: at their call volume, the CPU difference between text and binary parsing is measured in datacenters.
Confluent’s Schema Registry became standard in the Kafka ecosystem because uncontrolled schema drift between producers and consumers is one of the most common ways data pipelines break — and because the failure is usually silent and discovered days later in a report.
Public APIs stay on JSON even at companies that use protobuf everywhere internally (Google, Stripe, GitHub), because the cost of every external developer needing a compiler toolchain outweighs the bytes saved. gRPC-Web and Connect exist to bridge this, but JSON at the edge remains the pragmatic default.

🚨 Interview traps

Never mentioning serialization cost. In a high-throughput design, it’s a real CPU line item and mentioning it shows depth.
Using JSON for a high-volume internal path without acknowledging the cost, or using protobuf for a public API without acknowledging the friction.
Ignoring schema evolution. “How do you deploy a change to this message format without downtime?” is a very common follow-up. The answer is: add optional fields, never reuse numbers, and enforce compatibility in CI.
Using pickle/Java serialization across a trust boundary. An immediate security flag.
Forgetting that mobile clients are old. Your v1 message format needs to be readable by an app from 2023 that will never update.

🎙️ Soundbites

“JSON at the public edge, protobuf over gRPC internally — the internal call volume makes parsing cost real, and the schema turns a class of production bugs into build failures.”
“For Kafka I’d use Avro with a schema registry, so a producer can’t deploy a schema that breaks existing consumers. That check belongs in CI, not in an incident.”
“We’ll have both versions running during the rollout, so every change has to be backward *and forward compatible — new optional fields only, and consumers must tolerate unknown enum values.”*
“I’d enable compression on responses. Two microseconds of CPU to save several hundred bytes over a 150 ms link is an easy trade.”

🛠️ Try it

1. Measure the difference. Take a realistic object (say 20 fields, nested). Serialize 100,000 of them as JSON and as protobuf. Compare total bytes and wall-clock time. The numbers are usually more dramatic than people expect.

2. Break compatibility on purpose. Define a protobuf message, generate code, serialize a message. Then change field 3’s number to 7, regenerate, and try to deserialize the old bytes. Watch what happens — and note that it doesn’t error, it silently produces wrong data. That’s the lesson.

3. See the wire format.

# Encode with protoc and hexdump it
echo 'id: 42 name: "Bilal"' | protoc --encode=User user.proto | xxd

Count the bytes. Compare to {"id":42,"name":"Bilal"}. Notice the field names are simply absent.

Check yourself

1. Why can protobuf add fields without breaking old consumers, while JSON APIs need more care?

Protobuf identifies fields by *number*, and decoders are specified to skip unknown field numbers. So an old consumer reading a new message simply ignores the fields it doesn't know about. JSON has no such contract — behaviour depends on the parser and the application code (strict parsers reject unknown keys; lenient ones ignore them), so you must establish "ignore unknown fields" as a convention and enforce it in every client.

2. Why must you never reuse a protobuf field number?

Because the number *is* the field's identity on the wire. If field 5 meant `phone` in v1 and you reuse 5 for `country_code` in v2, a v1 consumer reading a v2 message will decode a country code as a phone number — and if the types happen to be compatible, it won't even error. It's a silent data corruption bug. Use `reserved 5;` when you delete a field so the compiler prevents anyone from reusing it.

3. When is JSON the right choice despite being slower and larger?

Public APIs (every language and tool consumes it with zero setup), anything humans debug by reading (`curl` output, logs, config), browser-facing endpoints, low-volume internal calls where the performance difference is irrelevant, and early-stage products where iteration speed beats efficiency. The rule: optimize serialization when it's measurably a bottleneck, not by default.

4. A producer adds a new enum value. What breaks, and how do you prevent it?

Consumers that don't have a case for the new value — they throw, or silently fall into a default branch that does the wrong thing. Neither the schema nor the serializer catches this, because the data parses fine. Prevention: design consumers to explicitly handle unknown values (log, route to a dead-letter queue, or treat as a documented "unrecognized" state), deploy consumer changes *before* producer changes, and use a schema registry with compatibility checks.

5. Why is deserializing untrusted pickle data dangerous?

Because pickle's format can encode arbitrary object construction and callable invocation — the deserializer is effectively an interpreter. A crafted payload runs arbitrary code in your process at deserialize time, before any validation you'd write. The same class of vulnerability affects Java `Serializable` and .NET `BinaryFormatter`. Use a data-only format (JSON, protobuf, Avro) for anything crossing a trust boundary; those can produce malformed data but not code execution.