Allow deprecation of input values (#525)

Co-authored-by: Ivan Goncharov <ivan.goncharov.ua@gmail.com>

spec/Section 3 -- Type System.md

@@ -2047,7 +2047,7 @@ condition is false.
 ```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` _built-in directive_ is used within the type system definition
@@ -2058,12 +2058,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`.
+`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

@@ -145,7 +145,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 +166,7 @@ enum __TypeKind {
 type __Field {
   name: String!
   description: String
-  args: [__InputValue!]!
+  args(includeDeprecated: Boolean = false): [__InputValue!]!
   type: __Type!
   isDeprecated: Boolean!
   deprecationReason: String
@@ -177,6 +177,8 @@ type __InputValue {
   description: String
   type: __Type!
   defaultValue: String
+  isDeprecated: Boolean!
+  deprecationReason: String
 }
 
 type __EnumValue {
@@ -367,6 +369,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 +416,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 +438,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 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 +493,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.