From 94f73f48c12a6bdafa9dc729a89482aa7917303f Mon Sep 17 00:00:00 2001 From: Ivan Goncharov Date: Fri, 3 Jun 2022 08:49:17 +0300 Subject: [PATCH] Allow deprecation of input values (field args, directive args, input fields) (#805) Adds the ability to deprecate arguments, directive arguments, and input fields on input types. Exposes these deprecations via the introspection system with the same mechanism as found in existing field deprecations. Adds a schema validation rule for @deprecated on required arguments - The `@deprecated` directive must not appear on required (non-null without a default) arguments or input object field definitions. Deprecated arguments and fields are excluded by default in introspection, and deprecating required arguments or input fields could create confusion for clients. Co-authored-by: Kevin Smithson Co-authored-by: Lee Byron Co-authored-by: Ivan Maximov Co-authored-by: Stephen Spalding --- spec/Section 3 -- Type System.md | 31 +++++++++++++++++++++++++++--- spec/Section 4 -- Introspection.md | 25 ++++++++++++++++++------ 2 files changed, 47 insertions(+), 9 deletions(-) diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index b539b936e..0d44913a6 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -879,6 +879,8 @@ of rules must be adhered to by every Object type in a GraphQL schema. {"\_\_"} (two underscores). 2. The argument must accept a type where {IsInputType(argumentType)} returns {true}. + 3. If argument type is Non-Null and a default value is not defined: + - The `@deprecated` directive must not be applied to this argument. 3. An object type may declare that it implements one or more unique interfaces. 4. An object type must be a super-set of all interfaces it implements: 1. Let this object type be {objectType}. @@ -1652,6 +1654,8 @@ input ExampleInputObject { {"\_\_"} (two underscores). 3. The input field must accept a type where {IsInputType(inputFieldType)} returns {true}. + 4. If input field type is Non-Null and a default value is not defined: + - The `@deprecated` directive must not be applied to this input field. 3. If an Input Object references itself either directly or through referenced Input Objects, at least one of the fields in the chain of references must be either a nullable or a List type. @@ -2047,26 +2051,47 @@ condition is false. ```graphql directive @deprecated( reason: String = "No longer supported" -) on FIELD_DEFINITION | ENUM_VALUE +) on FIELD_DEFINITION | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION | ENUM_VALUE ``` The `@deprecated` _built-in directive_ is used within the type system definition language to indicate deprecated portions of a GraphQL service's schema, such as -deprecated fields on a type or deprecated enum values. +deprecated fields on a type, arguments on a field, input fields on an input +type, or values of an enum type. Deprecations include a reason for why it is deprecated, which is formatted using Markdown syntax (as specified by [CommonMark](https://commonmark.org/)). In this example type definition, `oldField` is deprecated in favor of using -`newField`. +`newField` and `oldArg` is deprecated in favor of using `newArg`. ```graphql example type ExampleType { newField: String oldField: String @deprecated(reason: "Use `newField`.") + + anotherField( + newArg: String + oldArg: String @deprecated(reason: "Use `newArg`.") + ): String +} +``` + +The `@deprecated` directive must not appear on required (non-null without a +default) arguments or input object field definitions. + +```graphql counter-example +type ExampleType { + invalidField( + newArg: String + oldArg: String! @deprecated(reason: "Use `newArg`.") + ): String } ``` +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. + ### @specifiedBy ```graphql diff --git a/spec/Section 4 -- Introspection.md b/spec/Section 4 -- Introspection.md index 9b32133f8..63a5981b9 100644 --- a/spec/Section 4 -- Introspection.md +++ b/spec/Section 4 -- Introspection.md @@ -108,9 +108,10 @@ CommonMark-compliant Markdown renderer. **Deprecation** -To support the management of backwards compatibility, GraphQL fields and enum -values can indicate whether or not they are deprecated (`isDeprecated: Boolean`) -and a description of why it is deprecated (`deprecationReason: String`). +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`). Tools built using GraphQL introspection should respect deprecation by discouraging deprecated use through information hiding or developer-facing @@ -145,7 +146,7 @@ type __Type { # must be non-null for ENUM, otherwise null. enumValues(includeDeprecated: Boolean = false): [__EnumValue!] # must be non-null for INPUT_OBJECT, otherwise null. - inputFields: [__InputValue!] + inputFields(includeDeprecated: Boolean = false): [__InputValue!] # must be non-null for NON_NULL and LIST, otherwise null. ofType: __Type # may be non-null for custom SCALAR, otherwise null. @@ -166,7 +167,7 @@ enum __TypeKind { type __Field { name: String! description: String - args: [__InputValue!]! + args(includeDeprecated: Boolean = false): [__InputValue!]! type: __Type! isDeprecated: Boolean! deprecationReason: String @@ -177,6 +178,8 @@ type __InputValue { description: String type: __Type! defaultValue: String + isDeprecated: Boolean! + deprecationReason: String } type __EnumValue { @@ -190,7 +193,7 @@ type __Directive { name: String! description: String locations: [__DirectiveLocation!]! - args: [__InputValue!]! + args(includeDeprecated: Boolean = false): [__InputValue!]! isRepeatable: Boolean! } @@ -367,6 +370,8 @@ Fields\: - `name` must return a String. - `description` may return a String or {null}. - `inputFields` must return the set of input fields as a list of `__InputValue`. + - Accepts the argument `includeDeprecated` which defaults to {false}. If + {true}, deprecated input fields are also returned. - All other fields must return {null}. **List** @@ -412,6 +417,8 @@ Fields\: - `description` may return a String or {null} - `args` returns a List of `__InputValue` representing the arguments this field accepts. + - Accepts the argument `includeDeprecated` which defaults to {false}. If + {true}, deprecated arguments are also returned. - `type` must return a `__Type` that represents the type of value returned by this field. - `isDeprecated` returns {true} if this field should no longer be used, @@ -432,6 +439,10 @@ Fields\: - `defaultValue` may return a String encoding (using the GraphQL language) of the default value used by this input value in the condition a value is not provided at runtime. If this input value has no default value, returns {null}. +- `isDeprecated` returns {true} if this input field or argument should no longer + be used, otherwise {false}. +- `deprecationReason` optionally provides a reason why this input field or + argument is deprecated. ### The \_\_EnumValue Type @@ -483,5 +494,7 @@ Fields\: locations this directive may be placed. - `args` returns a List of `__InputValue` representing the arguments this directive accepts. + - Accepts the argument `includeDeprecated` which defaults to {false}. If + {true}, deprecated arguments are also returned. - `isRepeatable` must return a Boolean that indicates if the directive may be used repeatedly at a single location.