# Evolving the Schema — GraphQL

Source: https://www.skillbyai.com/en/graphql/x-evolution

> Change without versioning.

## 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.

```graphql
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.

**Quiz:** Which schema change is non-breaking?

- [x] Adding a new optional field
- [ ] Removing a field
- [ ] Renaming a field
- [ ] Changing a field from String to Int

*Answer:* Adding a new optional field. Existing queries are unaffected.