Skip to content

Commit

Permalink
Be more explicit about the data that makes up a GraphQL request
Browse files Browse the repository at this point in the history
  • Loading branch information
benjie committed Mar 27, 2024
1 parent 86561e8 commit e606fc9
Showing 1 changed file with 23 additions and 17 deletions.
40 changes: 23 additions & 17 deletions spec/Section 6 -- Execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,23 +4,29 @@ A GraphQL service generates a response from a request via execution.

:: A _request_ for execution consists of a few pieces of information:

- The schema to use, typically solely provided by the GraphQL service.
- A {Document} which must contain GraphQL {OperationDefinition} and may contain
{FragmentDefinition}.
- Optionally: The name of the Operation in the Document to execute.
- Optionally: Values for any Variables defined by the Operation.
- An initial value corresponding to the root type being executed. Conceptually,
an initial value represents the "universe" of data available via a GraphQL
Service. It is common for a GraphQL Service to always use the same initial
value for every request.

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

Given this information, the result of {ExecuteRequest()} produces the response,
to be formatted according to the Response section below.
- {schema} - The schema to use, typically solely provided by the GraphQL
service.
- {document} - A {Document} which must contain GraphQL {OperationDefinition} and
may contain {FragmentDefinition}.
- {operationName} (optional) - The name of the Operation in the Document to
execute.
- {variableValues} (optional) - Values for any Variables defined by the
Operation.
- {initialValue} (optional) - An initial value corresponding to the root type
being executed. Conceptually, an initial value represents the "universe" of
data available via a GraphQL Service. It is common for a GraphQL Service to
always use the same initial value for every request.
- {extensions} (optional) - A map reserved for implementers to extend the
protocol however they see fit.

Note: Since {extensions} is reserved for implementers, the only requirement is
that, if present, it is a map. There are no additional restrictions on its
contents. It is recommended that implementers use prefixes in {extensions} keys
to avoid conflicts with other implementers.

Given this information, the result of {ExecuteRequest(schema, document,
operationName, variableValues, initialValue)} produces the response, to be
formatted according to the Response section below.

Note: GraphQL requests do not require any specific serialization format or
transport mechanism. Message serialization and transport mechanisms should be
Expand Down

0 comments on commit e606fc9

Please sign in to comment.