Schema Evolution and Deprecation

As a product grows, a field that once met its needs may become too limited. Suppose a bookstore has served plain-text book descriptions for years and now needs descriptions in several languages, with the response explicitly naming the language. Replacing the existing string with an object would suit the new interface, but older mobile applications still expect the string.

GraphQL supports gradual schema evolution, but compatibility requires more than adding a deprecation marker.

This chapter explains how to classify changes, introduce replacements, migrate consumers, and decide when removing an old capability is justified.