From ff20cb43b42372f82f7f39db5c1a180baf79bc99 Mon Sep 17 00:00:00 2001
From: Stephen Spalding <sspalding@netflix.com>
Date: Wed, 5 Jan 2022 21:14:24 -0800
Subject: [PATCH] Add validation 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.
---
 spec/Section 3 -- Type System.md | 16 ++++++++++++++++
 spec/Section 5 -- Validation.md  | 23 +++++++++++++++++++++++
 2 files changed, 39 insertions(+)

diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md
index 6bdf1d558..393412c5a 100644
--- a/spec/Section 3 -- Type System.md	
+++ b/spec/Section 3 -- Type System.md	
@@ -2060,6 +2060,22 @@ 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
 
diff --git a/spec/Section 5 -- Validation.md b/spec/Section 5 -- Validation.md
index 34b99820d..0042554c7 100644
--- a/spec/Section 5 -- Validation.md	
+++ b/spec/Section 5 -- Validation.md	
@@ -738,6 +738,7 @@ and 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.
 
@@ -785,6 +786,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
@@ -1419,6 +1432,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.
 
@@ -1429,6 +1443,15 @@ 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