DOCUMENTATION / API COMPATIBILITY

gRPC and Protobuf breaking changes

By Soumik Ghosh ยท Published

Check gRPC methods, Protobuf field numbers, generated client compatibility, and the difference between binary and JSON consumers.

Keep field numbers stable when evolving a message

Before

Protobuf
message User { string display_name = 7; }

After

Protobuf
message User { string display_name = 9; reserved 7; }

A binary reader generated from the original definition expects field 7. Moving the same property to field 9 makes each revision ignore the field written by the other. Reserving 7 prevents reuse but cannot restore compatibility.

Compatibility patterns to review
Change patternDirectionClassificationClient impact
Renumber a message fieldWireBreakingOld and new readers stop agreeing on the field tag.
Remove an RPC methodServiceBreakingExisting stubs can reach an unimplemented method.
Change unary to streamingServiceBreakingClient invocation and message flow change.
Add an optional field with a new tagWireUsually compatibleOld binary readers can ignore the field; check JSON and SDK behavior.

What should you check before deploying?

  1. Match package, service, method and streaming shape for the client in use.
  2. Review field numbers, presence, enum evolution, and changes to generated APIs.
  3. Test old and new clients with your actual codec. ProtoJSON names and binary tags have different compatibility rules.

What can ParityDiff verify?

Protobuf intake captures service and method identity with native message schemas. Repository and runtime checks require the relevant generated symbols, codec and configured toolchain.

Protobuf guide to updating message types and the contract support matrix.

API compatibility guides and tools

Use public API change evidence in your IDE with MCP

Browse public API change history, including OpenAI and Sentry.

Rule reference