From a91df7490b75450380b8be1643f03fb93eda78dc Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Thu, 2 Apr 2026 13:00:15 +0200 Subject: [PATCH 1/2] Tweak the "Request" section --- spec/GraphQLOverHTTP.md | 32 ++++++++++++++++---------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index c8b14751..4817d66f 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -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 @@ -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_. @@ -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 +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. @@ -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 From cf9fc9a77f9f74c36e0cdfc30dc036fbb9506238 Mon Sep 17 00:00:00 2001 From: Martin Bonnin Date: Thu, 2 Apr 2026 14:38:41 +0200 Subject: [PATCH 2/2] format --- spec/GraphQLOverHTTP.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/spec/GraphQLOverHTTP.md b/spec/GraphQLOverHTTP.md index 4817d66f..36d37f6a 100644 --- a/spec/GraphQLOverHTTP.md +++ b/spec/GraphQLOverHTTP.md @@ -290,8 +290,8 @@ the document as specified in The {operationName} parameter, if present and not the empty string, MUST be a string. -Each of the {variables} and {extensions} parameters, if present and not the empty string, 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 present and not the empty string, represents the name of the operation to be executed within the {query} as a string. @@ -381,8 +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). -For robustness, specifying {null} for optional request parameters is equivalent to -not specifying them at all. +For robustness, specifying {null} for optional request parameters is equivalent +to not specifying them at all. ### Example