Skip to content

Tweak the "Request" section #377

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

Open
martinbonnin wants to merge 2 commits into
base: main
Choose a base branch
from
+17 −17
Open

Tweak the "Request" section #377

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a91df74
Tweak the "Request" section
martinbonnin Apr 2, 2026
cf9fc9a
format
martinbonnin Apr 2, 2026
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
34 changes: 17 additions & 17 deletions spec/GraphQLOverHTTP.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,13 @@ parameters in one of the manners described in this specification:
extend the protocol however they see fit, as specified in
[the Response section of the GraphQL specification](https://spec.graphql.org/draft/#sec-Response-Format.Response).

Servers receiving a request with additional parameters MUST ignore parameters
they do not understand.

If implementers need to add additional information to a request they MUST do so
via other means; the RECOMMENDED approach is to add an implementer-scoped entry
to the {extensions} object.

Note: When comparing _GraphQL-over-HTTP request_ against the term
["request"](https://spec.graphql.org/draft/#request) in the GraphQL
specification you should note the _GraphQL schema_ and "initial value" are not
Expand All @@ -237,9 +244,6 @@ Note: An HTTP request that encodes parameters of the same names but of the wrong
type, or that omits required parameters, is not a well-formed _GraphQL-over-HTTP
request_.

Note: Specifying `null` for optional request parameters is equivalent to not
specifying them at all.

Note: So long as it is a string, {query} does not have to parse or validate to
be part of a well-formed _GraphQL-over-HTTP request_.

Expand Down Expand Up @@ -283,21 +287,22 @@ The {query} parameter MUST be the string representation of the source text of
the document as specified in
[the Language section of the GraphQL specification](https://spec.graphql.org/draft/#sec-Language).

The {operationName} parameter, if present, must be a string.
The {operationName} parameter, if present and not the empty string, MUST be a
string.

Each of the {variables} and {extensions} parameters, if used, MUST be encoded as
a JSON string.
Each of the {variables} and {extensions} parameters, if present and not the
empty string, MUST be encoded as a JSON string.

The {operationName} parameter, if supplied and not the empty string, represents
The {operationName} parameter, if present and not the empty string, represents
the name of the operation to be executed within the {query} as a string.

For robustness, specifying the empty string for optional parameters is
equivalent to not specifying them at all.

Note: In the final URL all of these parameters will appear in the query
component of the request URL as URL-encoded values due to the WHATWG
URLSearchParams encoding specified above.

Setting the value of the {operationName} parameter to the empty string is
equivalent to omitting the {operationName} parameter.

Note: By the above, `operationName=null` represents an operation with the name
`"null"` (such as `query null { __typename }`). If a literal `null` is desired,
either omit {operationName} or set it to the empty string.
Expand Down Expand Up @@ -376,13 +381,8 @@ When encoded in JSON, a _GraphQL-over-HTTP request_ is encoded as a JSON object
the protocol however they see fit, as specified in
[the Response section of the GraphQL specification](https://spec.graphql.org/draft/#sec-Response-Format.Response).

All other property names are reserved for future expansion. If implementers need
to add additional information to a request they MUST do so via other means; the
RECOMMENDED approach is to add an implementer-scoped entry to the {extensions}
object.

Servers receiving a request with additional properties MUST ignore properties
they do not understand.
For robustness, specifying {null} for optional request parameters is equivalent
to not specifying them at all.

### Example

Expand Down
Loading