Skip to content

Commit 1feb562

Browse files
committed
[RFC] Clarify rules for validation + execution
There is some ambiguity of what it means to execute a query relative to if it has passed validation. Is it safe to ignore validation errors and execute anyhow? (no) Is it safe to skip validation altogether? (no) What about requests that at some point in the past were validated, do you need to validate them again every time you execute them? (only one validation required per request) This adds more language around validation and its relationship to execution to help clarify these ambiguities and talks more about what happens when time passes between validation and execution. There is some repetition here, just to reinforce these ideas between sections.
1 parent bb45a6f commit 1feb562

File tree

2 files changed

+49
-14
lines changed

2 files changed

+49
-14
lines changed

spec/Section 5 -- Validation.md

Lines changed: 31 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,36 @@
11
# Validation
22

3-
GraphQL does not just verify if a request is syntactically correct.
4-
5-
Prior to execution, it can also verify that a request is valid
6-
within the context of a given GraphQL schema. Validation is primarily
7-
targeted at development-time tooling. Any client-side tooling
8-
should return errors and not allow the formulation of queries
9-
known to violate the type system at a given point in time.
10-
11-
Total request validation on the server-side during execution is optional. As
12-
schemas and systems change over time existing clients may end up emitting
13-
queries that are no longer valid given the current type system. Servers
14-
(as described in the Execution section of this spec) attempt to satisfy as
15-
much of the request as possible and continue to execute in the presence
16-
of type system errors rather than cease execution completely.
3+
GraphQL does not just verify if a request is syntactically correct, but also
4+
ensures that it is unambiguous and mistake-free in the context of a given
5+
GraphQL schema.
6+
7+
An invalid request is still technically executable, and will always produce a
8+
stable result as defined by the procedures in the Execution section, however
9+
that result may be ambiguous, surprising, or unexpected relative to the request
10+
containing validation errors, so execution should not occur for invalid requests.
11+
12+
Typically validation is performed in the context of a request immediately
13+
before execution, however a GraphQL service may execute a request without
14+
explicitly validating it if that exact same request is known to have been
15+
validated before. For example: the request may be validated during development,
16+
provided it does not later change, or a service may validate a request once and
17+
memoize the result to avoid validating the same request again in the future.
18+
Any client-side or development-time tool should report validation errors and not
19+
allow the formulation or execution of requests known to be invalid at that given
20+
point in time.
21+
22+
**Type system evolution**
23+
24+
As GraphQL type system schema evolve over time by adding new types and new
25+
fields, it is possible that a request which was previously valid could later
26+
become invalid. Any change that can cause a previously valid request to become
27+
invalid is considered a *breaking change*. GraphQL services and schema
28+
maintainers are encouraged to avoid breaking changes, however in order to be
29+
more resilient to these breaking changes, sophisticated GraphQL systems may
30+
still allow for the execution of requests which *at some point* were known to
31+
be free of any validation errors, and have not changed since.
32+
33+
**Examples**
1734

1835
For this section of this schema, we will assume the following type system
1936
in order to demonstrate examples:

spec/Section 6 -- Execution.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,6 +16,24 @@ should be the result of evaluating the operation according to the “Evaluating
1616
operations” section.
1717

1818

19+
## Validation of operation
20+
21+
As explained in the Validation section, only requests which pass all validation
22+
rules should be executed. If validation errors are known, they should be
23+
reported in the list of "errors" in the response and the operation must fail
24+
without execution.
25+
26+
Typically validation is performed in the context of a request immediately
27+
before execution, however a GraphQL service may execute a request without
28+
explicitly validating it if that exact same request is known to have been
29+
validated before. For example: the request may be validated during development,
30+
provided it does not later change, or a service may validate a request once and
31+
memoize the result to avoid validating the same request again in the future.
32+
33+
A GraphQL service should only execute requests which *at some point* were
34+
known to be free of any validation errors, and have not changed since.
35+
36+
1937
## Coercing Variable Values
2038

2139
If the operation has defined any variables, then the values for

0 commit comments

Comments
 (0)