English for Protocol Buffers (Protobuf) Developers
Vocabulary for developers defining Protocol Buffers schemas — field numbers, wire format, and backward compatibility — for teams discussing serialization contracts in English.
Most Protobuf disagreements in review are really about schema evolution — whether a change is safe for services that haven’t redeployed yet. Having precise vocabulary for compatibility lets a reviewer say exactly why a change is risky, instead of a vague “that might break something.”
Schema Basics
.proto file — the schema definition file describing messages and their fields, from which Protobuf generates typed code for every target language a project uses.
“Don’t hand-edit the generated Go structs — change the .proto file and regenerate, or your fix disappears on the next codegen run.”
Message — a structured data type defined in a .proto file, roughly analogous to a class or struct, composed of typed, numbered fields.
“Add a new message instead of overloading this one with unrelated optional fields — it’s getting hard to tell what a valid instance even looks like.”
Field number — the small integer tag assigned to each field in a message, used in the binary wire format instead of the field’s name; this number, not the name, is what actually identifies the field on the wire.
“You can rename this field freely — just never change or reuse its field number, since that’s what actually identifies it in the encoded bytes.”
Wire Format and Encoding
Wire format — the compact binary encoding Protobuf uses to serialize messages, built around field numbers and types rather than field names, which is what makes it smaller and faster to parse than JSON.
“There’s no field name in the actual bytes on the wire — that’s why the field number is permanent and the field name is just a code-generation convenience.”
Varint — a variable-length integer encoding Protobuf uses for most numeric types, where small values take fewer bytes, which is part of why Protobuf payloads are typically smaller than equivalent JSON.
“Small counters like this cost almost nothing on the wire — varint encoding means a value under 128 takes a single byte.”
Compatibility
Backward compatibility — a schema change that doesn’t break older clients or servers still running the previous schema version, which is the default assumption Protobuf’s design optimizes for.
“Adding a new optional field is backward compatible — old binaries just ignore the field they don’t know about.”
Breaking change (in Protobuf) — reusing a field number for a different field, changing a field’s type incompatibly, or renumbering an existing field, any of which corrupts decoding for services on a different schema version.
“Reusing field number 4 for a different type is the single most dangerous thing you can do here — an old service will misinterpret the bytes entirely, not just fail cleanly.”
Reserved fields/numbers — explicitly marking a removed field’s number (and often its name) as reserved so it can never accidentally be reused by a future field, protecting against exactly that class of breaking change.
“Mark field 7 as reserved after removing it — that way nobody adds a new field with that number six months from now and silently breaks every service still on the old schema.”
Common Mistakes
- Renaming a field and assuming that alone is safe, without checking whether its field number was also changed.
- Reusing a deleted field’s number for a new, unrelated field instead of marking it reserved.
- Treating Protobuf compatibility rules as optional style preferences rather than the mechanism that keeps mixed-version services from silently corrupting data.
Practice Exercise
- Explain, in two sentences, why the field number matters more than the field name in Protobuf’s wire format.
- Write a short PR comment explaining why reusing a removed field’s number is unsafe and reserving it instead.
- Draft a message distinguishing a backward-compatible schema change from a breaking one for a teammate proposing a field type change.