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.