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

Protobuf Reserved Fields and Deprecation

On this page
  1. The danger of reusing a field number
  2. Removing a field in three stages
  3. What buf breaking says at each step
  4. Renaming fields: safe for binary, breaking for JSON
  5. Reserving enum values
  6. Check yourself

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:

Protobuf
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:

Protobuf
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.

A field moves from active to deprecated, clients migrate, then it's deleted with its number and name reserved so neither can be reused.
A field moves from active to deprecated, clients migrate, then it's deleted with its number and name reserved so neither can be reused.

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:

Code
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):

Code
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

Code
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 changes

The 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:

Code
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.