RFC: Client Controlled Nullability

spec/Appendix B -- Grammar Summary.md

@@ -48,7 +48,7 @@ Token ::
 - FloatValue
 - StringValue
 
-Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | }
+Punctuator :: one of ! ? $ & ( ) ... : = @ [ ] { | }
 
 Name ::
 
@@ -156,10 +156,15 @@ Selection :
 - FragmentSpread
 - InlineFragment
 
-Field : Alias? Name Arguments? Directives? SelectionSet?
+Field : Alias? Name Arguments? Nullability? Directives? SelectionSet?
 
 Alias : Name :
 
+Nullability :
+
+- !
+- ?
+
 Arguments[Const] : ( Argument[?Const]+ )
 
 Argument[Const] : Name : Value[?Const]

spec/Section 2 -- Language.md

@@ -177,7 +177,7 @@ characters are permitted between the characters defining a {FloatValue}.
 
 ### Punctuators
 
-Punctuator :: one of ! $ & ( ) ... : = @ [ ] { | }
+Punctuator :: one of ! ? $ & ( ) ... : = @ [ ] { | }
 
 GraphQL documents include punctuation in order to describe structure. GraphQL is
 a data description language and not a programming language, therefore GraphQL
@@ -351,7 +351,7 @@ selection set. Selection sets may also contain fragment references.
 
 ## Fields
 
-Field : Alias? Name Arguments? Directives? SelectionSet?
+Field : Alias? Name Arguments? Nullability? Directives? SelectionSet?
 
 A selection set is primarily composed of fields. A field describes one discrete
 piece of information available to request within a selection set.
@@ -515,6 +515,115 @@ which returns the result:
 }
 ```
 
+## Nullability
+
+Nullability :
+
+- ListNullability NullabilityModifier?
+- NullabilityModifier
+
+ListNullability : `[` Nullability? `]`
+
+NullabilityModifier :
+
+- `!`
+- `?`
+
+Fields can have their nullability designated with either a `!` to indicate that
+a field should be `Non-Nullable` or a `?` to indicate that a field should be
+`Nullable`. These designators override the nullability set on a field by the
+schema for the operation where they're being used. In addition to being
+`Non-Nullable`, if a field marked with `!` resolves to `null`, it propagates to
+the nearest parent field marked with a `?` or to `data` if one does not exist.
+An error is added to the `errors` array identical to if the field had been
+`Non-Nullable` in the schema.
+
+In this example, we can indicate that a `user`'s `name` that could possibly be
+`null`, should not be `null` and that `null` propagation should halt at the
+`user` field:
+
+```graphql example
+{
+  user(id: 4)? {
+    id
+    name!
+  }
+}
+```
+
+If `name` comes back non-`null`, then the return value is the same as if the
+nullability designator was not used:
+
+```json example
+{
+  "user": {
+    "id": 4,
+    "name": "Mark Zuckerberg"
+  }
+}
+```
+
+In the event that `name` is `null`, the field's parent selection set becomes
+`null` in the result and an error is returned, just as if `name` was marked
+`Non-Nullable` in the schema:
+
+```json example
+{
+  "data": {
+    "user": null
+  },
+  "errors": [
+    {
+      "locations": [{ "column": 13, "line": 4 }],
+      "message": "Cannot return null for non-nullable field User.name.",
+      "path": ["user", "name"]
+    }
+  ]
+}
+```
+
+If `user` was `Non-Nullable` in the schema, but we don't want `null`s
+propagating past that point, then we can use `?` to create null propagation
+boundary. `User` will be treated as `Nullable` for this operation:
+
+```graphql example
+{
+  user(id: 4)? {
+    id
+    name!
+  }
+}
+```
+
+Nullability designators can also be applied to list elements like so.
+
+```graphql example
+{
+  user(id: 4)? {
+    id
+    petsNames[!]?
+  }
+}
+```
+
+In the above example, the query author is saying that each individual pet name
+should be `Non-Nullable`, but the list as a whole should be `Nullable`. The same
+syntax can be applied to multidimensional lists.
+
+```graphql example
+{
+  threeDimensionalMatrix[[[?]!]]!
+}
+```
+
+Any element without a nullability designator will inherit its nullability from
+the schema definition, exactly the same as non-list fields do. When designating
+nullability for list fields, query authors can either use a single designator
+(`!` or `?`) to designate the nullability of the entire field, or they can use
+the list element nullability syntax displayed above. The number of dimensions
+indicated by list element nullability syntax is required to match the number of
+dimensions of the field. Anything else results in a query validation error.
+
 ## Fragments
 
 FragmentSpread : ... FragmentName Directives?

spec/Section 5 -- Validation.md

@@ -564,6 +564,45 @@ fragment conflictingDifferingResponses on Pet {
 }
 ```
 
+The same is true if a field is designated `Non-Nullable` in an operation. In
+this case, `someValue` could be either a `String` or a `String!` which are two
+different types and therefore can not be merged:
+
+```graphql counter-example
+fragment conflictingDifferingResponses on Pet {
+  ... on Dog {
+    someValue: nickname
+  }
+  ... on Cat {
+    someValue: nickname!
+  }
+}
+```
+
+### Client Controlled Nullability Designator List Dimensions
+
+**Formal Specification**
+
+- For each {field} in the document
+  - Let {fieldDef} be the definition of {field}
+  - Let {fieldType} be the type of {fieldDef}
+  - Let {requiredStatus} be the required status of {field}
+  - Let {designatorDepth} be the number of square bracket pairs in
+    {requiredStatus}
+  - Let {typeDepth} be the number of list dimensions in {fieldType}
+  - If {typeDepth} equals {designatorDepth} or {designatorDepth} equals 0 return
+    true
+  - Otherwise return false
+
+**Explanatory Text**
+
+List fields can be marked with nullability designators that look like `[?]!` to
+indicate the nullability of the list's elements and the nullability of the list
+itself. For multi-dimensional lists, the designator would look something like
+`[[[!]?]]!`. If the designator is not a simple `!` or `?`, then the number of
+dimensions of the designator are required to match the number of dimensions of
+the field's type. If the two do not match then a validation error is thrown.
+
 ### Leaf Field Selections
 
 **Formal Specification**

spec/Section 6 -- Execution.md

@@ -570,13 +570,69 @@ ExecuteField(objectType, objectValue, fieldType, fields, variableValues):
 
 - Let {field} be the first entry in {fields}.
 - Let {fieldName} be the field name of {field}.
+- Let {requiredStatus} be the required status of {field}.
 - Let {argumentValues} be the result of {CoerceArgumentValues(objectType, field,
   variableValues)}
 - Let {resolvedValue} be {ResolveFieldValue(objectType, objectValue, fieldName,
   argumentValues)}.
-- Return the result of {CompleteValue(fieldType, fields, resolvedValue,
+- Let {modifiedFieldType} be {ModifiedOutputType(fieldType, requiredStatus)}.
+- Return the result of {CompleteValue(modifiedFieldType, fields, resolvedValue,
   variableValues)}.
 
+## Accounting For Client Controlled Nullability Designators
+
+A field can have its nullability status set either in its service's schema, or a
+nullability designator (! or ?) can override it for the duration of an
+execution. In order to determine a field's true nullability, both are taken into
+account and a final type is produced.
+
+ModifiedOutputType(outputType, requiredStatus):
+
+- Create a {stack} initially containing {type}.
+- As long as the top of {stack} is a list:
+  - Let {currentType} be the top item of {stack}.
+  - Push the {elementType} of {currentType} to the {stack}.
+- If {requiredStatus} exists:
+  - Start visiting {node}s in {requiredStatus} and building up a
+    {resultingType}:
+    - For each {node} that is a RequiredDesignator:
+      - If {resultingType} exists:
+        - Let {nullableResult} be the nullable type of {resultingType}.
+        - Set {resultingType} to the Non-Nullable type of {nullableResult}.
+        - Continue onto the next node.
+      - Pop the top of {stack} and let {nextType} be the result.
+      - Let {nullableType} be the nullable type of {nextType}.
+      - Set {resultingType} to the Non-Nullable type of {nullableType}.
+      - Continue onto the next node.
+    - For each {node} that is a OptionalDesignator:
+      - If {resultingType} exists:
+        - Set {resultingType} to the nullableType type of {resultingType}.
+        - Continue onto the next node.
+      - Pop the top of {stack} and let {nextType} be the result.
+      - Set {resultingType} to the nullable type of {resultingType}
+      - Continue onto the next node.
+    - For each {node} that is a ListNullabilityDesignator:
+      - Pop the top of {stack} and let {listType} be the result
+      - If the nullable type of {listType} is not a list
+        - Pop the top of {stack} and set {listType} to the result
+      - If {listType} does not exist:
+        - Throw an error because {requiredStatus} had more list dimensions than
+          {outputType} and is invalid.
+      - If {resultingType} exist:
+        - If {listType} is Non-Nullable:
+          - Set {resultingType} to a Non-Nullable list where the element is
+            {resultingType}.
+        - Otherwise:
+          - Set {resultingType} to a list where the element is {resultingType}.
+        - Continue onto the next node.
+      - Set {resultingType} to {listType}
+- If {stack} is not empty:
+  - Throw an error because {requiredStatus} had fewer list dimensions than
+    {outputType} and is invalid.
+- Return {resultingType}.
+- Otherwise:
+  - Return {outputType}.
+
 ### Coercing Field Arguments
 
 Fields may include arguments which are provided to the underlying runtime in
@@ -778,9 +834,9 @@ field returned {null}, and the error must be added to the {"errors"} list in the
 response.
 
 If the result of resolving a field is {null} (either because the function to
-resolve the field returned {null} or because a field error was raised), and that
-field is of a `Non-Null` type, then a field error is raised. The error must be
-added to the {"errors"} list in the response.
+resolve the field returned {null} or because a field error was raised), and the
+{ModifiedOutputType} of that field is of a `Non-Null` type, then a field error
+is raised. The error must be added to the {"errors"} list in the response.
 
 If the field returns {null} because of a field error which has already been
 added to the {"errors"} list in the response, the {"errors"} list must not be
@@ -789,8 +845,8 @@ field.
 
 Since `Non-Null` type fields cannot be {null}, field errors are propagated to be
 handled by the parent field. If the parent field may be {null} then it resolves
-to {null}, otherwise if it is a `Non-Null` type, the field error is further
-propagated to its parent field.
+to {null}, otherwise if its {ModifiedOutputType} is a `Non-Null` type, the field
+error is further propagated to its parent field.
 
 If a `List` type wraps a `Non-Null` type, and one of the elements of that list
 resolves to {null}, then the entire list must resolve to {null}. If the `List`

spec/Section 7 -- Response.md

@@ -160,10 +160,11 @@ The response might look like:
 }
 ```
 
-If the field which experienced an error was declared as `Non-Null`, the `null`
-result will bubble up to the next nullable field. In that case, the `path` for
-the error should include the full path to the result field where the error was
-raised, even if that field is not present in the response.
+If the field which experienced an error was declared as `Non-Null` or designated
+`Non-Null` in the query document, the `null` result will propagate to the next
+nullable field. In that case, the `path` for the error should include the full
+path to the result field where the error was raised, even if that field is not
+present in the response.
 
 For example, if the `name` field from above had declared a `Non-Null` return
 type in the schema, the result would look different but the error reported would