Protobuf versioning + breaking-change rules

Protobuf3 schema evolution is a wire-format problem first and a codegen problem second. The field number is the only durable identifier - every breaking-change rule derives from preserving field-number → type binding.

Per protobuf.dev/programming-guides/proto3/: "This number cannot be changed once your message type is in use because it identifies the field in the message wire format."

This is the catalog of what is breaking and why; the host SKILL.md is the detection workflow (buf breaking in CI).

When to use

• Designing a proto change - is this safe?
• Auditing an existing schema for risky patterns (un-reserved deleted fields, oneof-conversion footguns).
• Configuring buf breaking - which category fits the deployment model?
• PR review of .proto changes.

Field-number rules

When deleting a field, reserve its number:

message User {
  reserved 4, 7, 10 to 12;
  reserved "deprecated_email";

  string name = 1;
  // ...
}

Per the spec: "If you do not reserve the field number, it is possible for a developer to reuse that number in the future." Reuse → semantic corruption: old clients interpret bytes as the old type.

Binary wire-safe changes

Fully safe - old code parses new messages and vice versa with no loss:

Wire-compatible changes (conditionally safe)

These preserve wire compatibility but may be lossy or surprising:

The catch: a parser reading int64 data with int32 will silently truncate. The wire is "compatible" but the data may be lost.

Wire-incompatible changes (always breaking)

• Changing field numbers is equivalent to deleting and re-adding. Always breaks.
• Moving fields into an existing oneof is not safe.
• Changing map<k,v> key or value type.
• Changing field cardinality from singular to repeated (or vice versa) outside the wire-compatible paths.

Oneof constraints

Per protobuf.dev:

• Oneof fields cannot be repeated or map.
• "If multiple values are set, the last set value as determined by the order in the proto will overwrite all previous ones."
• Adding a field to an existing oneof is always breaking - old code can't represent the new variant; new data crashes old parsers.
• Removing a field from a oneof is breaking for the same reason.
• Converting a singular field into a single-field oneof: safe.
• Converting a single-field oneof back to singular: safe.

Map constraints

Per protobuf3 docs:

• Maps cannot be repeated.
• Key types: integral and string scalars only. "neither enum nor proto messages are valid for key_type."
• Changing a map's key or value type is breaking.

buf breaking-change taxonomy

Per buf.build/docs/breaking/rules, buf organises detection into four categories, strictest to most lenient. Full rule-ID tables: buf-breaking-rules.md.

• FILE (default) - "changes that move generated code between files, breaking generated source code on a per-file basis" (e.g. MESSAGE_NO_DELETE, FIELD_SAME_TYPE, FIELD_SAME_CARDINALITY). Choose when codegen consumers import per-file (most JVM, .NET, generated stubs in a monorepo).
• PACKAGE - breakage at package level; permits file relocations inside a package (e.g. PACKAGE_MESSAGE_NO_DELETE). Choose when consumers import by package (Go, Python).
• WIRE_JSON - "changes that break wire (binary) or JSON encoding" (e.g. FIELD_NO_DELETE_UNLESS_NUMBER_RESERVED, FIELD_SAME_JSON_NAME). Choose when consumers use both binary and JSON encoding (REST gateway + grpc).
• WIRE (most lenient) - only changes "compromising binary wire format compatibility" (e.g. FIELD_WIRE_COMPATIBLE_TYPE, allowing int32->int64). Choose when only wire format matters (binary-only protocols between server fleets you control).

Choosing the category

# buf.yaml
version: v2
breaking:
  use:
    - FILE        # most strict (default)
# OR
    - PACKAGE     # codegen friendly within-package
# OR
    - WIRE_JSON   # wire + JSON
# OR
    - WIRE        # wire only

CI invocation:

buf breaking --against ".git#branch=main"
# Compares the working tree against the main branch as baseline

Common patterns

Removing a field

Always reserve the number and the name:

message User {
+  reserved 2;
+  reserved "nickname";
   string name = 1;
-  string nickname = 2;
 }

More worked diffs - adding an optional field, renaming, promoting int32 to int64, and the oneof footgun: buf-breaking-rules.md.

Anti-patterns

Limitations

• buf categories cover binary breakage. Semantic breakage (a field's meaning changes) is not detectable. Document semantic changes in commit messages.
• JSON name changes (camelCase ↔ snake_case) detected only in WIRE_JSON.
• No transitive analysis. A message field whose type is an imported message: buf doesn't follow the import.
• Doesn't enforce naming conventions. buf lint is separate from buf breaking.

References

• protobuf3 versioning rules: protobuf.dev/programming-guides/proto3/.
• buf breaking-change rules: buf.build/docs/breaking/rules.
• Consumed by the host skill buf-cli-lint-breaking-build and grpc-streaming-test-author.
• For protobuf-schema contract-testing across services see protobuf-compat-checking.