Skip to content

Fix "response position" definition; clarify sibling errors on propagation #1183

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions spec/Section 3 -- Type System.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
42 changes: 21 additions & 21 deletions spec/Section 6 -- Execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -599,14 +599,14 @@ section.
<!-- Legacy link, this section was previously titled "Errors and Non-Null Fields" -->
</a>

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.
Expand Down Expand Up @@ -902,40 +902,40 @@ ResolveAbstractType(abstractType, objectValue):
</a>

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_.

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}.
39 changes: 22 additions & 17 deletions spec/Section 7 -- Response.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 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. 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
Expand All @@ -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
{
Expand All @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down