Schema evolution strategies in GraphQL

Introduction

Schema evolution strategies help us change a GraphQL schema safely without breaking existing apps.

When you want to add new fields to your GraphQL API without stopping old clients from working.

When you need to rename or remove fields but want to keep the API stable for users.

When you want to improve or fix your schema while keeping old queries valid.

When you want to introduce new types or change existing ones without causing errors.

When you want to keep your API flexible as your app grows and changes.

Syntax

GraphQL

# Example of adding a new optional field
 type User {
   id: ID!
   name: String!
   email: String
   phone: String  # new optional field added
 }

# Example of deprecating a field
 type User {
   id: ID!
   name: String!
   email: String @deprecated(reason: "Use contactEmail instead")
   contactEmail: String
 }

Adding new optional fields is safe because old clients ignore unknown fields.

Deprecating fields with @deprecated helps clients know which fields to stop using.

Examples

This adds a new field discount without breaking existing queries.

GraphQL

# Adding a new optional field
 type Product {
   id: ID!
   name: String!
   description: String
   price: Float
   discount: Float  # new optional field
 }

This marks oldPrice as deprecated so clients know to switch to price.

GraphQL

# Deprecating a field
 type Product {
   id: ID!
   name: String!
   oldPrice: Float @deprecated(reason: "Use price instead")
   price: Float
 }

Keep the old field with deprecation while adding the new field to avoid breaking clients.

GraphQL

# Renaming a field safely
 type User {
   id: ID!
   fullName: String
   name: String @deprecated(reason: "Use fullName instead")
 }

Sample Program

This schema shows a user type where email is deprecated and replaced by contactEmail. A new optional field phone is added safely.

GraphQL

type Query {
  user(id: ID!): User
}

type User {
  id: ID!
  name: String!
  email: String @deprecated(reason: "Use contactEmail instead")
  contactEmail: String
  phone: String  # newly added optional field
}

Important Notes

Always add new fields as optional to avoid breaking existing clients.

Use the @deprecated directive to signal fields that should not be used anymore.

Removing fields should be done carefully, usually after clients have stopped using them.

Summary

Schema evolution lets you change GraphQL APIs without breaking apps.

Add new fields as optional and deprecate old ones instead of removing immediately.

Use clear deprecation reasons to guide clients to update their queries.