Evolving a GraphQL schema

This chapter follows Normalized caching with urql Graphcache.

Clients ship operations as static documents and mobile apps linger for months. Schema changes therefore need the same discipline as public library APIs: expand, deprecate, measure, then remove.

Safe, dangerous, and breaking changes

GraphQL validation catches some client mistakes at deploy time; semantic changes (same field name, different meaning) are not caught automatically.

Using @deprecated

Mark fields, enum values, and arguments scheduled for removal:

1
type User {
2
  email: String!
3
  legacyUsername: String @deprecated(reason: "Use profile.handle instead")
4
}

Tools surface strikethrough docs in GraphiQL. Telemetry should count how often deprecated fields appear in incoming operations before you delete them.

In NestJS code-first:

1
@Field({ deprecationReason: "Use displayName" })
2
name!: string;

Regenerated schema.gql carries @deprecated for reviewers and registries.

Deprecation workflow

A practical sequence in product teams:

1. Announce in changelog and schema descriptions.
2. Ship the replacement field or mutation alongside the old one.
3. Measure field usage from gateway logs or Apollo GraphOS / Hive metrics.
4. Notify owners of lingering operations (internal Slack, CI warnings on deprecated selections).
5. Set a sunset date communicated to partners.
6. Remove only when usage hits zero or the sunset passes; run breaking-change checks in CI.

Skipping measurement is how mobile clients break on old builds.

Field usage telemetry

Log operation name and selected fields at the gateway or server plugin layer. NestJS and Apollo Server support usage reporting plugins; open-source stacks can emit OpenTelemetry attributes per field.

Compare telemetry week-over-week before deleting deprecated paths.

Removing schema elements

When removal day arrives:

• Run schema diff tools against registered operations (graphql-inspector, Rover, Hive CLI).
• Update codegen and Graphcache possibleTypes in the same release train.
• Coordinate federation subgraph publishes if applicable.

Next: Managing GraphQL schemas in organizations.