Skip to content

Editorial: Define _response payload_ #1149

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.

Sign up for GitHub

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

Closed
wants to merge 2 commits into from
Closed

Editorial: Define _response payload_ #1149

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9aa2f0a
Editorial: Define _response payload_
robrichard Mar 13, 2025
d9bbd4e
PR feedback
robrichard Apr 3, 2025
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
22 changes: 11 additions & 11 deletions spec/Section 6 -- Execution.md
View file
Open in desktop
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 {responsePayload} 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 {responsePayload} on {responseStream}.
- When {sourceStream} completes normally:
- Complete {responseStream} normally.
- When {sourceStream} completes with {error}:
Expand Down Expand Up @@ -804,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
payload_ 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 payload_.

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

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 payload_, 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 @@ -832,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
{null}.
return `Non-Null` types, then the {"data"} entry in the _response payload_
should be {null}.
94 changes: 49 additions & 45 deletions spec/Section 7 -- Response.md
View file
Open in desktop
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_ is the returned result of a GraphQL _request_. A
_response_ is either a _response payload_ or a _response stream_.

### Response
### Response Payload

:: 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 payload_ when the GraphQL operation is
a query or mutation. When the GraphQL operation is a subscription, the GraphQL
Comment on lines +18 to +19
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sentence is no longer accurate. A GraphQL query with incremental delivery no longer returns a response payload.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, this section will be updated in the Incremental Delivery spec draft: #1124. I'll update it once we have settled on the terms here.

request returns a _response payload_ if a _request error_ is raised. A response
payload 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
the request completed without raising any errors, this entry must not be
If the request raised any errors, the _response payload_ 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
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.
If the request included execution, the _response payload_ 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
extend the protocol however they see fit, and hence there are no additional
restrictions on its contents.
The _response payload_ 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 payload_ 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 payload_, it may be helpful for
it to appear first when serialized to make it more apparent that errors are
present.

### 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 payload_.

### 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 payload_ 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 payload_.

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 payload_ should be `null`.
Comment on lines +62 to +63
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Note to other reviewers: this line contains a subtle fix to the wording. 👍


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

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 payload_ 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 payload_ 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,9 +89,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 payload_ must
not be present, the `errors` entry must include the error, and request execution
should be halted.

**Field Errors**

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 payload_ must be present. The `errors` entry
should include this error.

**Error Result Format**

Expand Down