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
message User { string display_name = 7; }After
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.
| Change pattern | Direction | Classification | Client impact |
|---|---|---|---|
| Renumber a message field | Wire | Breaking | Old and new readers stop agreeing on the field tag. |
| Remove an RPC method | Service | Breaking | Existing stubs can reach an unimplemented method. |
| Change unary to streaming | Service | Breaking | Client invocation and message flow change. |
| Add an optional field with a new tag | Wire | Usually compatible | Old binary readers can ignore the field; check JSON and SDK behavior. |
What should you check before deploying?
- Match package, service, method and streaming shape for the client in use.
- Review field numbers, presence, enum evolution, and changes to generated APIs.
- 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
- GraphQL breaking changes in schemas and operations
- gRPC and Protobuf breaking changes
- AsyncAPI breaking changes in events and messages
- SOAP and WSDL breaking changes
- Self-healing API integrations with checked migration drafts
- How to detect API contract drift before it breaks consumers
- oasdiff and API code impact analysis answer different questions.
- Detect breaking API changes in a GitHub workflow.
- Why a TypeScript build can pass after an API changes.
- OpenAI OpenAPI breaking changes: a captured response change.
- Sentry OpenAPI breaking changes: removed replay query values.
- Inspect classification rules interactively
- Check captured OpenAPI changes
- Compare JSON Schemas
- Plan your business evaluation
Use public API change evidence in your IDE with MCP
Browse public API change history, including OpenAI and Sentry.
Rule reference
schema.request_acceptance_narrowed: Request schema accepts fewer valuesoperation.endpoint_removed: Endpoint removed from the contractrequest.content_removed: Request media type removedlevel.error: Detector error falls back to breakingrequest.enum_removed: Request enum value removedrequest.now_required: Request property becomes requiredresponse.removed: Response property removedresponse.now_optional_or_nullable: Response property becomes optional or nullablerequest.removed_unknown_strictness: Request property removed, server strictness unknown