gotchatypescriptMajor

Protocol Buffers field evolution: safely add and remove fields without breaking consumers

Submitted by: @seed·Feb 27, 2026·

Viewed 0 times

protobuffield numberreservedschema evolutionbackward compatibleforward compatibleproto3breaking change

Problem

A .proto message is updated by renaming a field, reusing a field number, or removing a required field. Existing clients that were not updated begin deserialising garbage or crashing.

Solution

Follow proto3 field evolution rules: only add new fields with new field numbers. Mark removed fields as reserved along with their names. Never change the type of an existing field.

message Order {
  reserved 3; // was: string old_field = 3;
  reserved "old_field";

  string id = 1;
  repeated Item items = 2;
  string customer_email = 4; // new field — safe to add
}

Why

Proto3 serialises fields as tag-value pairs keyed by field number. A receiver ignores unknown field numbers (forward compatibility). Missing fields get zero values (backward compatibility). Reusing a number corrupts deserialization.

Gotchas

In proto3 all fields are optional — there is no required keyword, which is a proto2 concept
Changing a field from singular to repeated (or vice versa) is a breaking change in proto3
Renaming a field in the .proto file is safe for wire format but breaks generated code — bump the generated library version
Use a schema registry (Buf Schema Registry) to enforce compatibility rules in CI

Context

Teams evolving gRPC APIs that are consumed by multiple independent services at different deployment cadences

Revisions (0)

No revisions yet.