DOCUMENTATION / API COMPATIBILITY
AsyncAPI breaking changes in events and messages
By Soumik Ghosh ยท Published
Compare AsyncAPI channels, operations, and event payload revisions. Check which publishers and subscribers depend on a changed field or binding.
Remove a field that an existing subscriber expects
Before
{ "eventId": "evt_1", "orderId": "order_42" }After
{ "eventId": "evt_1" }If the revised event schema permits a missing orderId, older subscribers that use it for routing or reconciliation need a compatible message version or an explicit migration.
| Change pattern | Direction | Classification | Client impact |
|---|---|---|---|
| Remove a consumer-required payload field | Message | Breaking | Existing consumer validation or business logic may fail. |
| Rename a channel address | Binding | Breaking without overlap | Producers and consumers can end up on different channels. |
| Change the payload encoding | Binding | Breaking without negotiation | Subscribers may be unable to decode events. |
| Add an optional property | Message | Review consumers | Strict consumers may reject additional properties. |
What should you check before deploying?
- Match channel addresses and send/receive operations across both revisions.
- Check message headers, payload requirements, correlation IDs, and protocol bindings.
- Replay representative old and new messages with the real subscriber codec and retry behavior.
What can ParityDiff verify?
AsyncAPI intake captures channels, operations, payload and binding metadata. Repository impact and runtime checks depend on the configured transport and message usage.
AsyncAPI specification 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