Skip to content

Define 'execution' as in 'before execution begins' #894

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 5 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
2 changes: 1 addition & 1 deletion spec/Section 3 -- Type System.md
Original file line number Diff line number Diff line change
Expand Up @@ -487,7 +487,7 @@ information on the serialization of scalars in common JSON and other formats.
If a GraphQL service expects a scalar type as input to an argument, coercion is
observable and the rules must be well defined. If an input value does not match
a coercion rule, a _request error_ must be raised (input values are validated
before execution begins).
before _execution_ begins).

GraphQL has different constant literals to represent integer and floating-point
input values, and coercion rules may apply differently depending on which type
Expand Down
2 changes: 1 addition & 1 deletion spec/Section 4 -- Introspection.md
Original file line number Diff line number Diff line change
Expand Up @@ -72,7 +72,7 @@ GraphQL supports type name introspection within any _selection set_ in an
operation, with the single exception of selections at the root of a subscription
operation. Type name introspection is accomplished via the meta-field
`__typename: String!` on any Object, Interface, or Union. It returns the name of
the concrete Object type at that point during execution.
the concrete Object type at that point during _execution_.

This is most often used when querying against Interface or Union types to
identify which actual Object type of the possible types has been returned.
Expand Down
15 changes: 12 additions & 3 deletions spec/Section 6 -- Execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,15 @@ document is expected to only contain a single operation. The result of the
request is determined by the result of executing this operation according to the
"Executing Operations” section below.

:: We define _execution_ as the process of executing the operation's root
selection set through {ExecuteSelectionSet()}, thus _execution_ begins when
{ExecuteSelectionSet()} is called for the first time in a request. The
{ExecuteRequest()} algorithm contains the preamble for _execution_, followed by
the _execution_ itself.

Note: An error raised before _execution_ begins will typically be a _request
error_, and once _execution_ begins will typically be a _field error_.

ExecuteRequest(schema, document, operationName, variableValues, initialValue):

- Let {operation} be the result of {GetOperation(document, operationName)}.
Expand Down Expand Up @@ -62,10 +71,10 @@ GetOperation(document, operationName):
As explained in the Validation section, only requests which pass all validation
rules should be executed. If validation errors are known, they should be
reported in the list of "errors" in the response and the request must fail
without execution.
without _execution_.

Typically validation is performed in the context of a request immediately before
execution, however a GraphQL service may execute a request without immediately
_execution_, however a GraphQL service may execute a request without immediately
validating it if that exact same request is known to have been validated before.
A GraphQL service should only execute requests which _at some point_ were known
to be free of any validation errors, and have since not changed.
Expand All @@ -79,7 +88,7 @@ result to avoid validating the same request again in the future.
If the operation has defined any variables, then the values for those variables
need to be coerced using the input coercion rules of variable's declared type.
If a _request error_ is encountered during input coercion of variable values,
then the operation fails without execution.
then the operation fails without _execution_.

CoerceVariableValues(schema, operation, variableValues):

Expand Down
32 changes: 18 additions & 14 deletions spec/Section 7 -- Response.md
Original file line number Diff line number Diff line change
Expand Up @@ -22,10 +22,10 @@ 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.
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
Expand All @@ -47,16 +47,20 @@ 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
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
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`.
If an error was raised during the _execution_ that prevented a valid response,
the `data` entry in the response should be `null`.

Note: Request errors (including those raised during {ExecuteRequest()}) occur
before _execution_ begins; when a request error is raised the `data` entry
should not be present in the result.

### Errors

Expand All @@ -74,12 +78,12 @@ 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.
error_ was raised during _execution_.

**Request Errors**

:: A _request error_ is an error raised during a _request_ which results in no
response data. Typically raised before execution begins, a request error may
response data. Typically raised before _execution_ begins, a request error may
occur due to a parse grammar or validation error in the _Document_, an inability
to determine which operation to execute, or invalid input values for variables.

Expand All @@ -97,10 +101,10 @@ during value resolution or failure to coerce the resulting value.

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

**Error Result Format**

Expand Down Expand Up @@ -251,7 +255,7 @@ discouraged.
### Path

:: A _path entry_ is an entry within an _error result_ that allows for
association with a particular field reached during GraphQL execution.
association with a particular field reached during GraphQL _execution_.

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
Expand Down