Skip to content
API Design Learn/gRPC Fundamentals
Browsing as a guest. Sign in to save your progress and earn XP as you complete chapters.

Evolving the Wire Format

4 min read

You'll learn to

  • -List which protobuf changes are safe and which are not, and why the field number is the key
  • -Run an old reader against data from a newer writer and see the unknown field ignored
  • -Use oneof for "exactly one of these", and add an option to it safely

Protobuf was designed with change in mind. Old clients with new servers, or new clients with old servers, must keep working together during a rolling deployment. This is the same problem as the REST versioning chapter, with protobuf's own specific rules.

An Analogy: A Form With Numbered Boxes

Picture a paper form where every box has a printed number. A newer version of the form adds box 5. A clerk with the old form simply does not read box 5. But if someone moves "date of birth" from box 3 to box 7, the old clerk reads box 3 and finds something else entirely. The number, not the label, is what everyone relies on.

What's Safe to Change

  • -Safe: adding a new field with a new, never-used number. Old code ignores fields it does not recognize.
  • -Safe: removing a field, as long as its number is marked reserved so it is never reused.
  • -Unsafe: changing a field's number. The wire identifies fields by number, so a change looks like removing the old field and adding an unrelated one.
  • -Unsafe: changing a field to an incompatible type, such as string to int32. Some changes within a family are safe, such as int32 to int64, but most are not.
  • -Generally safe: renaming a field. The wire carries only the number, so already-compiled programs are unaffected. It does affect human-readable forms, such as protobuf's JSON mapping, and generated code that uses the name.

oneof: Exactly One of Several Types

A field that holds exactly one of several possible shapes
message PaymentMethod {
  oneof method {
    CreditCard credit_card = 1;
    BankTransfer bank_transfer = 2;
    DigitalWallet digital_wallet = 3;
  }
}

oneof declares that exactly one of the listed fields is set at a time. Setting credit_card clears bank_transfer or digital_wallet if either was set, and generated code lets you ask which is set now. It is protobuf's version of a union type. Without it, three optional fields for mutually exclusive choices leave it possible, and wrong, for more than one to be set at once.

Adding a New oneof Option

Extending a oneof is additive, as long as the new field number is unused
message PaymentMethod {
  oneof method {
    CreditCard credit_card = 1;
    BankTransfer bank_transfer = 2;
    DigitalWallet digital_wallet = 3;
    Cryptocurrency cryptocurrency = 4;   // new option, safe to add
  }
}

Adding an option to an existing oneof is additive and safe, under the usual rule of a new field with a new number. Old clients that do not know about cryptocurrency cannot build or recognize it, but they are not broken by its existence. They just do not support it yet. The demo runs all of this: an old reader meeting a newer message, a rename that leaves the bytes untouched, and a oneof that clears itself.

Press Run: the unknown field is ignored, a rename changes nothing on the wire, and a oneof holds one value

A common slip is reordering fields in the .proto file. For the wire format that is genuinely cosmetic, since only numbers matter, but it can still confuse a human comparing old and new versions of the schema. Treat the field numbers as the source of truth, not a field's position in the file.

Interview Signal is part of Pro

See a real weak answer next to a real strong one for this exact topic.

Quiz is part of Pro

Test what you just read with a short quiz, and bank the XP.

Ready to Build This?

Design Wire Evolution in the API Design Lab's gRPC & Event-Driven act.

Discussion0

Join the Discussion

Sign in to leave comments, reply to others, or like insights.

Sign In to ScaleDojo

No comments yet. Be the first to start the thread!