diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index c98e96725..44fa117cc 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2057,7 +2057,7 @@ condition is false. ```graphql directive @deprecated( reason: String = "No longer supported" -) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE +) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE | OBJECT ``` The `@deprecated` _built-in directive_ is used within the type system definition @@ -2098,6 +2098,36 @@ type ExampleType { To deprecate a required argument or input field, it must first be made optional by either changing the type to nullable or adding a default value. +The `@deprecated` directive is useful for object types that are included in +unions or interfaces. Deprecating the type indicates to clients that the server +will no longer be returning this type and clients should remove references to +this type in their queries. + +```graphql example +type Query { + returnsUnion: MyUnion +} + +union MyUnion = ExampleType | DeprecatedType + +type DeprecatedType @deprecated { + id: ID +} +``` + +The `@deprecated` directive should not appear on object types that are +referenced by non-deprecated fields. + +```graphql counter-example +type Query { + returnsDeprecatedType: DeprecatedType +} + +type DeprecatedType @deprecated { + id: ID +} +``` + ### @specifiedBy ```graphql diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 3aa4e40e0..30c8fc930 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -109,9 +109,9 @@ CommonMark-compliant Markdown renderer. **Deprecation** To support the management of backwards compatibility, GraphQL fields, arguments, -input fields, and enum values can indicate whether or not they are deprecated -(`isDeprecated: Boolean`) along with a description of why it is deprecated -(`deprecationReason: String`). +input fields, enum values, and objects can indicate whether or not they are +deprecated (`isDeprecated: Boolean`) along with a description of why it is +deprecated (`deprecationReason: String`). Tools built using GraphQL introspection should respect deprecation by discouraging deprecated use through information hiding or developer-facing @@ -126,7 +126,7 @@ which are fully defined in the sections below. ```graphql type __Schema { description: String - types: [__Type!]! + types(includeDeprecated: Boolean = false): [__Type!]! queryType: __Type! mutationType: __Type subscriptionType: __Type @@ -142,7 +142,7 @@ type __Type { # must be non-null for OBJECT and INTERFACE, otherwise null. interfaces: [__Type!] # must be non-null for INTERFACE and UNION, otherwise null. - possibleTypes: [__Type!] + possibleTypes(includeDeprecated: Boolean = false): [__Type!] # must be non-null for ENUM, otherwise null. enumValues(includeDeprecated: Boolean = false): [__EnumValue!] # must be non-null for INPUT_OBJECT, otherwise null. @@ -151,6 +151,8 @@ type __Type { ofType: __Type # may be non-null for custom SCALAR, otherwise null. specifiedByURL: String + isDeprecated: Boolean! + deprecationReason: String } enum __TypeKind { @@ -236,6 +238,8 @@ Fields\: - `types` must return the set of all named types contained within this schema. Any named type which can be found through a field of any introspection type must be included in this set. + - Accepts the argument `includeDeprecated` which defaults to {false}. If + {true}, deprecated fields are also returned. - `directives` must return the set of all directives available within this schema including all built-in directives. @@ -311,6 +315,8 @@ Fields\: - `description` may return a String or {null}. - `possibleTypes` returns the list of types that can be represented within this union. They must be object types. + - Accepts the argument `includeDeprecated` which defaults to {false}. If + {true}, deprecated fields are also returned. - All other fields must return {null}. **Interface** @@ -332,6 +338,8 @@ Fields\: (if none, `interfaces` must return the empty set). - `possibleTypes` returns the list of types that implement this interface. They must be object types. + - Accepts the argument `includeDeprecated` which defaults to {false}. If + {true}, deprecated fields are also returned. - All other fields must return {null}. **Enum**