GraphQL APIs are expected to evolve without unnecessarily breaking existing clients.

GraphQL provides the @deprecated directive:

type User {
  username: String @deprecated(reason: "Use displayName instead")
  displayName: String!
}

Deprecation communicates that clients should migrate away from an existing field.

A typical migration strategy is:

Existing field
      ↓
Introduce replacement
      ↓
Mark old field deprecated
      ↓
Notify / monitor consumers
      ↓
Migrate clients
      ↓
Remove old field when safe

Do not remove fields simply because a new version of the application no longer uses them internally. GraphQL APIs may have external consumers that are not visible to the server team.

Schema registries, usage analytics, persisted operation tracking, and client communication can help determine whether a deprecated field is still in use.

Backward-compatible evolution is one of GraphQL's strengths, but only if teams actively manage schema lifecycle.