Catalog My learning Blog
gRPC and Protobuf Tutorial: Fast Microservice APIs · Phase 2 · Lesson 12 · 3 min read

Protobuf Schema Evolution: Backward Compatibility

On this page
  1. Why protobuf schemas must evolve compatibly
  2. Adding a field: safe
  3. Changing a field type: silently broken
  4. Catching breaking changes with buf breaking
  5. Safe vs unsafe protobuf changes
  6. Check yourself

Why protobuf schemas must evolve compatibly

A server deploys version 2 of a message. Some clients still run version 1, and mobile apps may run it for months. Both directions must keep working: new server with old clients, and old server with new clients. Protobuf is built for this kind of backward compatibility, as long as you follow its rules.

The idea behind every rule today is the tolerant reader: each side reads what it understands and quietly skips what it doesn't. A new server can send a field an old client has never heard of, and the old client skips it by its wire type (Day 11). An old client can omit a field the new server expects, and the server sees the default value. Problems start only when both sides read the same field number differently.

Adding a field: safe

Protobuf
// v1
message User {
  string id = 1;
  string email = 2;
}

// v2
message User {
  string id = 1;
  string email = 2;
  string display_name = 3;   // added in v2
}

Tested with protoc in both directions:

Code
v2 writes, v1 reads (old client, new server)
  id: "u1"
  email: "a@b.com"
  3: "Ana"                   <- unknown to v1, kept as raw field 3

v1 writes, v2 reads (new client, old server)
  id: "u1"
  email: "a@b.com"           <- display_name simply absent: its default ""

The old reader keeps the unknown field (and passes it through if it re-serializes the message), and the new reader sees the default. New code must therefore handle "not set" sensibly for every field it adds.

Changing a field type: silently broken

Protobuf
message User {
  string id = 1;
  int64 email = 2;            // type changed
}
Code
v1 writes, changed schema reads
  id: "u1"
  2: "a@b.com"               <- no error: the value is no longer understood as email

No exception, no error: the field quietly becomes an unknown field and email reads as 0. Some type changes are even worse, decoding into a wrong value without complaint (int32 to int64 is compatible; int32 to sint32 is not, since the encodings differ).

Adding fields is safe in both directions because unknown fields are skipped and missing ones read as defaults; changing types or reusing numbers corrupts data silently.
Adding fields is safe in both directions because unknown fields are skipped and missing ones read as defaults; changing types or reusing numbers corrupts data silently.

Catching breaking changes with buf breaking

buf breaking compares the current schema with a previous version (a Git branch, a tag, or the registry) and fails on incompatible changes. Run against the examples above with the FILE rules:

Code
add field     -> no breaking changes
change type   -> Field "2" with name "email" on message "User" changed type from "string" to "int64".
delete field  -> Previously present field "2" with name "email" on message "User" was deleted.

Add it to CI against the main branch:

Code
buf breaking --against '.git#branch=main'

Safe vs unsafe protobuf changes

ChangeSafe?
Add a field with a new numberYes
Add an enum valueYes on the wire; clients must handle unknown values (Day 3)
Add an RPC or a serviceYes
Rename a fieldBinary yes, JSON no (names are the JSON keys); Day 13
Delete a fieldOnly if its number and name are reserved (Day 13)
Change a field's typeAlmost always no
Change or reuse a field numberNever
Move a field into or out of a oneofNo
Change an RPC's request or response typeNo

Check yourself

It keeps it as an unknown field and ignores it, so decoding still succeeds and the rest of the message is read normally. That's what makes adding fields a safe change.

Many types share a wire type, so old data decodes without errors but is misread, for example an int32 read as sint32 turns positive numbers into different values. Values become wrong silently.

Run buf breaking in CI against the last released schema, such as the main branch or a registry version, and fail the build on violations, so incompatible changes can't merge unnoticed.

Adding fields with new numbers, adding RPCs, adding enum values that clients handle as unknown, and renaming fields when nobody uses the JSON form. Old readers ignore what they don't know, so these changes don't break deployed clients.

Changing field numbers or types, reusing deleted numbers, removing or renaming RPCs, and moving fields into or out of a oneof.