Schema deprecations

Gracefully manage type and field deprecations

schema-design

💡 TIP

If you're an enterprise customer looking for more material on this topic, try the

Enterprise best practices: Schema design

course on Odyssey.

Not an enterprise customer?

Learn about GraphOS for Enterprise.

Leverage SDL and tooling to manage deprecations

Your graph governance group should outline a company-wide field rollover strategy to gracefully handle type and field deprecations throughout the unified graph.

GraphQL APIs can be versioned, but at Apollo, we have seen that it is far more common for organizations to leverage GraphQL's inherently evolutionary nature and iterate their APIs on a rapid and incremental basis. Doing so, however, requires clear communication with API consumers, and especially when field deprecations are required.

Use the `@deprecated` type system directive

As a first step, the @deprecated directive, which is

defined in the GraphQL specification

, should be applied when deprecating fields or enum values in a schema. Its single reason argument can also provide the API consumer some direction about what to do instead of using that field or enum value. For instance, this example we can indicate that a related topProducts query has been deprecated as follows:

1
extend type Query {
2
  """
3
  Fetch a simple list of products with an offset
4
  """
5
  topProducts(
6
    "How many products to retrieve per page."
7
    first: Int = 5
8
  ): [Product] @deprecated(reason: "Use `products` instead.")
9

10
  """
11
  Fetch a paginated list of products based on a filter type.
12
  """
13
  products(
14
    "How many products to retrieve per page."
15
    first: Int = 5
16
    "Begin paginating results after a product ID."
17
    after: Int = 0
18
    "Filter products based on a type."
19
    type: ProductType = LATEST
20
  ): ProductConnection
21
}

Use field usage metrics to assess when it's safe to remove fields

After a service's schema has been updated with new @deprecated directives, it's important to communicate the deprecations beyond the SDL as well. Using a dedicated Slack channel or team meetings might serve as appropriate communication channels for such notices, and they should be delivered with any additional migration instructions for client teams.

At this point, a crucial question still remains: "When will it be safe to remove the deprecated field?" To answer this question with certainty that you won't cause any breaking changes to client applications, you must lean on your observability tooling.

Specifically, the

Clients & Operations table

on the Insights page in

GraphOS Studio

can provide insight into what clients might still be using the deprecated fields.

In addition,

schema checks

will check any changes pushed for registered schemas against a recent window of operation tracing data to ensure that a deprecated field rollover can be completed without causing any breaking changes to existing clients. It's common to

require that clients identify themselves

so that you can reach out to them before making a breaking change.

Home