Define 'execution' as in 'before execution begins'

[benjie]

UPDATE: 2025-05-01

There are various parts of the spec that relate to a concept of "execution":

• "before execution begins" defines the boundary between request error/field error
• "the request must fail without execution" indicates that no data should be produced
• "validation is performed in the context of a request immediately before execution"

All of these things actually happen during ExecuteRequest(), which makes it confusing to the reader that ExecuteRequest() is not itself considered execution despite the name.

I've thus defined execution, elided Execute from a number of algorithms, and described that Request() (formerly ExecuteRequest()) contains the preamble for "execution", followed by "execution" itself.

This PR is dependent on:

• Replace ExecuteSelectionSet with ExecuteCollectedFields #1039

This PR merges in the changes from:

• Distinguish between executing (a selection set) vs processing (a response) #1154

[netlify]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	ec28769
🔍 Latest deploy log	https://app.netlify.com/sites/graphql-spec-draft/deploys/68135f0ca8cd6300074cefe0
😎 Deploy Preview	https://deploy-preview-894--graphql-spec-draft.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[yaacovCR]

I guess the question is why (or why not) some errors should be considered Request errors, for example, submitting a mutation operation when no mutation root type exists.

it is the fault of the graphql user, so should be considered a request error by the rough explanation given, but it does not occur during the executing requests section.

[yaacovCR]

But if you don’t validate, you can get user errors during field execution so ???

[benjie]

For that specific case that should be something raised during validation; the assert in the request execution phase is just to ensure that the assumption made by validation is still correct (useful if validation happened a long time previous, maybe the schema has changed since then).

[IvanGoncharov]

@benjie @yaacovCR I think we need to clean criteria for what consider executions and what not.
Otherwise, we just adding additional notes that clarify it but not fully.
I suggest simple criteria:
If error contains a non-empty path it's execution error and data is always present (maybe null).

[yaacovCR]

@IvanGoncharov that definition while clean is a bit circular, whether or not a path should be empty depends on whether we have started execution…

[IvanGoncharov]

My second attempt, to produce "non-confusing criteria" 😄
What if we just say that data should be null only due to "error propagation to the root":
https://spec.graphql.org/draft/#sec-Handling-Field-Errors
De facto it's the only algorithm in a spec that explicitly requires setting data to null.
It is very easy to check programmatically, and I actually think it matches the original intention.

[benjie]

I think that's a fair assessment: data should only be null in the event of a field error (including a non-null assertion) being triggered on a root field. In all other cases it should be either an object (map), or not be present. (This comment not intended to be taken as a strictly worded specification.)

[martinbonnin]

This is very hard for my brain to process. I may already be in ExecuteRequest() but still before execution begins?This feels weird.

Do we have a formal definition of what "execution" is and when it starts that we could link to maybe?

[benjie]

That's what the purpose of this PR is 💯

Execution begins the moment that the data property should be added to the response, which is when the root selection set is executed (after validating variables, establishing a stream in the case of subscriptions, etc).

[benjie]

I've taken a different tact by defining execution, see what you think.

[martinbonnin]

 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 is a preamble for _execution_.

This is clarifying but also also adding more language to processs. I think a rename of ExecuteRequest() would be even more clarifying.

[benjie]

Why not both? We use the term "execution" thoughout the spec, it makes sense to have a definition for it IMO.

[martinbonnin]

Agreed.

[benjie]

I have merged in

• Replace ExecuteSelectionSet with ExecuteCollectedFields #1039, and
• Distinguish between executing (a selection set) vs processing (a response) #1154 (thanks @martinbonnin!)

and then applied further editorial on top based on the discussions at last months WG, restoring "execution" where appropriate, eliding "Execute" (or "Process" or "Perform") from algorithm names, and making it clear that you:

• process a request,
• perform an operation, and
• execute a selection set.

I've further clarified that you validate the document not the request, and you can execute another request without validation if the document is exactly the same - the request doesn't have to be exactly the same! (Longstanding issue.)

This PR is now presented as being a PR to #1039 to keep the diff small.