Skip to content

Commit

Permalink
[RFC] Clarify rules for validation + execution
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
leebyron committed Mar 23, 2016
1 parent bb45a6f commit 1feb562
Show file tree
Hide file tree
Showing 2 changed files with 49 additions and 14 deletions.
45 changes: 31 additions & 14 deletions spec/Section 5 -- Validation.md
Original file line number Diff line number Diff line change
@@ -1,19 +1,36 @@
# Validation

GraphQL does not just verify if a request is syntactically correct.

Prior to execution, it can also verify that a request is valid
within the context of a given GraphQL schema. Validation is primarily
targeted at development-time tooling. Any client-side tooling
should return errors and not allow the formulation of queries
known to violate the type system at a given point in time.

Total request validation on the server-side during execution is optional. As
schemas and systems change over time existing clients may end up emitting
queries that are no longer valid given the current type system. Servers
(as described in the Execution section of this spec) attempt to satisfy as
much of the request as possible and continue to execute in the presence
of type system errors rather than cease execution completely.
GraphQL does not just verify if a request is syntactically correct, but also
ensures that it is unambiguous and mistake-free in the context of a given
GraphQL schema.

An invalid request is still technically executable, and will always produce a
stable result as defined by the procedures in the Execution section, however
that result may be ambiguous, surprising, or unexpected relative to the request
containing validation errors, so execution should not occur for invalid requests.

Typically validation is performed in the context of a request immediately
before execution, however a GraphQL service may execute a request without
explicitly validating it if that exact same request is known to have been
validated before. For example: the request may be validated during development,
provided it does not later change, or a service may validate a request once and
memoize the result to avoid validating the same request again in the future.
Any client-side or development-time tool should report validation errors and not
allow the formulation or execution of requests known to be invalid at that given
point in time.

**Type system evolution**

As GraphQL type system schema evolve over time by adding new types and new
fields, it is possible that a request which was previously valid could later
become invalid. Any change that can cause a previously valid request to become
invalid is considered a *breaking change*. GraphQL services and schema
maintainers are encouraged to avoid breaking changes, however in order to be
more resilient to these breaking changes, sophisticated GraphQL systems may
still allow for the execution of requests which *at some point* were known to
be free of any validation errors, and have not changed since.

**Examples**

For this section of this schema, we will assume the following type system
in order to demonstrate examples:
Expand Down
18 changes: 18 additions & 0 deletions spec/Section 6 -- Execution.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,24 @@ should be the result of evaluating the operation according to the “Evaluating
operations” section.


## Validation of operation

As explained in the Validation section, only requests which pass all validation
rules should be executed. If validation errors are known, they should be
reported in the list of "errors" in the response and the operation must fail
without execution.

Typically validation is performed in the context of a request immediately
before execution, however a GraphQL service may execute a request without
explicitly validating it if that exact same request is known to have been
validated before. For example: the request may be validated during development,
provided it does not later change, or a service may validate a request once and
memoize the result to avoid validating the same request again in the future.

A GraphQL service should only execute requests which *at some point* were
known to be free of any validation errors, and have not changed since.


## Coercing Variable Values

If the operation has defined any variables, then the values for
Expand Down

0 comments on commit 1feb562

Please sign in to comment.