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

GraphQL
type Product { id: ID! legacySku: String }

After

GraphQL
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.

Compatibility patterns to review
Change patternDirectionClassificationClient impact
Remove a selected fieldResponseBreakingOperations that select the field fail validation.
Make an input field requiredRequestBreaking without a defaultOld variables may omit the field.
Make an output field nullableResponseBreaking for non-null assumptionsClients must handle null.
Add an enum output valueResponseReview consumersExhaustive branches may need a fallback.

What should you check before deploying?

  1. Validate the actual operation documents against the revised schema.
  2. Compare argument and input field requirements, output nullability, and enum assumptions in generated clients.
  3. 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

Use public API change evidence in your IDE with MCP

Browse public API change history, including OpenAI and Sentry.

Rule reference