From ba78f0040c170bf69db5c14dc247bb342275a515 Mon Sep 17 00:00:00 2001
From: Stephen Spalding <fotoetienne@users.noreply.github.com>
Date: Thu, 6 Jan 2022 12:59:22 -0800
Subject: [PATCH] Add validation for @deprecated on required arguments (#917)

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.
---
 spec/Section 3 -- Type System.md | 17 +++++++++++++++++
 spec/Section 5 -- Validation.md  | 24 ++++++++++++++++++++++++
 2 files changed, 41 insertions(+)

diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md
index 7f29899bc..df6bc813f 100644
--- a/spec/Section 3 -- Type System.md	
+++ b/spec/Section 3 -- Type System.md	
@@ -2073,6 +2073,23 @@ type ExampleType {
 }
 ```
 
+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
diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md
index 4eda8e7b4..076b55d2f 100644
--- a/spec/Section 5 -- Validation.md	
+++ b/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