diff --git a/spec/Section 3 -- Type System.md b/spec/Section 3 -- Type System.md index 8400233fa..b983f2f9b 100644 --- a/spec/Section 3 -- Type System.md +++ b/spec/Section 3 -- Type System.md @@ -1876,9 +1876,9 @@ performed. If that result was not {null}, then the result of coercing the Non-Null type is that result. If that result was {null}, then an _execution error_ must be raised. -Note: When an _execution error_ is raised on a non-null _response position_, the -error propagates to the parent _response position_. For more information on this -process, see +Note: When an _execution error_ is raised on a non-null _execution position_, +the error propagates to the parent _execution position_. For more information on +this process, see [Errors and Non-Null Types](#sec-Executing-Selection-Sets.Errors-and-Non-Null-Types) within the Execution section. diff --git a/spec/Section 6 -- Execution.md b/spec/Section 6 -- Execution.md index d0de0ed2d..dda67dae8 100644 --- a/spec/Section 6 -- Execution.md +++ b/spec/Section 6 -- Execution.md @@ -599,14 +599,14 @@ section. -If during {ExecuteCollectedFields()} 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 +If during {ExecuteCollectedFields()} an _execution position_ with a non-null +type raises an _execution error_ then that error must propagate to the parent +execution position (the entire selection set in the case of a field, or the entire list in the case of a list position), either resolving to {null} if -allowed or being further propagated to a parent response position. +allowed or being further propagated to a parent execution position. -If this occurs, any sibling response positions which have not yet executed or -have not yet yielded a value may be cancelled to avoid unnecessary work. +If this occurs, any sibling _execution position_ which has not yet executed or +has not yet yielded a value may be cancelled to avoid unnecessary work. Note: See [Handling Execution Errors](#sec-Handling-Execution-Errors) for more about this behavior. @@ -902,7 +902,7 @@ ResolveAbstractType(abstractType, objectValue): An _execution error_ is an error raised during field execution, value resolution -or coercion, at a specific _response position_. While these errors must be +or coercion, at a specific _execution position_. While these errors must be reported in the response, they are "handled" by producing partial {"data"} in the _response_. @@ -910,32 +910,32 @@ Note: This is distinct from a _request error_ which results in a _request error result_ 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 _response position_ at +nested inside any lists), it is handled as though the _execution position_ at which the error occurred resolved to {null}, and the error must be added to the {"errors"} list in the _execution result_. -If the result of resolving a _response position_ is {null} (either due to the +If the result of resolving an _execution 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 _execution result_. -If a _response position_ resolves to {null} because of an execution error which -has already been added to the {"errors"} list in the _execution result_, the -{"errors"} list must not be further affected. That is, only one error should be -added to the errors list per _response position_. +If an _execution position_ resolves to {null} because of an execution error +which has already been added to the {"errors"} list in the _execution result_, +the {"errors"} list must not be further affected. That is, each error added to +the errors list during execution must have a unique _response path_. -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_. +Since `Non-Null` execution positions cannot be {null}, execution errors are +propagated to be handled by the parent _execution position_. If the parent +execution 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 +_execution position_. -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 +If a `List` type wraps a `Non-Null` type, and one of the _execution position_ +elements of that list resolves to {null}, then the entire list _execution 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 +If every _execution position_ from the root of the request to the source of the execution error has a `Non-Null` type, then the {"data"} entry in the _execution result_ should be {null}. diff --git a/spec/Section 7 -- Response.md b/spec/Section 7 -- Response.md index f79100cd2..00ad2afe6 100644 --- a/spec/Section 7 -- Response.md +++ b/spec/Section 7 -- Response.md @@ -70,20 +70,24 @@ The _request error result_ map must not contain an entry with key {"data"}. The _request error result_ map may also contain an entry with key `extensions`. The value of this entry is described in the "Extensions" section. -### Response Position +### Response Path -:: 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. Each response position is uniquely identifiable via a _response path_. +:: An _execution position_ is a uniquely identifiable position in the response +structure evaluated during execution. It may correspond to a {responseName} +evaluated by {ExecuteCollectedFields()}, or to an element within a (potentially +nested) List value evaluated by {CompleteValue()}. Each execution position is +uniquely identifiable via a _response path_. -:: A _response path_ uniquely identifies a _response position_ via a list of +Note: An _execution position_ may be omitted from the _execution result_ due to +error propagation. + +:: A _response path_ uniquely identifies an _execution position_ via a list of path segments (response names or list indices) starting at the root of the -response and ending with the associated response position. +response and ending with the associated execution position. The value for a _response path_ must be a list of path segments. Path segments that represent field _response name_ must be strings, and path segments that @@ -92,9 +96,10 @@ associated with an aliased field it must use the aliased name, since it represents a path in the response, not in the request. When a _response path_ is present on an _error result_, it identifies the -_response position_ which raised the error. +_execution position_ which raised the error. -A single field execution may result in multiple response positions. For example, +A single field execution may result in multiple execution positions. For +example, ```graphql example { @@ -107,7 +112,7 @@ 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 the +The hero's name would be found in the _execution 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 @@ -121,7 +126,7 @@ 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. +execution positions during execution. If an error was raised before execution begins, the _response_ must be a _request error result_ which will result in no response data. @@ -164,12 +169,12 @@ _field error_. 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 +An _execution error_ must occur at a specific _execution position_, and may +occur in any execution position. The execution position of an execution error is 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 +When an execution error is raised at a given _execution position_, then that +execution 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 @@ -189,8 +194,8 @@ 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"} 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 +describes the _execution 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