Documentation

Validation error.

Validates a document and returns a list of found errors. If the returned list is empty, the document is valid.

GraphQL servers define what directives they support and where they support them. For each usage of a directive, the directive must be used in a location that the server has declared support for.

Definition must be OperationDefinition or FragmentDefinition.

The target field of a field selection must be defined on the scoped type of the selection set. There are no limitations on alias names.

Fragments can only be declared on unions, interfaces, and objects. They are invalid on scalars. They can only be applied on non‐leaf fields. This rule applies to both inline and named fragments.

Named fragment spreads must refer to fragments defined within the document. It is a validation error if the target of a spread is not defined.

Fragments must be specified on types that exist in the schema. This applies for both named and inline fragments. If they are not defined in the schema, the query does not validate.

GraphQL allows a short‐hand form for defining query operations when only that one operation exists in the document.

Every argument provided to a field or directive must be defined in the set of possible arguments of that field or directive.

GraphQL servers define what directives they support. For each usage of a directive, the directive must be available on that server.

Every input field provided in an input object value must be defined in the set of possible fields of that input object’s expected type.

The graph of fragment spreads must not form any cycles including spreading itself. Otherwise an operation could infinitely spread or infinitely execute on cycles in the underlying data.

Variables are scoped on a per‐operation basis. That means that any variable used within the context of an operation must be defined at the top level of that operation.

Defined fragments must be used within a document.

All variables defined by an operation must be used in that operation or a fragment transitively included by that operation. Unused variables cause a validation error.

If multiple field selections with the same response names are encountered during execution, the field and arguments to execute and the resulting value should be unambiguous. Therefore any two field selections which might both be encountered for the same object are only valid if they are equivalent.

For simple hand‐written GraphQL, this rule is obviously a clear developer error, however nested fragments can make this difficult to detect manually.

Fragments are declared on a type and will only apply when the runtime object type matches the type condition. They also are spread within the context of a parent type. A fragment spread is only valid if its type condition could ever apply within the parent type.

Input object fields may be required. Much like a field may have required arguments, an input object may have required fields. An input field is required if it has a non‐null type and does not have a default value. Otherwise, the input object field is optional.

Arguments can be required. An argument is required if the argument type is non‐null and does not have a default value. Otherwise, the argument is optional.

Field selections on scalars or enums are never allowed, because they are the leaf nodes of any GraphQL query.

Subscription operations must have exactly one root field.

Default rules given in the specification.

Fields and directives treat arguments as a mapping of argument name to value. More than one argument with the same name in an argument set is ambiguous and invalid.

Directives are used to describe some metadata or behavioral change on the definition they apply to. When more than one directive of the same name is used, the expected metadata or behavior becomes ambiguous, therefore only one of each directive is allowed per location.

Fragment definitions are referenced in fragment spreads by name. To avoid ambiguity, each fragment’s name must be unique within a document.

Inline fragments are not considered fragment definitions, and are unaffected by this validation rule.

Input objects must not contain more than one field of the same name, otherwise an ambiguity would exist which includes an ignored portion of syntax.

Each named operation definition must be unique within a document when referred to by its name.

If any operation defines more than one variable with the same name, it is ambiguous and invalid. It is invalid even if the type of the duplicate variable is the same.

Literal values must be compatible with the type expected in the position they are found as per the coercion rules.

The type expected in a position include the type defined by the argument a value is provided for, the type defined by an input object field a value is provided for, and the type of a variable definition a default value is provided for.

Variable usages must be compatible with the arguments they are passed to.

Validation failures occur when variables are used in the context of types that are complete mismatches, or if a nullable type in a variable is passed to a non‐null argument type.

Variables can only be input types. Objects, unions and interfaces cannot be used as inputs.