Allow deprecation of input values (field args, directive args, input fields)

spec/Section 3 -- Type System.md

@@ -2047,26 +2047,49 @@ 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. Deprecated arguments and
+fields are excluded by default in introspection, and deprecating required
+arguments or input fields could create confusion for clients.
+
+```graphql counter-example
+type ExampleType {
+  invalidField(
+    newArg: String
+    oldArg: String! @deprecated(reason: "Use `newArg`.")
+  ): String
 }
 ```
 
+A required argument or input field should 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 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.

spec/Section 5 -- Validation.md

@@ -736,6 +736,7 @@ invalid.
     - Let {argumentName} be the name of {argumentDefinition}.
     - Let {argument} be the argument in {arguments} named {argumentName}
     - {argument} must exist.
+    - {argument} must not be deprecated.
     - Let {value} be the value of {argument}.
     - {value} must not be the {null} literal.
 
@@ -783,6 +784,18 @@ fragment missingRequiredArg on Arguments {
 }
 ```
 
+If an argument is required (non-null without a default value), it must not be
+marked as deprecated.
+
+```graphql counter-example
+type Query {
+  """
+  This is invalid because the locale argument is both required and deprecated.
+  """
+  myName(locale: String! @deprecated): String
+}
+```
+
 ## Fragments
 
 ### Fragment Declarations
@@ -1396,6 +1409,7 @@ For example the following document will not pass validation.
     - Let {fieldName} be the name of {fieldDefinition}.
     - Let {field} be the input field in {fields} named {fieldName}
     - {field} must exist.
+    - {field} must not be deprecated.
     - Let {value} be the value of {field}.
     - {value} must not be the {null} literal.
 
@@ -1406,6 +1420,16 @@ arguments, an input object may have required fields. An input field is required
 if it has a non-null type and does not have a default value. Otherwise, the
 input object field is optional.
 
+A required input object field must not be marked as deprecated.
+
+```graphql counter-example
+input Point {
+  x: Int!
+  y: Int!
+  z: Int! @deprecated(reason: "Northward, not upward")
+}
+```
+
 ## Directives
 
 ### Directives Are Defined