Proto Evolution and Backward Compatibility

In a gRPC microservice world, your .proto files are a contract shared between independently deployed services. A producer service and its many consumers rarely upgrade at the exact same moment.

During a rolling deploy you will have old clients talking to new servers and new clients talking to old servers simultaneously. Evolution rules exist so neither side crashes or silently corrupts data.

• Backward compatible: new code can read data written by old code.
• Forward compatible: old code can read data written by new code (Protobuf gives this for free if you follow the rules).

Break the rules and you get mismatched fields, lost data, or deserialization that maps bytes to the wrong field.

The single most important idea: on the wire, Protobuf does not send field names. It sends field numbers. The name email is just a label for humans and generated code.

Each encoded field is a tag built from (field_number << 3) | wire_type followed by its value. That means:

• Renaming a field is harmless on the wire (number unchanged).
• Changing a field's number is a breaking change — old data for number 2 will be read as a different field.

Here is a v1 message for a user service. Notice every field has an explicit, stable number. In a Node.js backend you typically load this with @grpc/proto-loader and @grpc/grpc-js.

The golden rule going forward: once a field number ships to production, it is permanent. Treat numbers like database primary keys — never reuse, never repurpose.

The safest evolution is adding a new field with a brand-new number. Old clients simply ignore tags they do not recognize, and new clients reading old data see the field's default value.

• In proto3, an unset string defaults to "", numbers to 0, bools to false.
• So always design new fields so that the default value is a safe, meaningful state.

Below, phone (field 4) is added. A v1 client ignores it; a v2 client reading a v1 payload gets "".

When an old server receives a message containing fields it does not know about, Protobuf preserves them as unknown fields (in many runtimes) rather than erroring. This is what makes forward compatibility work.

The practical consequence: a service in the middle of a pipeline can receive a newer message, and as long as it does not re-serialize destructively, the new data can pass through untouched.

You should never rely on a field not existing. Always tolerate extra data.

Suppose you delete email = 3 and later add country = 3. Disaster: an old client still sends an email string tagged with field 3. The new server happily decodes those bytes as if they were country.

Because field numbers are the wire identity, reuse causes silent data corruption — no exception, just wrong values flowing through your system.

The fix is to permanently retire deleted numbers so no future engineer can accidentally recycle them.

Protobuf's answer is the reserved keyword. When you remove a field, you reserve its number and its name. The compiler then refuses to let anyone reuse them.

• reserved 3; — blocks reusing field number 3.
• reserved "email"; — blocks reusing the name email (helps if old generated code or JSON mapping relies on it).

This turns a silent runtime corruption into a compile-time error, which is exactly where you want failures to happen.

When you remove several fields at once, reserve them all in one statement. Ranges use to, and max covers the upper bound.

• reserved 2, 15, 9 to 11; reserves individual numbers and a contiguous block.
• You can reserve numbers and names in separate statements, but not mix them in a single one.

Keep a running 'graveyard' comment so the history of retired fields is visible to reviewers.

Some type changes preserve wire compatibility because the wire type stays the same; others silently break.

• Safe: int32 ↔ int64 ↔ uint32 ↔ uint64 ↔ bool — all varints (just mind value ranges/truncation).
• Safe: string ↔ bytes when bytes are valid UTF-8 (both length-delimited).
• Unsafe: int32 → string, or changing between fixed32 and int32 — different wire types, garbled decode.

When in doubt, add a new field instead of mutating an existing one.

Enums evolve too. In proto3 every enum must have a zero value (the default), conventionally *_UNSPECIFIED = 0. You can append new values safely — old clients receiving an unknown enum number keep the raw integer and treat it as unrecognized.

• Always handle the default/unknown case in your Node.js switch logic.
• Never renumber existing enum values; reserve removed ones just like fields.

Teams enforce these rules automatically. Tools like buf run breaking-change detection in CI, but you can also encode simple invariants yourself. The core invariants:

• No field number is ever removed without a matching reserved.
• No field number changes its type family.
• New fields use numbers higher than any previously used or reserved.

Below is a tiny guard you might run against two parsed schema snapshots in a Node.js pipeline step.

You are removing the email field (number 3) from a deployed proto message. What is the correct way to keep the contract evolvable and prevent future corruption?

You now know how to evolve gRPC contracts without breaking running services:

• Field numbers, not names, are the wire identity — they are permanent once shipped.
• Add fields with fresh numbers; old clients ignore them and new clients see safe defaults.
• Protobuf preserves unknown fields, giving you forward compatibility for free.
• Reserve removed numbers and names (reserved 3; reserved "email";) to prevent silent corruption from reuse.
• Change types only within the same wire-type family; otherwise add a new field.
• Append enum values, always handle the unknown/UNSPECIFIED case, and enforce all of this in CI.

Follow these rules and old and new versions of your services can coexist safely through every rolling deploy.