Allow deprecation of input values (#525)

Co-authored-by: Ivan Goncharov <[email protected]>

Author: 2 people

spec/Section 3 -- Type System.md

@@ -2032,7 +2032,7 @@ must *not* be queried if either the `@skip` condition is true *or* the
 ```graphql
 directive @deprecated(
   reason: String = "No longer supported"
-) on FIELD_DEFINITION | ENUM_VALUE
+) on FIELD_DEFINITION | ENUM_VALUE | ARGUMENT_DEFINITION | INPUT_FIELD_DEFINITION
 ```
 
 The `@deprecated` directive is used within the type system definition language
@@ -2043,12 +2043,17 @@ 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`.
+using `newField` and `oldArg` is deprecated in favor of using `newArg`.
 
 ```graphql example
 type ExampleType {
   newField: String
   oldField: String @deprecated(reason: "Use `newField`.")
+
+  existingField(
+    newArg: String,
+    oldArg: String @deprecated(reason: "Use `newArg`.")
+  ): String
 }
 ```
 

spec/Section 4 -- Introspection.md

@@ -148,7 +148,7 @@ type __Type {
   enumValues(includeDeprecated: Boolean = false): [__EnumValue!]
 
   # should be non-null for INPUT_OBJECT only, must be null for the others
-  inputFields: [__InputValue!]
+  inputFields(includeDeprecated: Boolean = false): [__InputValue!]
 
   # should be non-null for NON_NULL and LIST only, must be null for the others
   ofType: __Type
@@ -160,7 +160,7 @@ type __Type {
 type __Field {
   name: String!
   description: String
-  args: [__InputValue!]!
+  args(includeDeprecated: Boolean = false): [__InputValue!]!
   type: __Type!
   isDeprecated: Boolean!
   deprecationReason: String
@@ -171,6 +171,8 @@ type __InputValue {
   description: String
   type: __Type!
   defaultValue: String
+  isDeprecated: Boolean!
+  deprecationReason: String
 }
 
 type __EnumValue {
@@ -347,6 +349,8 @@ Fields
 * `name` must return a String.
 * `description` may return a String or {null}.
 * `inputFields`: 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}.
 
 
@@ -393,6 +397,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,
@@ -414,6 +420,9 @@ 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 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
 
@@ -439,5 +448,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.