updated to reflect newest behavior

Author: twof

spec/Appendix B -- Grammar Summary.md

@@ -162,8 +162,15 @@ Alias : Name :
 
 Nullability :
 
-- !
-- ?
+- ListNullability NullabilityDesignator?
+- NullabilityDesignator
+
+ListNullability : `[` Nullability? `]`
+
+NullabilityDesignator :
+
+- `!`
+- `?`
 
 Arguments[Const] : ( Argument[?Const]+ )
 

spec/Section 2 -- Language.md

@@ -519,12 +519,12 @@ which returns the result:
 
 Nullability :
 
-- ListNullability NullabilityModifier?
-- NullabilityModifier
+- ListNullability NullabilityDesignator?
+- NullabilityDesignator
 
 ListNullability : `[` Nullability? `]`
 
-NullabilityModifier :
+NullabilityDesignator :
 
 - `!`
 - `?`
@@ -534,13 +534,14 @@ 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.
+the nearest parent field marked with a `?` or to `data` if there is not a parent
+marked with a `?`. 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:
+`user` field. We can use `?` to create null propagation boundary. `user` will be
+treated as `Nullable` for this operation:
 
 ```graphql example
 {
@@ -551,8 +552,8 @@ In this example, we can indicate that a `user`'s `name` that could possibly be
 }
 ```
 
-If `name` comes back non-`null`, then the return value is the same as if the
-nullability designator was not used:
+If `name` is resolved to a value other than `null`, then the return value is the
+same as if the designators were not used:
 
 ```json example
 {
@@ -563,9 +564,9 @@ nullability designator was not used:
 }
 ```
 
-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:
+In the event that `name` resolves to `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
 {
@@ -582,19 +583,33 @@ In the event that `name` is `null`, the field's parent selection set becomes
 }
 ```
 
-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:
+If `!` is used on a field and it is not paired with `?` on a parent, then `null`
+will propagate all the way to the `data` response field.
 
 ```graphql example
 {
-  user(id: 4)? {
+  user(id: 4) {
     id
     name!
   }
 }
 ```
 
+Response:
+
+```json example
+{
+  "data": null,
+  "errors": [
+    {
+      "locations": [{ "column": 13, "line": 4 }],
+      "message": "Cannot return null for non-nullable field User.name.",
+      "path": ["user", "name"]
+    }
+  ]
+}
+```
+
 Nullability designators can also be applied to list elements like so.
 
 ```graphql example
@@ -616,13 +631,13 @@ syntax can be applied to multidimensional lists.
 }
 ```
 
-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.
+Any field without a nullability designator will inherit its nullability from the
+schema definition. 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
 

spec/Section 5 -- Validation.md

@@ -565,16 +565,16 @@ 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
+this case, `nickname` 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
+    nickname
   }
   ... on Cat {
-    someValue: nickname!
+    nickname!
   }
 }
 ```
@@ -587,8 +587,10 @@ fragment conflictingDifferingResponses on Pet {
   - 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
+  - Let {designatorDepth} be the number of ListNullability operators in
     {requiredStatus}
+  - If {designatorDepth} is 0
+    - return true
   - Let {typeDepth} be the number of list dimensions in {fieldType}
   - If {typeDepth} equals {designatorDepth} or {designatorDepth} equals 0 return
     true
@@ -599,7 +601,7 @@ fragment conflictingDifferingResponses on Pet {
 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
+`[[[!]?]]!`. If any `ListNullability` operators are used 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.
 

spec/Section 6 -- Execution.md

@@ -564,30 +564,49 @@ Each field requested in the grouped field set that is defined on the selected
 objectType will result in an entry in the response map. Field execution first
 coerces any provided argument values, then resolves a value for the field, and
 finally completes that value either by recursively executing another selection
-set or coercing a scalar value.
+set or coercing a scalar value. `ccnPropagationPairs` is an unordered map where
+the keys are paths of required fields, and values are paths of the nearest
+optional parent to those required fields. `currentPropagationPath` starts as an
+empty path to indicate that `null` propagation should continue until it hits
+`data` if there is no optional field.
 
-ExecuteField(objectType, objectValue, fieldType, fields, variableValues):
+ExecuteField(objectType, objectValue, fieldType, fields, variableValues,
+currentPropagationPath, ccnPropagationPairs):
 
 - 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 {newPropagationPath} be {path} if {requiredStatus} is optional, otherwise
+  let {newPropagationPath} be {currentPropagationPath}
+- If {requiredStatus} is optional:
+  - Let {newPropagationPath} be {path}
+- If {requiredStatus} is required:
+  - Set {path} to {newPropagationPath} in {ccnPropagationPairs}
 - Let {argumentValues} be the result of {CoerceArgumentValues(objectType, field,
   variableValues)}
 - Let {resolvedValue} be {ResolveFieldValue(objectType, objectValue, fieldName,
   argumentValues)}.
-- Let {modifiedFieldType} be {ModifiedOutputType(fieldType, requiredStatus)}.
+- Let {modifiedFieldType} be {ApplyRequiredStatus(fieldType, requiredStatus)}.
 - Return the result of {CompleteValue(modifiedFieldType, fields, resolvedValue,
-  variableValues)}.
+  variableValues, newPropagationPath, ccnPropagationPairs)}.
 
 ## 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
+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):
-
+account and a final type is produced. A field marked with a `!` is called a
+"required field" and a field marked with a `?` is called an optional field.
+
+ApplyRequiredStatus(type, requiredStatus):
+
+- If there is no {requiredStatus}:
+  - return {type}
+- If {requiredStatus} is not a list:
+  - If {requiredStatus} is required:
+    - return a `Non-Null` version of {type}
+  - If {requiredStatus} is optional:
+    - return a nullable version of {type}
 - Create a {stack} initially containing {type}.
 - As long as the top of {stack} is a list:
   - Let {currentType} be the top item of {stack}.
@@ -616,8 +635,8 @@ ModifiedOutputType(outputType, requiredStatus):
       - 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.
+        - Raise a field 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
@@ -627,11 +646,9 @@ ModifiedOutputType(outputType, requiredStatus):
         - Continue onto the next node.
       - Set {resultingType} to {listType}
 - If {stack} is not empty:
-  - Throw an error because {requiredStatus} had fewer list dimensions than
+  - Raise a field error because {requiredStatus} had fewer list dimensions than
     {outputType} and is invalid.
 - Return {resultingType}.
-- Otherwise:
-  - Return {outputType}.
 
 ### Coercing Field Arguments
 
@@ -835,8 +852,9 @@ 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 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.
+type of the field after {ApplyRequiredStatus} has been applied to it 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
@@ -845,8 +863,11 @@ 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 its {ModifiedOutputType} is a `Non-Null` type, the field
-error is further propagated to its parent field.
+to {null}, otherwise if it is a `Non-Null` type, the field error is further
+propagated to its parent field.
+
+If a required field resolves to {null}, propagation instead happens until an
+optional field is found.
 
 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` 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
+If the field which experienced an error was declared as `Non-Null`, the `null`
+result will propagate to the next nullable field. If it was marked with a
+required designator, then it will propagate to the nearest optional parent field
+instead. In either 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