Implementing Schema Versioning

1. Understanding API Versioning

Strategy	GraphQL Equivalent
URL versioning (REST)	Avoided — single endpoint
Schema evolution	Add fields, deprecate old
Per-field deprecation	@deprecated reason
Namespace types	Optional `v2_User` for major rewrites

type User {
  fullName: String! @deprecated(reason: "Use firstName + lastName since 2026-01")
  firstName: String!
  lastName: String!
}

Rule	Detail
Always safe	Existing clients ignore unknown fields
Default nullable	Avoid forcing existing data to provide value
Document	Include description string

Type of Change	Safety
Add nullable arg	Safe
Add required arg without default	Breaking
Add required arg with default	Safe
Remove arg	Breaking

Change	Migration
Type change	Add new field with new type, deprecate old
Required arg added	Use new field name to opt in
Field removal	Long deprecation window
Enum value rename	Add new value, deprecate old, accept both

type Query {
  v2: V2Query!
}
type V2Query {
  user(id: ID!): V2User
}

Use	Detail
Major rewrites	Coexist with v1 fields
Internal vs public	internal { ... } namespace

Directive	Use
@deprecated	Standard deprecation
@inaccessible	Hide from federation supergraph
@tag	Annotate for governance/contracts
@since(version)	Custom: indicate when added

Channel	Detail
Schema changelog	Auto-generate via graphql-inspector
Schema diff in PR	CI annotation
Client notifications	Email registered API consumers
Status page	Document deprecation timeline

Step	Tool
Detect deprecated usage	graphql-eslint `no-deprecated`
Auto-migrate	Codemods
Validate	graphql-codegen against new schema
Deploy	Update client before server removes