Skip to content
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

Editorial: Define _response map_ #1143

Open
wants to merge 2 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
25 changes: 12 additions & 13 deletions spec/Section 6 -- Execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -301,13 +301,13 @@ MapSourceToResponseEvent(sourceStream, subscription, schema, variableValues):

- Let {responseStream} be a new _event stream_.
- When {sourceStream} emits {sourceValue}:
- Let {response} be the result of running
- Let {responseMap} be the result of running
{ExecuteSubscriptionEvent(subscription, schema, variableValues,
sourceValue)}.
- If internal {error} was raised:
- Cancel {sourceStream}.
- Complete {responseStream} with {error}.
- Otherwise emit {response} on {responseStream}.
- Otherwise emit {responseMap} on {responseStream}.
- When {sourceStream} completes normally:
- Complete {responseStream} normally.
- When {sourceStream} completes with {error}:
Expand Down Expand Up @@ -355,8 +355,7 @@ type need to be known, as well as whether it must be executed serially, or may
be executed in parallel.

First, the selection set is turned into a grouped field set; then, each
represented field in the grouped field set produces an entry into a response
map.
represented field in the grouped field set produces an entry into a result map.

ExecuteSelectionSet(selectionSet, objectType, objectValue, variableValues):

Expand Down Expand Up @@ -596,7 +595,7 @@ directives may be applied in either order since they apply commutatively.
## Executing Fields

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
objectType will result in an entry in the result 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.
Expand Down Expand Up @@ -805,22 +804,22 @@ A _field 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.

Note: This is distinct from a _request error_ which results in a response with
no data.
Note: This is distinct from a _request error_ which results in a _response map_
with no {"data"}.

If a field error is raised while resolving a field, it is handled as though the
field returned {null}, and the error must be added to the {"errors"} list in the
response.
_response map_.

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 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.
added to the {"errors"} list in the _response map_.

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
further affected. That is, only one error should be added to the errors list per
field.
added to the {"errors"} list in the _response map_, the {"errors"} list must not
be further affected. That is, only one error should be added to the errors list
per 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
Expand All @@ -833,5 +832,5 @@ type is also wrapped in a `Non-Null`, the field error continues to propagate
upwards.

If all fields from the root of the request to the source of the field error
return `Non-Null` types, then the {"data"} entry in the response should be
return `Non-Null` types, then the {"data"} entry in the _response map_ should be
{null}.
76 changes: 40 additions & 36 deletions spec/Section 7 -- Response.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,71 +10,75 @@ the case that any _field error_ was raised on a field and was replaced with

## Response Format

A GraphQL request returns either a _response_ or a _response stream_.
:: A GraphQL _response_ the returned result of a GraphQL _request_. A _response_
is either a _response map_ or a _response stream_.

### Response
### Response Map

:: A GraphQL request returns a _response_ when the GraphQL operation is a query
or mutation. A _response_ must be a map.
:: A GraphQL request returns a _response map_ when the GraphQL operation is a
query or mutation. When the GraphQL operation is a subscription, the GraphQL
request returns a _response map_ if a _request error_ is raised. A response map
must be a map.

If the request raised any errors, the response map must contain an entry with
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
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
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
request failed before execution, due to a syntax error, missing information, or
validation error, this entry must not be present.

The response map may also contain an entry with key `extensions`. This entry, if
set, must have a map as its value. This entry is reserved for implementers to
The _response map_ may also contain an entry with key `extensions`. This entry,
if set, must have a map as its value. This entry is reserved for implementers to
extend the protocol however they see fit, and hence there are no additional
restrictions on its contents.

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.
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
appear first when serialized to make it more clear when errors are present in a
response during debugging.
Note: When `errors` is present in the _response map_, it may be helpful for it
to appear first when serialized to make it more clear when errors are present in
a response map during debugging.

### Response Stream

:: A GraphQL request returns a _response stream_ when the GraphQL operation is a
subscription. A _response stream_ must be a stream of _response_.
subscription and a _request error_ is not raised. A response stream must be a
stream of _response map_.

### 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 `data` entry in the _response map_ 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.
present in the _response map_.

If an error was raised during the execution that prevented a valid response, the
`data` entry in the response should be `null`.
If an error was raised during execution that propagated to the operation root,
the `data` entry in the _response map_ should be `null`.

### Errors

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.
The `errors` entry in the _response map_ 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 map_ must contain at least one
error. If no errors were raised during the request, the `errors` entry must not
be present in the response map.

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 map_ 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 _field
error_ was raised during execution.
If the `data` entry in the _response map_ is present (including if it is the
value {null}), the `errors` entry must be present if and only if one or more
_field error_ was raised during execution.

**Request Errors**

Expand All @@ -85,7 +89,7 @@ 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
If a request error is raised, the `data` entry in the _response map_ must not be
present, the `errors` entry must include the error, and request execution should
be halted.

Expand All @@ -99,8 +103,8 @@ A field error is typically the fault of a GraphQL service.

If a field error is raised, execution attempts to continue and a partial result
is produced (see [Handling Field Errors](#sec-Handling-Field-Errors)). The
`data` entry in the response must be present. The `errors` entry should include
this error.
`data` entry in the _response map_ must be present. The `errors` entry should
include this error.

**Error Result Format**

Expand Down