From 29b2cf5f4699d6d10d24f81b622ce315c669a205 Mon Sep 17 00:00:00 2001 From: Stephen Spalding Date: Thu, 20 Oct 2022 11:14:37 -0700 Subject: [PATCH 1/2] Expand @deprecated to Objects Use case: objects that are members of interfaces or unions. Marking as deprecated indicates to clients that this type will no longer be returned from the server. This can indicate to client build tooling that references to this object should be removed from client queries. --- spec/Section 3 -- Type System.md | 30 +++++++++++++++++++++++++++++- spec/Section 4 -- Introspection.md | 8 ++++++-- 2 files changed, 35 insertions(+), 3 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index c98e96725..136f6e7ab 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,34 @@ 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..f812f97ce 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -109,7 +109,7 @@ 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 +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`). @@ -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 @@ -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. From 34e5723e54a66993747826843a25f8b5ae97d9ac Mon Sep 17 00:00:00 2001 From: Stephen Spalding Date: Fri, 21 Oct 2022 12:04:05 -0700 Subject: [PATCH 2/2] Add includeDeprecated argument to __type.possibleTypes Also run prettier to fix formatting --- spec/Section 3 -- Type System.md | 10 ++++++---- spec/Section 4 -- Introspection.md | 12 ++++++++---- 2 files changed, 14 insertions(+), 8 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 136f6e7ab..44fa117cc 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -2098,9 +2098,10 @@ 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. +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 { @@ -2114,7 +2115,8 @@ type DeprecatedType @deprecated { } ``` -The `@deprecated` directive should not appear on object types that are referenced by non-deprecated fields. +The `@deprecated` directive should not appear on object types that are +referenced by non-deprecated fields. ```graphql counter-example type Query { diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index f812f97ce..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, 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`). +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 @@ -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. @@ -315,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** @@ -336,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**