lift response position to top section

Author: leebyron

spec/Section 6 -- Execution.md

@@ -814,8 +814,9 @@ MergeSelectionSets(fields):
 </a>
 
 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.
+or coercion, at a specific _response position_. While these errors must be
+reported in the response, they are "handled" by producing partial {"data"} in
+the _response_.
 
 Note: This is distinct from a _request error_ which results in a response with
 no data.

spec/Section 7 -- Response.md

@@ -17,12 +17,12 @@ A GraphQL request returns either a _response_ or a _response stream_.
 or mutation. A _response_ must be a map.
 
 If the request raised any errors, the response map must contain an entry with
-key `errors`. The value of this entry is described in the "Errors" section. If
+key {"errors"}. The value of this entry is described in the "Errors" section. If
 the request completed without raising any errors, this entry must not be
 present.
 
 If the request included execution, the response map must contain an entry with
-key `data`. The value of this entry is described in the "Data" section. If the
+key {"data"}. The value of this entry is described in the "Data" section. If the
 request failed before execution, due to a syntax error, missing information, or
 validation error, this entry must not be present.
 
@@ -35,7 +35,7 @@ To ensure future changes to the protocol do not break existing services and
 clients, the top level response map must not contain any entries other than the
 three described above.
 
-Note: When `errors` is present in the response, it may be helpful for it to
+Note: When {"errors"} is present in the response, it may be helpful for it to
 appear first when serialized to make it more clear when errors are present in a
 response during debugging.
 
@@ -44,30 +44,29 @@ response during debugging.
 :: A GraphQL request returns a _response stream_ when the GraphQL operation is a
 subscription. A _response stream_ must be a stream of _response_.
 
-### Data
-
-The `data` entry in the response will be the result of the execution of the
-requested operation. If the operation was a query, this output will be an object
-of the query root operation type; if the operation was a mutation, this output
-will be an object of the mutation root operation type.
-
-If an error was raised before execution begins, the `data` entry should not be
-present in the response.
+### Response Position
 
-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 name="sec-Path">
+  <!-- Legacy link, this section was previously titled "Path" -->
+</a>
 
 :: 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.
+value. Each response position is uniquely identifiable via a _response path_.
+
+:: A _response path_ uniquely identifies a _response position_ via a list of
+path segments (response keys or list indicies) starting at the root of the
+response and ending with the associated response position.
 
-The response data is the result of accumulating the result of all response
-positions during execution.
+The value for a _response path_ must be a list of path segments. Path segments
+that represent field response keys must be strings, and path segments that
+represent list indices must be 0-indexed integers. If a path segment is
+associated with an aliased field it must use the aliased name, since it
+represents a path in the response, not in the request.
 
-Each _response position_ is uniquely identifiable via a _path entry_.
+When a _response path_ is present on an _error result_, it identifies the
+_response position_ which raised the error.
 
 A single field execution may result in multiple response positions. For example,
 
@@ -82,27 +81,44 @@ A single field execution may result in multiple response positions. For example,
 }
 ```
 
-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"]`.
+The hero's name would be found in the _response position_ identified by the
+_response path_ `["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"]`.
+
+### Data
+
+The {"data"} entry in the response will be the result of the execution of the
+requested operation. If the operation was a query, this output will be an object
+of the query root operation type; if the operation was a mutation, this output
+will be an object of the mutation root operation type.
+
+The response data is the result of accumulating the resolved result of all
+response positions during execution.
+
+If an error was raised before execution begins, the {"data"} entry should not be
+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`.
 
 ### Errors
 
-The `errors` entry in the response is a non-empty list of errors raised during
+The {"errors"} entry in the response is a non-empty list of errors raised during
 the _request_, where each error is a map of data described by the error result
 format below.
 
-If present, the `errors` entry in the response must contain at least one error.
-If no errors were raised during the request, the `errors` entry must not be
-present in the response.
+If present, the {"errors"} entry in the response must contain at least one
+error. If no errors were raised during the request, the {"errors"} entry must
+not be present in the response.
 
-If the `data` entry in the response is not present, the `errors` entry must be
-present. It must contain at least one _request error_ indicating why no data was
-able to be returned.
+If the {"data"} entry in the response is not present, the {"errors"} entry must
+be present. It must contain at least one _request error_ indicating why no data
+was able to be returned.
 
-If the `data` entry in the response is present (including if it is the value
-{null}), the `errors` entry must be present if and only if one or more
+If the {"data"} entry in the response is present (including if it is the value
+{null}), the {"errors"} entry must be present if and only if one or more
 _execution error_ was raised during execution.
 
 **Request Errors**
@@ -114,9 +130,9 @@ to determine which operation to execute, or invalid input values for variables.
 
 A request error is typically the fault of the requesting client.
 
-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.
+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**
 
@@ -136,31 +152,32 @@ An execution error is typically the fault of a GraphQL service.
 
 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_.
+indicated via a _response path_ in the error response's {"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
+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**
 
-Every error must contain an entry with the key `message` with a string
+Every error must contain an entry with the key {"message"} with a string
 description of the error intended for the developer as a guide to understand and
 correct the error.
 
 If an error can be associated to a particular point in the requested GraphQL
-document, it should contain an entry with the key `locations` with a list of
-locations, where each location is a map with the keys `line` and `column`, both
-positive numbers starting from `1` which describe the beginning of an associated
-syntax element.
+document, it should contain an entry with the key {"locations"} with a list of
+locations, where each location is a map with the keys {"line"} and {"column"},
+both positive numbers starting from `1` which describe the beginning of an
+associated syntax element.
 
 If an error can be associated to a particular field in the GraphQL result, it
-must contain an entry with the key `path` that details the path of the response
-field which experienced the error. This allows clients to identify whether a
-`null` result is intentional or caused by a runtime error. The value of this
-_path entry_ is described in the [Path](#sec-Path) section.
+must contain an entry with the key {"path"} with a _response path_ which
+describes the _response position_ which raised the error. This allows clients to
+identify whether a {null} resolved result is a true value or the result of an
+_execution error_.
 
 For example, if fetching one of the friends' names fails in the following
 operation:
@@ -290,21 +307,6 @@ discouraged.
 }
 ```
 
-### Path
-
-:: A _path entry_ is an entry within an _error result_ that indicates the
-_response position_ at which the error occurred.
-
-The value for a _path entry_ must be a list of path segments starting at the
-root of the response and ending with the field to be associated with. Path
-segments that represent fields must be strings, and path segments that represent
-list indices must be 0-indexed integers. If a path segment is associated with an
-aliased field it must use the aliased name, since it represents a path in the
-response, not in the request.
-
-When the _path entry_ is present on an _error result_, it identifies the
-response field which experienced the error.
-
 ## Serialization Format
 
 GraphQL does not require a specific serialization format. However, clients