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 <[email protected]>
Co-authored-by: Lee Byron <[email protected]>
Co-authored-by: Ivan Maximov <[email protected]>
Co-authored-by: Stephen Spalding <[email protected]>

Author: 5 people

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

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.