Protobuf Schema Evolution: Backward Compatibility
On this page
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
// 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:
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
message User {
string id = 1;
int64 email = 2; // type changed
}v1 writes, changed schema reads
id: "u1"
2: "a@b.com" <- no error: the value is no longer understood as emailNo 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).
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:
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:
buf breaking --against '.git#branch=main'Safe vs unsafe protobuf changes
| Change | Safe? |
|---|---|
| Add a field with a new number | Yes |
| Add an enum value | Yes on the wire; clients must handle unknown values (Day 3) |
| Add an RPC or a service | Yes |
| Rename a field | Binary yes, JSON no (names are the JSON keys); Day 13 |
| Delete a field | Only if its number and name are reserved (Day 13) |
| Change a field's type | Almost always no |
| Change or reuse a field number | Never |
| Move a field into or out of a oneof | No |
| Change an RPC's request or response type | No |
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.