Evolving the Schema

Add, deprecate, remove

GraphQL APIs usually evolve without version numbers. Adding types, fields and optional arguments is non-breaking, because existing queries do not ask for them. To replace a field, add the new one, mark the old one @deprecated(reason: ...), monitor field usage until clients migrate, then remove it. Breaking changes include removing or renaming fields, making nullable fields non-null in inputs or non-null fields nullable in outputs in ways clients rely on, and changing types. Schema checks in CI compare changes against the published schema and real client usage.

Deprecating a field

GraphQL SDL.

type Product {
  id: ID!
  name: String!
  price: Float! @deprecated(reason: "Use priceMoney, which includes currency.")
  priceMoney: Money!
}

type Money {
  amount: String!     # decimal string avoids float rounding
  currency: String!
}

Track field usage

Operation and field usage metrics tell you when a deprecated field is safe to remove.

Quick check: Which schema change is non-breaking?

• Adding a new optional field
• Removing a field
• Renaming a field
• Changing a field from String to Int