DOCUMENTATION / API COMPATIBILITY
GraphQL breaking changes in schemas and operations
By Soumik Ghosh ยท Published
Learn how removing a GraphQL field or tightening an input breaks existing operations, and what to verify in persisted queries and generated clients.
Remove a field selected by an existing query
Before
type Product { id: ID! legacySku: String }After
type Product { id: ID! }A query selecting legacySku fails validation against the revised schema. Existing clients may keep sending that operation through a persisted query or generated SDK.
| Change pattern | Direction | Classification | Client impact |
|---|---|---|---|
| Remove a selected field | Response | Breaking | Operations that select the field fail validation. |
| Make an input field required | Request | Breaking without a default | Old variables may omit the field. |
| Make an output field nullable | Response | Breaking for non-null assumptions | Clients must handle null. |
| Add an enum output value | Response | Review consumers | Exhaustive branches may need a fallback. |
What should you check before deploying?
- Validate the actual operation documents against the revised schema.
- Compare argument and input field requirements, output nullability, and enum assumptions in generated clients.
- Test the affected operation with the application client and its configured schema.
What can ParityDiff verify?
The GraphQL contract adapter captures schema types, fields and operation metadata. Repository evidence depends on resolving the operation and a configured client or transport adapter.
GraphQL specification on validation 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