Guide clients to a replacement
A field has a replacement with a different name or shape.
GraphQL · Directive
@deprecated
@deprecated marks a GraphQL field or enum value as obsolete while keeping it available to clients. Its optional reason tells users what to use instead.
How it works
Place @deprecated on a schema field or enum value to signal that clients should migrate away from it. Its optional reason describes the replacement or rationale; if omitted, the default reason is "No longer supported".
Syntax
directive @deprecated(reason: String = "No longer supported") on FIELD_DEFINITION | ENUM_VALUEParameters
| Name | Type | Description |
|---|---|---|
reason | String | Optional explanation of the deprecation and recommended migration; defaults to "No longer supported". |
Key points
- Directives attach metadata or behavior to schema elements; @deprecated communicates that an element should no longer be used.
- @deprecated is one of GraphQL's built-in directives.
- Its SDL declaration takes an optional String reason and permits placement on field definitions or enum values.
- A reason should identify the migration target or recommended replacement.
- Development tools can surface deprecation warnings to client authors.
Common mistakes
- The reason argument is nullable and accepts a String; provide a useful migration instruction rather than relying on the default.
Example: Deprecate a field
type User {
fullName: String
name: String @deprecated(reason: "Use `fullName`.")
}The schema keeps name available while directing clients toward fullName.
When to use it
Retire an enum value safely
An enum member should remain readable for existing clients during migration.
Stage a schema migration
A schema change must be introduced without immediately breaking existing queries.
Interview questions
QWhat does @deprecated do?
@deprecated marks a field or enum value as deprecated without immediately removing it. In SDL implementations, its reason argument defaults to "No longer supported".
Follow-up: Where can it be applied? The documented locations are FIELD_DEFINITION and ENUM_VALUE.
QWhat is the directive signature?
Its declaration accepts an optional String reason and limits use to schema field definitions and enum values. The reason can explain what clients should use instead.
Follow-up: What happens when reason is omitted? The directive supplies the default text "No longer supported".
QWhy deprecate instead of removing a field immediately?
A deprecated field remains part of the schema, but tools can use the deprecation metadata to guide clients toward a replacement. This supports evolving a schema without an immediate breaking removal.
Follow-up: How should a replacement be represented? Add the new field, then mark the old field with a reason naming the replacement.
Related
directivesFIELD_DEFINITIONENUM_VALUEGraphiQLschema evolution