Protobuf Reserved Fields and Deprecation
On this page
The danger of reusing a field number
A team deletes email = 2 from User. Months later, someone adds int64 loyalty_points = 2. Old clients still sending email strings in field 2 now feed garbage into loyalty points, and old messages in queues and storage decode wrongly. Nothing errors; the data is just wrong (Day 12). Reserving removed numbers prevents this.
Removing a field in three stages
1. Deprecate. Mark the field, keep it working. Deprecation is a signal, not a removal:
message User {
string id = 1;
string email = 2 [deprecated = true]; // use contact_email
string contact_email = 3;
}Generated code marks the accessor deprecated, so compilers and IDEs warn anyone still using it. Keep populating both fields for a while.
2. Migrate. Move clients to the new field and verify that nothing reads or writes the old one (logs, usage metrics, searches across repositories).
3. Delete and reserve:
message User {
reserved 2;
reserved "email";
string id = 1;
string contact_email = 3;
}reserved 2 stops anyone reusing the number; reserved "email" stops the name being reused, which matters for JSON.
What buf breaking says at each step
buf's breaking-change rule sets differ in strictness. With the FILE set (the strictest, protecting generated source code), any deletion is breaking, reserved or not:
FILE, delete + reserve:
Previously present field "2" with name "email" on message "User" was deleted.That's because deleting a field removes its accessor from generated code, breaking code that calls it. With WIRE_JSON (protecting the binary and JSON wire formats only):
WIRE_JSON, delete + reserve: no breaking changes
WIRE_JSON, delete without reserving:
... was deleted without reserving the name "email".
... was deleted without reserving the number "2".Choose the rule set per API: FILE or PACKAGE for libraries whose generated code others compile against, WIRE_JSON when only the wire format matters, plus a reviewed exception when you deliberately remove a deprecated field.
Renaming fields: safe for binary, breaking for JSON
rename email -> mail, WIRE_JSON:
Field "2" with name "mail" on message "User" changed option "json_name" from "email" to "mail".
Field "2" on message "User" changed name from "email" to "mail".
rename email -> mail, WIRE: no breaking changesThe binary format only uses numbers, so a rename is invisible there. But the JSON mapping uses field names as keys, so gRPC-Gateway, gRPC-Web JSON clients, logs and anything reading protojson output break. If JSON clients exist, treat renames as breaking.
Reserving enum values
Removing an enum value has the same risks. Reserve its number and name inside the enum:
enum Status {
reserved 5;
reserved "STATUS_REFUNDED";
STATUS_UNSPECIFIED = 0;
// ...
}Check yourself
So it can never be reused for a different field, which would make old data and old clients decode into the wrong field.
The FILE category protects generated source code as well as the wire format. Deleting a field removes its accessor from generated code, which breaks any code still using it, even though the bytes stay compatible.
For the binary format yes, since only field numbers travel on the wire. For the JSON mapping no, because field names become the JSON keys, so clients using JSON or transcoding break.
Mark it deprecated, stop writing and reading it in all services, then delete it and add its number and name to reserved.
Reusing a removed enum number makes old stored data and old clients interpret it as the new meaning, such as a past CANCELLED becoming REFUNDED. Reserving the number and name makes protoc reject accidental reuse.