lift up + other feedback

Author: leebyron

spec/Section 6 -- Execution.md

@@ -376,12 +376,12 @@ ExecuteSelectionSet(selectionSet, objectType, objectValue, variableValues):
 Note: {resultMap} is ordered by which fields appear first in the operation. This
 is explained in greater detail in the Field Collection section below.
 
+**Errors and Non-Null Types**
+
 <a name="sec-Executing-Selection-Sets.Errors-and-Non-Null-Fields">
-  <!-- This link exists for legacy hyperlink support -->
+  <!-- Legacy link, this section was previously titled "Errors and Non-Null Fields" -->
 </a>
 
-**Errors and Non-Null Types**
-
 If during {ExecuteSelectionSet()} a _response position_ with a non-null type
 raises an _execution error_ then that error must propagate to the parent
 response position (the entire selection set in the case of a field, or the
@@ -626,9 +626,6 @@ the type system to have a specific input type.
 At each argument position in an operation may be a literal {Value}, or a
 {Variable} to be provided at runtime.
 
-Any _request error_ raised during {CoerceArgumentValues()} should be treated
-instead as an _execution error_.
-
 CoerceArgumentValues(objectType, field, variableValues):
 
 - Let {coercedValues} be an empty unordered Map.
@@ -672,6 +669,9 @@ CoerceArgumentValues(objectType, field, variableValues):
         {coercedValue}.
 - Return {coercedValues}.
 
+Any _request error_ raised as a result of input coercion during
+{CoerceArgumentValues()} should be treated instead as an _execution error_.
+
 Note: Variable values are not coerced because they are expected to be coerced
 before executing the operation in {CoerceVariableValues()}, and valid operations
 must only allow usage of variables of appropriate types.
@@ -807,45 +807,45 @@ MergeSelectionSets(fields):
   - Append all selections in {fieldSelectionSet} to {selectionSet}.
 - Return {selectionSet}.
 
+### Handling Execution Errors
+
 <a name="sec-Handling-Field-Errors">
-  <!-- This link exists for legacy hyperlink support -->
+  <!-- Legacy link, this section was previously titled "Handling Execution Errors" -->
 </a>
 
-### Handling Execution Errors
-
-An _execution error_ is an error raised from a particular field during value
-resolution or coercion. While these errors should be reported in the response,
-they are "handled" by producing a partial response.
+An _execution error_ is an error raised during field execution, value resolution
+or coercion, at a specific _response position_. While these errors should be
+reported in the response, they are "handled" by producing a partial response.
 
 Note: This is distinct from a _request error_ which results in a response with
 no data.
 
 If an execution error is raised while resolving a field (either directly or
-nested inside any lists), it is handled as though the position at which the
-error occurred resulted in {null}, and the error must be added to the {"errors"}
-list in the response.
+nested inside any lists), it is handled as though the _response position_ at
+which the error occurred resolved to {null}, and the error must be added to the
+{"errors"} list in the response.
 
 If the result of resolving a _response position_ is {null} (either due to the
 result of {ResolveFieldValue()} or because an execution error was raised), and
 that position is of a `Non-Null` type, then an execution error is raised at that
 position. The error must be added to the {"errors"} list in the response.
 
-If a _response position_ returns {null} because of an execution error which has
-already been added to the {"errors"} list in the response, the {"errors"} list
-must not be further affected. That is, only one error should be added to the
-errors list per _response position_.
+If a _response position_ resolves to {null} because of an execution error which
+has already been added to the {"errors"} list in the response, the {"errors"}
+list must not be further affected. That is, only one error should be added to
+the errors list per _response position_.
 
 Since `Non-Null` response positions cannot be {null}, execution errors are
 propagated to be handled by the parent _response position_. If the parent
 response position may be {null} then it resolves to {null}, otherwise if it is a
 `Non-Null` type, the execution error is further propagated to its parent
 _response position_.
 
-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`
-type is also wrapped in a `Non-Null`, the execution error continues to propagate
-upwards.
+If a `List` type wraps a `Non-Null` type, and one of the _response position_
+elements of that list resolves to {null}, then the entire list _response
+position_ must resolve to {null}. If the `List` type is also wrapped in a
+`Non-Null`, the execution error continues to propagate upwards.
 
 If every _response position_ from the root of the request to the source of the
-execution error returns a `Non-Null` type, then the {"data"} entry in the
-response should be {null}.
+execution error has a `Non-Null` type, then the {"data"} entry in the response
+should be {null}.

spec/Section 7 -- Response.md

@@ -57,6 +57,36 @@ present in the response.
 If an error was raised during the execution that prevented a valid response, the
 `data` entry in the response should be `null`.
 
+**Response Position**
+
+:: A _response position_ is a uniquely identifiable position in the response
+data produced during execution. It is either a direct entry in the {resultMap}
+of a {ExecuteSelectionSet()}, or it is a position in a (potentially nested) List
+value.
+
+The response data is the result of accumulating the result of all response
+positions during execution.
+
+Each _response position_ is uniquely identifiable via a _path entry_.
+
+A single field execution may result in multiple response positions. For example,
+
+```graphql example
+{
+  hero(episode: $episode) {
+    name
+    friends {
+      name
+    }
+  }
+}
+```
+
+The hero's name would be found in the _response position_ identified by
+`["hero", "name"]`. The List of the hero's friends would be found at
+`["hero", "friends"]`, the hero's first friend at `["hero", "friends", 0]` and
+that friend's name at `["hero", "friends", 0, "name"]`.
+
 ### Errors
 
 The `errors` entry in the response is a non-empty list of errors raised during
@@ -88,33 +118,31 @@ If a request error is raised, the `data` entry in the response must not be
 present, the `errors` entry must include the error, and request execution should
 be halted.
 
+**Execution Errors**
+
 <a name="sec-Errors.Field-Errors">
-  <!-- This link exists for legacy hyperlink support -->
+  <!-- Legacy link, this section was previously titled "Field Errors" -->
 </a>
 
-**Execution Errors**
-
 :: An _execution error_ is an error raised during the execution of a particular
 field which results in partial response data. This may occur due to failure to
 coerce the arguments for the field, an internal error during value resolution,
-or failure to coerce the resulting value. An _execution error_ may occur in any
-_response position_.
+or failure to coerce the resulting value.
 
 Note: In previous versions of this specification _execution error_ was called
 _field error_.
 
-:: A _response position_ is an identifiable position in the response: either a
-_field_, or a (potentially nested) list position within a field if the field has
-a `List` type. An _execution error_ may only occur within a _response position_.
-The _response position_ is indicated in the _response_ via the error's _path
-entry_.
-
 An execution error is typically the fault of a GraphQL service.
 
-If an execution error is raised, execution attempts to continue and a partial
-result is produced (see
-[Handling Execution Errors](#sec-Handling-Execution-Errors)). The `data` entry
-in the response must be present. The `errors` entry must include this error.
+An _execution error_ must occur at a specific _response position_, and may occur
+in any response position. The response position of an execution error is
+indicated via the error's `path` _path entry_.
+
+When an execution error is raised at a given _response position_, then that
+response position must not be present within the _response_ `data` entry (except
+{null}), and the `errors` entry must include the error. Nested execution is
+halted and sibling execution attempts to continue, producing partial result (see
+[Handling Execution Errors](#sec-Handling-Execution-Errors)).
 
 **Error Result Format**