Define 'execution' as in 'before execution begins'

[benjie]

UPDATE: 2025-04-03

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, and indicated that ExecuteRequest() contains the preamble for "execution", followed by "execution" itself.

See also: #1154 which renames these algorithms for further clarity.

Previous description

This is cleared up in the "Errors" -> "Request errors" section just 20 lines later, but for people dipping in to see what should happen with "data" it may not be obvious that the concept of "before execution begins" and that of entering the "Executing Requests" and/or "Executing Operations" sections differs due to the subtlety of when "request errors" can be raised.

[netlify]

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	d60481a
🔍 Latest deploy log	https://app.netlify.com/sites/graphql-spec-draft/deploys/67ee61f29fbe64000835c5ff
😎 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.