Validation | GraphQL

Validate GraphQL documents and schemas with the specified validation rules.

These exports are also available from the root graphql package.

For documentation purposes, these exports are grouped into the following categories:

Category: Validation Context

Classes:
ValidationContext

Types:
ValidationRule

Classes

ValidationContext

Validation context passed to query validation rules.

Constructor

Creates a ValidationContext instance.

Signature:

new ValidationContext(
  schema: GraphQLSchema,
  ast: DocumentNode,
  typeInfo: TypeInfo,
  onError: (error: GraphQLError) => void,
  hideSuggestions?: Maybe<boolean>,
);

Arguments

Name	Type	Description
schema	`GraphQLSchema`	Schema used to validate the document.
ast	`DocumentNode`	Document AST being validated.
typeInfo	`TypeInfo`	TypeInfo instance used to track traversal state.
onError	`(error: GraphQLError) => void`	Callback invoked for each validation error.
hideSuggestions?	`Maybe<boolean>`	Whether suggestion text should be omitted from errors.

getSchema()

Returns the schema being used by this validation context.

Signature:

getSchema(): GraphQLSchema;

Returns

Type	Description
`GraphQLSchema`	The schema being validated against.

Example

import { parse } from 'graphql/language';
import { buildSchema, TypeInfo } from 'graphql/utilities';
import { ValidationContext } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    greeting: String
  }
`);
const context = new ValidationContext(
  schema,
  parse('{ greeting }'),
  new TypeInfo(schema),
  () => {},
);
 
context.getSchema().getQueryType()?.name; // => 'Query'

getVariableUsages()

Returns variable usages found directly within this node.

Signature:

getVariableUsages(
  node: OperationDefinitionNode | FragmentDefinitionNode,
): readonly {
  node: VariableNode;
  type: Maybe<GraphQLInputType>;
  parentType: Maybe<GraphQLInputType>;
  defaultValue: unknown;
  fragmentVariableDefinition: Maybe<VariableDefinitionNode>;
}[];

Arguments

Name	Type	Description
node	`OperationDefinitionNode \| FragmentDefinitionNode`	The AST node to inspect or visit.

Returns

Type	Description
`readonly { node: VariableNode; type: Maybe<GraphQLInputType>; parentType: Maybe<GraphQLInputType>; defaultValue: unknown; fragmentVariableDefinition: Maybe<VariableDefinitionNode>; }[]`	Variable usages found directly within this node.

Example

import { parse } from 'graphql/language';
import { buildSchema, TypeInfo } from 'graphql/utilities';
import { ValidationContext } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    greeting(name: String): String
  }
`);
const document = parse('query ($name: String) { greeting(name: $name) }');
const operation = document.definitions[0];
const context = new ValidationContext(
  schema,
  document,
  new TypeInfo(schema),
  () => {},
);
 
const usages = context.getVariableUsages(operation);
 
usages[0].node.name.value; // => 'name'
String(usages[0].type); // => 'String'

getRecursiveVariableUsages()

Returns variable usages for an operation, including variables used by referenced fragments.

Signature:

getRecursiveVariableUsages(
  operation: OperationDefinitionNode,
): readonly {
  node: VariableNode;
  type: Maybe<GraphQLInputType>;
  parentType: Maybe<GraphQLInputType>;
  defaultValue: unknown;
  fragmentVariableDefinition: Maybe<VariableDefinitionNode>;
}[];

Arguments

Name	Type	Description
operation	`OperationDefinitionNode`	Operation definition to inspect.

Returns

Type	Description
`readonly { node: VariableNode; type: Maybe<GraphQLInputType>; parentType: Maybe<GraphQLInputType>; defaultValue: unknown; fragmentVariableDefinition: Maybe<VariableDefinitionNode>; }[]`	Variable usages reachable from the operation.

Example

import { parse } from 'graphql/language';
import { buildSchema, TypeInfo } from 'graphql/utilities';
import { ValidationContext } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    viewer: User
  }
 
  type User {
    name(prefix: String): String
  }
`);
const document = parse(`
  query ($prefix: String) {
    viewer {
      ...UserName
    }
  }
 
  fragment UserName on User {
    name(prefix: $prefix)
  }
`);
const operation = document.definitions[0];
const context = new ValidationContext(
  schema,
  document,
  new TypeInfo(schema),
  () => {},
);
 
const usages = context.getRecursiveVariableUsages(operation);
 
usages.map((usage) => usage.node.name.value); // => ['prefix']

getType()

Returns the current output type at this point in traversal.

Signature:

getType(): Maybe<GraphQLOutputType>;

Returns

Type	Description
`Maybe<GraphQLOutputType>`	The current output type, if known.

Example

import { parse, visit } from 'graphql/language';
import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
import { ValidationContext } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    greeting: String
  }
`);
const document = parse('{ greeting }');
const typeInfo = new TypeInfo(schema);
const context = new ValidationContext(schema, document, typeInfo, () => {});
let typeName;
 
visit(
  document,
  visitWithTypeInfo(typeInfo, {
    Field: () => {
      typeName = String(context.getType());
    },
  }),
);
 
typeName; // => 'String'

getParentType()

Returns the current parent composite type.

Signature:

getParentType(): Maybe<GraphQLCompositeType>;

Returns

Type	Description
`Maybe<GraphQLCompositeType>`	The current parent composite type, if known.

Example

import { parse, visit } from 'graphql/language';
import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
import { ValidationContext } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    greeting: String
  }
`);
const document = parse('{ greeting }');
const typeInfo = new TypeInfo(schema);
const context = new ValidationContext(schema, document, typeInfo, () => {});
let parentTypeName;
 
visit(
  document,
  visitWithTypeInfo(typeInfo, {
    Field: () => {
      parentTypeName = context.getParentType()?.name;
    },
  }),
);
 
parentTypeName; // => 'Query'

getInputType()

Returns the current input type at this point in traversal.

Signature:

getInputType(): Maybe<GraphQLInputType>;

Returns

Type	Description
`Maybe<GraphQLInputType>`	The current input type, if known.

Example

import { parse, visit } from 'graphql/language';
import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
import { ValidationContext } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    reviews(limit: Int): [String]
  }
`);
const document = parse('{ reviews(limit: 5) }');
const typeInfo = new TypeInfo(schema);
const context = new ValidationContext(schema, document, typeInfo, () => {});
let inputTypeName;
 
visit(
  document,
  visitWithTypeInfo(typeInfo, {
    Argument: () => {
      inputTypeName = String(context.getInputType());
    },
  }),
);
 
inputTypeName; // => 'Int'

getParentInputType()

Returns the parent input type for the current input position.

Signature:

getParentInputType(): Maybe<GraphQLInputType>;

Returns

Type	Description
`Maybe<GraphQLInputType>`	The parent input type, if known.

Example

import { parse, visit } from 'graphql/language';
import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
import { ValidationContext } from 'graphql/validation';
 
const schema = buildSchema(`
  input ReviewFilter {
    stars: Int
  }
 
  type Query {
    reviews(filter: ReviewFilter): [String]
  }
`);
const document = parse('{ reviews(filter: { stars: 5 }) }');
const typeInfo = new TypeInfo(schema);
const context = new ValidationContext(schema, document, typeInfo, () => {});
let parentInputTypeName;
 
visit(
  document,
  visitWithTypeInfo(typeInfo, {
    ObjectField: () => {
      parentInputTypeName = String(context.getParentInputType());
    },
  }),
);
 
parentInputTypeName; // => 'ReviewFilter'

getFieldDef()

Returns the current field definition.

Signature:

getFieldDef(): Maybe<
  GraphQLField<unknown, unknown>
>;

Returns

Type	Description
`Maybe<GraphQLField<unknown, unknown>>`	The current field definition, if known.

Example

import { parse, visit } from 'graphql/language';
import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
import { ValidationContext } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    greeting: String
  }
`);
const document = parse('{ greeting }');
const typeInfo = new TypeInfo(schema);
const context = new ValidationContext(schema, document, typeInfo, () => {});
let fieldName;
 
visit(
  document,
  visitWithTypeInfo(typeInfo, {
    Field: () => {
      fieldName = context.getFieldDef()?.name;
    },
  }),
);
 
fieldName; // => 'greeting'

getDirective()

Returns the current directive definition.

Signature:

getDirective(): Maybe<GraphQLDirective>;

Returns

Type	Description
`Maybe<GraphQLDirective>`	The current directive definition, if known.

Example

import { parse, visit } from 'graphql/language';
import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
import { ValidationContext } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    greeting: String
  }
`);
const document = parse('{ greeting @include(if: true) }');
const typeInfo = new TypeInfo(schema);
const context = new ValidationContext(schema, document, typeInfo, () => {});
let directiveName;
 
visit(
  document,
  visitWithTypeInfo(typeInfo, {
    Directive: () => {
      directiveName = context.getDirective()?.name;
    },
  }),
);
 
directiveName; // => 'include'

getArgument()

Returns the current argument definition.

Signature:

getArgument(): Maybe<GraphQLArgument>;

Returns

Type	Description
`Maybe<GraphQLArgument>`	The current argument definition, if known.

Example

import { parse, visit } from 'graphql/language';
import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
import { ValidationContext } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    reviews(limit: Int): [String]
  }
`);
const document = parse('{ reviews(limit: 5) }');
const typeInfo = new TypeInfo(schema);
const context = new ValidationContext(schema, document, typeInfo, () => {});
let argumentName;
 
visit(
  document,
  visitWithTypeInfo(typeInfo, {
    Argument: () => {
      argumentName = context.getArgument()?.name;
    },
  }),
);
 
argumentName; // => 'limit'

getFragmentSignature()

Returns the fragment signature at the current traversal position.

Signature:

getFragmentSignature(): Maybe<FragmentSignature>;

Returns

Type	Description
`Maybe<FragmentSignature>`	The current fragment signature, if one is active.

Example

import { parse, visit } from 'graphql/language';
import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
import { ValidationContext } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    greeting: String
  }
`);
const document = parse(
  `
    {
      ...GreetingFields
    }
 
    fragment GreetingFields on Query {
      greeting
    }
  `,
  { experimentalFragmentArguments: true },
);
const typeInfo = new TypeInfo(schema);
const context = new ValidationContext(schema, document, typeInfo, () => {});
let fragmentName;
 
visit(
  document,
  visitWithTypeInfo(typeInfo, {
    FragmentSpread: () => {
      fragmentName = context.getFragmentSignature()?.definition.name.value;
    },
  }),
);
 
fragmentName; // => 'GreetingFields'

getFragmentSignatureByName()

Returns the function used to look up fragment signatures by name.

Signature:

getFragmentSignatureByName(): (
  fragmentName: string,
) => Maybe<FragmentSignature>;

Returns

Type	Description
`( fragmentName: string, ) => Maybe<FragmentSignature>`	A function that maps fragment names to fragment signatures.

Example

import { parse, visit } from 'graphql/language';
import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
import { ValidationContext } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    greeting: String
  }
`);
const document = parse(
  `
    {
      ...GreetingFields
    }
 
    fragment GreetingFields on Query {
      greeting
    }
  `,
  { experimentalFragmentArguments: true },
);
const typeInfo = new TypeInfo(schema);
const context = new ValidationContext(schema, document, typeInfo, () => {});
let fragmentName;
 
visit(
  document,
  visitWithTypeInfo(typeInfo, {
    Document: () => {
      const getFragmentSignature = context.getFragmentSignatureByName();
      fragmentName =
        getFragmentSignature('GreetingFields')?.definition.name.value;
    },
  }),
);
 
fragmentName; // => 'GreetingFields'

getEnumValue()

Returns the current enum value definition.

Signature:

getEnumValue(): Maybe<GraphQLEnumValue>;

Returns

Type	Description
`Maybe<GraphQLEnumValue>`	The current enum value definition, if known.

Example

import { parse, visit } from 'graphql/language';
import { buildSchema, TypeInfo, visitWithTypeInfo } from 'graphql/utilities';
import { ValidationContext } from 'graphql/validation';
 
const schema = buildSchema(`
  enum Sort {
    NEWEST
    OLDEST
  }
 
  type Query {
    reviews(sort: Sort): [String]
  }
`);
const document = parse('{ reviews(sort: OLDEST) }');
const typeInfo = new TypeInfo(schema);
const context = new ValidationContext(schema, document, typeInfo, () => {});
let enumValueName;
 
visit(
  document,
  visitWithTypeInfo(typeInfo, {
    EnumValue: () => {
      enumValueName = context.getEnumValue()?.name;
    },
  }),
);
 
enumValueName; // => 'OLDEST'

Types

ValidationRule

Type alias. A function that creates an AST visitor for validating a GraphQL document.

type ValidationRule = (
  context: ValidationContext,
) => ASTVisitor;

Category: Validation Rules

Functions:
DeferStreamDirectiveLabelRule()DeferStreamDirectiveOnRootFieldRule()DeferStreamDirectiveOnValidOperationsRule()ExecutableDefinitionsRule()FieldsOnCorrectTypeRule()FragmentsOnCompositeTypesRule()KnownArgumentNamesRule()KnownDirectivesRule()KnownFragmentNamesRule()KnownOperationTypesRule()KnownTypeNamesRule()LoneAnonymousOperationRule()LoneSchemaDefinitionRule()MaxIntrospectionDepthRule()NoFragmentCyclesRule()NoUndefinedVariablesRule()NoUnusedFragmentsRule()NoUnusedVariablesRule()OverlappingFieldsCanBeMergedRule()PossibleFragmentSpreadsRule()PossibleTypeExtensionsRule()ProvidedRequiredArgumentsRule()ScalarLeafsRule()SingleFieldSubscriptionsRule()StreamDirectiveOnListFieldRule()UniqueArgumentDefinitionNamesRule()UniqueArgumentNamesRule()UniqueDirectiveNamesRule()UniqueDirectivesPerLocationRule()UniqueEnumValueNamesRule()UniqueFieldDefinitionNamesRule()UniqueFragmentNamesRule()UniqueInputFieldNamesRule()UniqueOperationNamesRule()UniqueOperationTypesRule()UniqueTypeNamesRule()UniqueVariableNamesRule()ValuesOfCorrectTypeRule()VariablesAreInputTypesRule()VariablesInAllowedPositionRule()

Constants:
recommendedRules specifiedRules

Functions

DeferStreamDirectiveLabelRule()

Defer and stream directive labels are unique

A GraphQL document is only valid if defer and stream directives’ label argument is static and unique.

Signature:

DeferStreamDirectiveLabelRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { parse } from 'graphql/language';
import { buildSchema } from 'graphql/utilities';
import { validate, DeferStreamDirectiveLabelRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    friends: [String]
  }
`);
const invalidDocument = parse(`
  {
    friends @stream(label: "friends")
    other: friends @stream(label: "friends")
  }
`);
const validDocument = parse(`
  {
    friends @stream(label: "friends")
    other: friends @stream(label: "otherFriends")
  }
`);
 
validate(schema, invalidDocument, [DeferStreamDirectiveLabelRule]).length; // => 1
validate(schema, validDocument, [DeferStreamDirectiveLabelRule]); // => []

DeferStreamDirectiveOnRootFieldRule()

Defer and stream directives are used on valid root field

A GraphQL document is only valid if defer directives are not used on root mutation or subscription types.

Signature:

DeferStreamDirectiveOnRootFieldRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { parse } from 'graphql/language';
import { buildSchema } from 'graphql/utilities';
import { validate, DeferStreamDirectiveOnRootFieldRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    message: String
  }
 
  type Mutation {
    updateMessage: String
  }
`);
const invalidDocument = parse(`
  mutation { ... @defer { updateMessage } }
`);
const validDocument = parse(`
  { ... @defer { message } }
`);
 
validate(schema, invalidDocument, [DeferStreamDirectiveOnRootFieldRule]).length; // => 1
validate(schema, validDocument, [DeferStreamDirectiveOnRootFieldRule]); // => []

DeferStreamDirectiveOnValidOperationsRule()

Defer And Stream Directives Are Used On Valid Operations

A GraphQL document is only valid if defer directives are not used on root mutation or subscription types.

Signature:

DeferStreamDirectiveOnValidOperationsRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { parse } from 'graphql/language';
import { buildSchema } from 'graphql/utilities';
import {
  validate,
  DeferStreamDirectiveOnValidOperationsRule,
} from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    message: Message
  }
 
  type Subscription {
    message: Message
  }
 
  type Message {
    body: String
  }
`);
const invalidDocument = parse(`
  subscription {
    message {
      ...MessageBody @defer
    }
  }
 
  fragment MessageBody on Message {
    body
  }
`);
const validDocument = parse(`
  subscription {
    message {
      ...MessageBody @defer(if: false)
    }
  }
 
  fragment MessageBody on Message {
    body
  }
`);
 
validate(schema, invalidDocument, [DeferStreamDirectiveOnValidOperationsRule])
  .length; // => 1
validate(schema, validDocument, [DeferStreamDirectiveOnValidOperationsRule]); // => []

ExecutableDefinitionsRule()

Executable definitions

A GraphQL document is only valid for execution if all definitions are either operation or fragment definitions.

See https://spec.graphql.org/draft/#sec-Executable-Definitions

Signature:

ExecutableDefinitionsRule(
  context: ASTValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ASTValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { ExecutableDefinitionsRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  type Extra { field: String }
`);
const invalidErrors = validate(schema, invalidDocument, [ExecutableDefinitionsRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { name }
`);
const validErrors = validate(schema, validDocument, [ExecutableDefinitionsRule]);
 
validErrors; // => []

FieldsOnCorrectTypeRule()

Fields on correct type

A GraphQL document is only valid if all fields selected are defined by the parent type, or are an allowed meta field such as __typename.

See https://spec.graphql.org/draft/#sec-Field-Selections

Signature:

FieldsOnCorrectTypeRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { FieldsOnCorrectTypeRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  { missing }
`);
const invalidErrors = validate(schema, invalidDocument, [FieldsOnCorrectTypeRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { name }
`);
const validErrors = validate(schema, validDocument, [FieldsOnCorrectTypeRule]);
 
validErrors; // => []

FragmentsOnCompositeTypesRule()

Fragments on composite type

Fragments use a type condition to determine if they apply, since fragments can only be spread into a composite type (object, interface, or union), the type condition must also be a composite type.

See https://spec.graphql.org/draft/#sec-Fragments-On-Composite-Types

Signature:

FragmentsOnCompositeTypesRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { FragmentsOnCompositeTypesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  fragment Bad on String { length }
`);
const invalidErrors = validate(schema, invalidDocument, [FragmentsOnCompositeTypesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  fragment Good on Query { name }
`);
const validErrors = validate(schema, validDocument, [FragmentsOnCompositeTypesRule]);
 
validErrors; // => []

KnownArgumentNamesRule()

Known argument names

A GraphQL field is only valid if all supplied arguments are defined by that field.

See https://spec.graphql.org/draft/#sec-Argument-Names See https://spec.graphql.org/draft/#sec-Directives-Are-In-Valid-Locations

Signature:

KnownArgumentNamesRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { KnownArgumentNamesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    field(arg: String): String
  }
`);
 
const invalidDocument = parse(`
  { field(unknown: "1") }
`);
const invalidErrors = validate(schema, invalidDocument, [KnownArgumentNamesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { field(arg: "1") }
`);
const validErrors = validate(schema, validDocument, [KnownArgumentNamesRule]);
 
validErrors; // => []

KnownDirectivesRule()

Known directives

A GraphQL document is only valid if all @directives are known by the schema and legally positioned.

See https://spec.graphql.org/draft/#sec-Directives-Are-Defined

Signature:

KnownDirectivesRule(
  context: ValidationContext | SDLValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext \| SDLValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { KnownDirectivesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  { name @unknown }
`);
const invalidErrors = validate(schema, invalidDocument, [KnownDirectivesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { name @include(if: true) }
`);
const validErrors = validate(schema, validDocument, [KnownDirectivesRule]);
 
validErrors; // => []

KnownFragmentNamesRule()

Known fragment names

A GraphQL document is only valid if all ...Fragment fragment spreads refer to fragments defined in the same document.

See https://spec.graphql.org/draft/#sec-Fragment-spread-target-defined

Signature:

KnownFragmentNamesRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { KnownFragmentNamesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  { ...Missing }
`);
const invalidErrors = validate(schema, invalidDocument, [KnownFragmentNamesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  fragment NameFields on Query { name } query { ...NameFields }
`);
const validErrors = validate(schema, validDocument, [KnownFragmentNamesRule]);
 
validErrors; // => []

KnownOperationTypesRule()

Known Operation Types

A GraphQL document is only valid if when it contains an operation, the root type for the operation exists within the schema.

See https://spec.graphql.org/draft/#sec-Operation-Type-Existence

Signature:

KnownOperationTypesRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { parse } from 'graphql/language';
import { buildSchema } from 'graphql/utilities';
import { validate, KnownOperationTypesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    greeting: String
  }
`);
const invalidDocument = parse('mutation { greeting }');
const validDocument = parse('{ greeting }');
 
validate(schema, invalidDocument, [KnownOperationTypesRule])[0].message; // => 'The mutation operation is not supported by the schema.'
validate(schema, validDocument, [KnownOperationTypesRule]); // => []

KnownTypeNamesRule()

Known type names

A GraphQL document is only valid if referenced types (specifically variable definitions and fragment conditions) are defined by the type schema.

See https://spec.graphql.org/draft/#sec-Fragment-Spread-Type-Existence

Signature:

KnownTypeNamesRule(
  context: ValidationContext | SDLValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext \| SDLValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { KnownTypeNamesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  fragment Bad on Missing { name }
`);
const invalidErrors = validate(schema, invalidDocument, [KnownTypeNamesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  fragment Good on Query { name }
`);
const validErrors = validate(schema, validDocument, [KnownTypeNamesRule]);
 
validErrors; // => []

LoneAnonymousOperationRule()

Lone anonymous operation

A GraphQL document is only valid if when it contains an anonymous operation (the query short-hand) that it contains only that one operation definition.

See https://spec.graphql.org/draft/#sec-Lone-Anonymous-Operation

Signature:

LoneAnonymousOperationRule(
  context: ASTValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ASTValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { LoneAnonymousOperationRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  query { name } query Other { name }
`);
const invalidErrors = validate(schema, invalidDocument, [LoneAnonymousOperationRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { name }
`);
const validErrors = validate(schema, validDocument, [LoneAnonymousOperationRule]);
 
validErrors; // => []

LoneSchemaDefinitionRule()

Lone Schema definition

A GraphQL document is only valid if it contains only one schema definition.

Signature:

LoneSchemaDefinitionRule(
  context: SDLValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`SDLValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema } from 'graphql';
import { LoneSchemaDefinitionRule } from 'graphql/validation';
 
const invalidSDL = `
  schema { query: Query } schema { query: Query } type Query { name: String }
`;
 
LoneSchemaDefinitionRule.name; // => 'LoneSchemaDefinitionRule'
buildSchema(invalidSDL); // throws an error
 
const validSDL = `
  schema { query: Query } type Query { name: String }
`;
 
buildSchema(validSDL); // does not throw

MaxIntrospectionDepthRule()

Implements the max introspection depth validation rule.

Signature:

MaxIntrospectionDepthRule(
  context: ASTValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ASTValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { MaxIntrospectionDepthRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  { __schema { types { fields { type { fields { type { fields { name } } } } } } } }
`);
const invalidErrors = validate(schema, invalidDocument, [MaxIntrospectionDepthRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { __schema { queryType { name } } }
`);
const validErrors = validate(schema, validDocument, [MaxIntrospectionDepthRule]);
 
validErrors; // => []

NoFragmentCyclesRule()

No fragment cycles

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.

See https://spec.graphql.org/draft/#sec-Fragment-spreads-must-not-form-cycles

Signature:

NoFragmentCyclesRule(
  context: ASTValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ASTValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { NoFragmentCyclesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  fragment A on Query { ...B } fragment B on Query { ...A } query { ...A }
`);
const invalidErrors = validate(schema, invalidDocument, [NoFragmentCyclesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  fragment A on Query { name } query { ...A }
`);
const validErrors = validate(schema, validDocument, [NoFragmentCyclesRule]);
 
validErrors; // => []

NoUndefinedVariablesRule()

No undefined variables

A GraphQL operation is only valid if all variables encountered, both directly and via fragment spreads, are defined by that operation.

See https://spec.graphql.org/draft/#sec-All-Variable-Uses-Defined

Signature:

NoUndefinedVariablesRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { NoUndefinedVariablesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    field(arg: ID): String
  }
`);
 
const invalidDocument = parse(`
  query ($id: ID) { field(arg: $missing) }
`);
const invalidErrors = validate(schema, invalidDocument, [NoUndefinedVariablesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  query ($id: ID) { field(arg: $id) }
`);
const validErrors = validate(schema, validDocument, [NoUndefinedVariablesRule]);
 
validErrors; // => []

NoUnusedFragmentsRule()

No unused fragments

A GraphQL document is only valid if all fragment definitions are spread within operations, or spread within other fragments spread within operations.

See https://spec.graphql.org/draft/#sec-Fragments-Must-Be-Used

Signature:

NoUnusedFragmentsRule(
  context: ASTValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ASTValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { NoUnusedFragmentsRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  fragment Unused on Query { name } query { name }
`);
const invalidErrors = validate(schema, invalidDocument, [NoUnusedFragmentsRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  fragment Used on Query { name } query { ...Used }
`);
const validErrors = validate(schema, validDocument, [NoUnusedFragmentsRule]);
 
validErrors; // => []

NoUnusedVariablesRule()

No unused variables

A GraphQL operation is only valid if all variables defined by an operation are used, either directly or within a spread fragment.

See https://spec.graphql.org/draft/#sec-All-Variables-Used

Signature:

NoUnusedVariablesRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { NoUnusedVariablesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    field(arg: ID): String
    name: String
  }
`);
 
const invalidDocument = parse(`
  query ($id: ID) { name }
`);
const invalidErrors = validate(schema, invalidDocument, [NoUnusedVariablesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  query ($id: ID) { field(arg: $id) }
`);
const validErrors = validate(schema, validDocument, [NoUnusedVariablesRule]);
 
validErrors; // => []

OverlappingFieldsCanBeMergedRule()

Overlapping fields can be merged

A selection set is only valid if all fields (including spreading any fragments) either correspond to distinct response names or can be merged without ambiguity.

See https://spec.graphql.org/draft/#sec-Field-Selection-Merging

Signature:

OverlappingFieldsCanBeMergedRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { OverlappingFieldsCanBeMergedRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    dog: Dog
  }
 
  type Dog {
    name: String
    barkVolume: Int
  }
`);
 
const invalidDocument = parse(`
  { dog { value: barkVolume value: name } }
`);
const invalidErrors = validate(schema, invalidDocument, [OverlappingFieldsCanBeMergedRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { dog { barkVolume name } }
`);
const validErrors = validate(schema, validDocument, [OverlappingFieldsCanBeMergedRule]);
 
validErrors; // => []

PossibleFragmentSpreadsRule()

Possible fragment spread

A fragment spread is only valid if the type condition could ever possibly be true: if there is a non-empty intersection of the possible parent types, and possible types which pass the type condition.

Signature:

PossibleFragmentSpreadsRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { PossibleFragmentSpreadsRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    dog: Dog
  }
 
  type Dog {
    barkVolume: Int
  }
 
  type Cat {
    meowVolume: Int
  }
`);
 
const invalidDocument = parse(`
  { dog { ... on Cat { meowVolume } } }
`);
const invalidErrors = validate(schema, invalidDocument, [PossibleFragmentSpreadsRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { dog { ... on Dog { barkVolume } } }
`);
const validErrors = validate(schema, validDocument, [PossibleFragmentSpreadsRule]);
 
validErrors; // => []

PossibleTypeExtensionsRule()

Possible type extension

A type extension is only valid if the type is defined and has the same kind.

Signature:

PossibleTypeExtensionsRule(
  context: SDLValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`SDLValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema } from 'graphql';
import { PossibleTypeExtensionsRule } from 'graphql/validation';
 
const invalidSDL = `
  extend type Missing { name: String } type Query { name: String }
`;
 
PossibleTypeExtensionsRule.name; // => 'PossibleTypeExtensionsRule'
buildSchema(invalidSDL); // throws an error
 
const validSDL = `
  type Query { name: String } extend type Query { other: String }
`;
 
buildSchema(validSDL); // does not throw

ProvidedRequiredArgumentsRule()

Provided required arguments

A field or directive is only valid if all required (non-null without a default value) field arguments have been provided.

Signature:

ProvidedRequiredArgumentsRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { ProvidedRequiredArgumentsRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    field(required: String!): String
  }
`);
 
const invalidDocument = parse(`
  { field }
`);
const invalidErrors = validate(schema, invalidDocument, [ProvidedRequiredArgumentsRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { field(required: "x") }
`);
const validErrors = validate(schema, validDocument, [ProvidedRequiredArgumentsRule]);
 
validErrors; // => []

ScalarLeafsRule()

Scalar leafs

A GraphQL document is valid only if all leaf fields (fields without sub selections) are of scalar or enum types.

Signature:

ScalarLeafsRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { ScalarLeafsRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  { name { length } }
`);
const invalidErrors = validate(schema, invalidDocument, [ScalarLeafsRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { name }
`);
const validErrors = validate(schema, validDocument, [ScalarLeafsRule]);
 
validErrors; // => []

SingleFieldSubscriptionsRule()

Subscriptions must only include a non-introspection field.

A GraphQL subscription is valid only if it contains a single root field and that root field is not an introspection field.

See https://spec.graphql.org/draft/#sec-Single-root-field

Signature:

SingleFieldSubscriptionsRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { SingleFieldSubscriptionsRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
 
  type Subscription {
    a: String
    b: String
  }
`);
 
const invalidDocument = parse(`
  subscription { a b }
`);
const invalidErrors = validate(schema, invalidDocument, [SingleFieldSubscriptionsRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  subscription { a }
`);
const validErrors = validate(schema, validDocument, [SingleFieldSubscriptionsRule]);
 
validErrors; // => []

StreamDirectiveOnListFieldRule()

Stream directives are used on list fields

A GraphQL document is only valid if stream directives are used on list fields.

Signature:

StreamDirectiveOnListFieldRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { parse } from 'graphql/language';
import { buildSchema } from 'graphql/utilities';
import { validate, StreamDirectiveOnListFieldRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
    friends: [String]
  }
`);
const invalidDocument = parse('{ name @stream(initialCount: 0) }');
const validDocument = parse('{ friends @stream(initialCount: 0) }');
 
validate(schema, invalidDocument, [StreamDirectiveOnListFieldRule]).length; // => 1
validate(schema, validDocument, [StreamDirectiveOnListFieldRule]); // => []

UniqueArgumentDefinitionNamesRule()

Unique argument definition names

A GraphQL Object or Interface type is only valid if all its fields have uniquely named arguments. A GraphQL Directive is only valid if all its arguments are uniquely named.

Signature:

UniqueArgumentDefinitionNamesRule(
  context: SDLValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`SDLValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema } from 'graphql';
import { UniqueArgumentDefinitionNamesRule } from 'graphql/validation';
 
const invalidSDL = `
  type Query { field(arg: String, arg: Int): String }
`;
 
UniqueArgumentDefinitionNamesRule.name; // => 'UniqueArgumentDefinitionNamesRule'
buildSchema(invalidSDL); // throws an error
 
const validSDL = `
  type Query { field(arg: String): String }
`;
 
buildSchema(validSDL); // does not throw

UniqueArgumentNamesRule()

Unique argument names

A GraphQL field or directive is only valid if all supplied arguments are uniquely named.

See https://spec.graphql.org/draft/#sec-Argument-Names

Signature:

UniqueArgumentNamesRule(
  context: ASTValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ASTValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { UniqueArgumentNamesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    field(arg: String): String
  }
`);
 
const invalidDocument = parse(`
  { field(arg: "1", arg: "2") }
`);
const invalidErrors = validate(schema, invalidDocument, [UniqueArgumentNamesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { field(arg: "1") }
`);
const validErrors = validate(schema, validDocument, [UniqueArgumentNamesRule]);
 
validErrors; // => []

UniqueDirectiveNamesRule()

Unique directive names

A GraphQL document is only valid if all defined directives have unique names.

Signature:

UniqueDirectiveNamesRule(
  context: SDLValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`SDLValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema } from 'graphql';
import { UniqueDirectiveNamesRule } from 'graphql/validation';
 
const invalidSDL = `
  directive @tag on FIELD directive @tag on QUERY type Query { name: String }
`;
 
UniqueDirectiveNamesRule.name; // => 'UniqueDirectiveNamesRule'
buildSchema(invalidSDL); // throws an error
 
const validSDL = `
  directive @tag on FIELD type Query { name: String }
`;
 
buildSchema(validSDL); // does not throw

UniqueDirectivesPerLocationRule()

Unique directive names per location

A GraphQL document is only valid if all non-repeatable directives at a given location are uniquely named.

See https://spec.graphql.org/draft/#sec-Directives-Are-Unique-Per-Location

Signature:

UniqueDirectivesPerLocationRule(
  context: ValidationContext | SDLValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext \| SDLValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { UniqueDirectivesPerLocationRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  { name @include(if: true) @include(if: false) }
`);
const invalidErrors = validate(schema, invalidDocument, [UniqueDirectivesPerLocationRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { name @include(if: true) }
`);
const validErrors = validate(schema, validDocument, [UniqueDirectivesPerLocationRule]);
 
validErrors; // => []

UniqueEnumValueNamesRule()

Unique enum value names

A GraphQL enum type is only valid if all its values are uniquely named.

Signature:

UniqueEnumValueNamesRule(
  context: SDLValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`SDLValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema } from 'graphql';
import { UniqueEnumValueNamesRule } from 'graphql/validation';
 
const invalidSDL = `
  enum Status { ACTIVE ACTIVE } type Query { status: Status }
`;
 
UniqueEnumValueNamesRule.name; // => 'UniqueEnumValueNamesRule'
buildSchema(invalidSDL); // throws an error
 
const validSDL = `
  enum Status { ACTIVE INACTIVE } type Query { status: Status }
`;
 
buildSchema(validSDL); // does not throw

UniqueFieldDefinitionNamesRule()

Unique field definition names

A GraphQL complex type is only valid if all its fields are uniquely named.

Signature:

UniqueFieldDefinitionNamesRule(
  context: SDLValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`SDLValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema } from 'graphql';
import { UniqueFieldDefinitionNamesRule } from 'graphql/validation';
 
const invalidSDL = `
  type Query { name: String name: String }
`;
 
UniqueFieldDefinitionNamesRule.name; // => 'UniqueFieldDefinitionNamesRule'
buildSchema(invalidSDL); // throws an error
 
const validSDL = `
  type Query { name: String other: String }
`;
 
buildSchema(validSDL); // does not throw

UniqueFragmentNamesRule()

Unique fragment names

A GraphQL document is only valid if all defined fragments have unique names.

See https://spec.graphql.org/draft/#sec-Fragment-Name-Uniqueness

Signature:

UniqueFragmentNamesRule(
  context: ASTValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ASTValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { UniqueFragmentNamesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  fragment A on Query { name } fragment A on Query { name } query { ...A }
`);
const invalidErrors = validate(schema, invalidDocument, [UniqueFragmentNamesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  fragment A on Query { name } query { ...A }
`);
const validErrors = validate(schema, validDocument, [UniqueFragmentNamesRule]);
 
validErrors; // => []

UniqueInputFieldNamesRule()

Unique input field names

A GraphQL input object value is only valid if all supplied fields are uniquely named.

See https://spec.graphql.org/draft/#sec-Input-Object-Field-Uniqueness

Signature:

UniqueInputFieldNamesRule(
  context: ASTValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ASTValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { UniqueInputFieldNamesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  input Filter {
    name: String
  }
 
  type Query {
    search(filter: Filter): String
  }
`);
 
const invalidDocument = parse(`
  { search(filter: { name: "a", name: "b" }) }
`);
const invalidErrors = validate(schema, invalidDocument, [UniqueInputFieldNamesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { search(filter: { name: "a" }) }
`);
const validErrors = validate(schema, validDocument, [UniqueInputFieldNamesRule]);
 
validErrors; // => []

UniqueOperationNamesRule()

Unique operation names

A GraphQL document is only valid if all defined operations have unique names.

See https://spec.graphql.org/draft/#sec-Operation-Name-Uniqueness

Signature:

UniqueOperationNamesRule(
  context: ASTValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ASTValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { UniqueOperationNamesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  query Same { name } query Same { name }
`);
const invalidErrors = validate(schema, invalidDocument, [UniqueOperationNamesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  query One { name } query Two { name }
`);
const validErrors = validate(schema, validDocument, [UniqueOperationNamesRule]);
 
validErrors; // => []

UniqueOperationTypesRule()

Unique operation types

A GraphQL document is only valid if it has only one type per operation.

Signature:

UniqueOperationTypesRule(
  context: SDLValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`SDLValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema } from 'graphql';
import { UniqueOperationTypesRule } from 'graphql/validation';
 
const invalidSDL = `
  schema { query: Query query: Other } type Query { name: String } type Other { name: String }
`;
 
UniqueOperationTypesRule.name; // => 'UniqueOperationTypesRule'
buildSchema(invalidSDL); // throws an error
 
const validSDL = `
  schema { query: Query } type Query { name: String }
`;
 
buildSchema(validSDL); // does not throw

UniqueTypeNamesRule()

Unique type names

A GraphQL document is only valid if all defined types have unique names.

Signature:

UniqueTypeNamesRule(
  context: SDLValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`SDLValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema } from 'graphql';
import { UniqueTypeNamesRule } from 'graphql/validation';
 
const invalidSDL = `
  type Query { name: String } type Query { other: String }
`;
 
UniqueTypeNamesRule.name; // => 'UniqueTypeNamesRule'
buildSchema(invalidSDL); // throws an error
 
const validSDL = `
  type Query { name: String } type Other { name: String }
`;
 
buildSchema(validSDL); // does not throw

UniqueVariableNamesRule()

Unique variable names

A GraphQL operation is only valid if all its variables are uniquely named.

Signature:

UniqueVariableNamesRule(
  context: ASTValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ASTValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { UniqueVariableNamesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    field(arg: ID): String
  }
`);
 
const invalidDocument = parse(`
  query ($id: ID, $id: ID) { field(arg: $id) }
`);
const invalidErrors = validate(schema, invalidDocument, [UniqueVariableNamesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  query ($id: ID) { field(arg: $id) }
`);
const validErrors = validate(schema, validDocument, [UniqueVariableNamesRule]);
 
validErrors; // => []

ValuesOfCorrectTypeRule()

Value literals of correct type

A GraphQL document is only valid if all value literals are of the type expected at their position.

See https://spec.graphql.org/draft/#sec-Values-of-Correct-Type

Signature:

ValuesOfCorrectTypeRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { ValuesOfCorrectTypeRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    count(limit: Int): Int
  }
`);
 
const invalidDocument = parse(`
  { count(limit: "many") }
`);
const invalidErrors = validate(schema, invalidDocument, [ValuesOfCorrectTypeRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { count(limit: 1) }
`);
const validErrors = validate(schema, validDocument, [ValuesOfCorrectTypeRule]);
 
validErrors; // => []

VariablesAreInputTypesRule()

Variables are input types

A GraphQL operation is only valid if all the variables it defines are of input types (scalar, enum, or input object).

See https://spec.graphql.org/draft/#sec-Variables-Are-Input-Types

Signature:

VariablesAreInputTypesRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { VariablesAreInputTypesRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    field(arg: ID): String
  }
 
  type User {
    name: String
  }
`);
 
const invalidDocument = parse(`
  query ($user: User) { field(arg: "1") }
`);
const invalidErrors = validate(schema, invalidDocument, [VariablesAreInputTypesRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  query ($id: ID) { field(arg: $id) }
`);
const validErrors = validate(schema, validDocument, [VariablesAreInputTypesRule]);
 
validErrors; // => []

VariablesInAllowedPositionRule()

Variables in allowed position

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

See https://spec.graphql.org/draft/#sec-All-Variable-Usages-are-Allowed

Signature:

VariablesInAllowedPositionRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { VariablesInAllowedPositionRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    field(arg: ID!): String
  }
`);
 
const invalidDocument = parse(`
  query ($id: String) { field(arg: $id) }
`);
const invalidErrors = validate(schema, invalidDocument, [VariablesInAllowedPositionRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  query ($id: ID!) { field(arg: $id) }
`);
const validErrors = validate(schema, validDocument, [VariablesInAllowedPositionRule]);
 
validErrors; // => []

Constants

recommendedRules

Technically these aren’t part of the spec but they are strongly encouraged validation rules.

Type

ReadonlyArray<ValidationRule>

specifiedRules

This set includes all validation rules defined by the GraphQL spec.

The order of the rules in this list has been adjusted to lead to the most clear output when encountering multiple validation errors.

Type

ReadonlyArray<ValidationRule>

Category: Custom Rules

Functions:
NoDeprecatedCustomRule()NoSchemaIntrospectionCustomRule()

Functions

NoDeprecatedCustomRule()

No deprecated

A GraphQL document is only valid if all selected fields and all used enum values have not been deprecated.

Note: This rule is optional and is not part of the Validation section of the GraphQL Specification. The main purpose of this rule is detection of deprecated usages and not necessarily to forbid their use when querying a service.

Signature:

NoDeprecatedCustomRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import {
  GraphQLObjectType,
  GraphQLSchema,
  GraphQLString,
  parse,
  validate,
} from 'graphql';
import { NoDeprecatedCustomRule } from 'graphql/validation';
 
const schema = new GraphQLSchema({
  query: new GraphQLObjectType({
    name: 'Query',
    fields: {
      name: { type: GraphQLString },
      oldName: {
        type: GraphQLString,
        deprecationReason: 'Use name instead.',
      },
    },
  }),
});
 
const invalidDocument = parse(`
  { oldName }
`);
const invalidErrors = validate(schema, invalidDocument, [NoDeprecatedCustomRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { name }
`);
const validErrors = validate(schema, validDocument, [NoDeprecatedCustomRule]);
 
validErrors; // => []

NoSchemaIntrospectionCustomRule()

Prohibit introspection queries

A GraphQL document is only valid if all fields selected are not fields that return an introspection type.

Note: This rule is optional and is not part of the Validation section of the GraphQL Specification. This rule effectively disables introspection, which does not reflect best practices and should only be done if absolutely necessary.

Signature:

NoSchemaIntrospectionCustomRule(
  context: ValidationContext,
): ASTVisitor;

Arguments

Name	Type	Description
context	`ValidationContext`	The validation context used while checking the document.

Returns

Type	Description
`ASTVisitor`	A visitor that reports validation errors for this rule.

Example

import { buildSchema, parse, validate } from 'graphql';
import { NoSchemaIntrospectionCustomRule } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    name: String
  }
`);
 
const invalidDocument = parse(`
  { __schema { queryType { name } } }
`);
const invalidErrors = validate(schema, invalidDocument, [NoSchemaIntrospectionCustomRule]);
 
invalidErrors.length; // => 1
 
const validDocument = parse(`
  { name }
`);
const validErrors = validate(schema, validDocument, [NoSchemaIntrospectionCustomRule]);
 
validErrors; // => []

Category: Validation

Functions:
validate()

Types:
ValidationOptions

Functions

validate()

Implements the “Validation” section of the spec.

Validation runs synchronously, returning an array of encountered errors, or an empty array if no errors were encountered and the document is valid.

A list of specific validation rules may be provided. If not provided, the default list of rules defined by the GraphQL specification will be used.

Each validation rule is a function that returns a visitor (see the language/visitor API). Visitor methods are expected to return GraphQLErrors, or Arrays of GraphQLErrors when invalid.

Validate will stop validation after a maxErrors limit has been reached. Attackers can send pathologically invalid queries to induce a DoS attack, so maxErrors defaults to 100 errors.

Signature:

validate(
  schema: GraphQLSchema,
  documentAST: DocumentNode,
  rules: readonly ValidationRule[] = specifiedRules,
  options?: ValidationOptions,
): readonly GraphQLError[];

Arguments

Name	Type	Default	Description
schema	`GraphQLSchema`		Schema to validate against.
documentAST	`DocumentNode`		Document AST to validate.
rules	`readonly ValidationRule[]`	`specifiedRules`	Validation rules to apply.
options?	`ValidationOptions`		Validation options, including error limits and suggestions.

Returns

Type	Description
`readonly GraphQLError[]`	Validation errors, or an empty array when the document is valid.

Example 1

// Validate with the default specified rules.
import { parse } from 'graphql/language';
import { buildSchema } from 'graphql/utilities';
import { validate } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    fullName: String
  }
`);
 
validate(schema, parse('{ greeting }')); // => []
 
const errors = validate(schema, parse('{ missing }'));
errors[0].message; // => 'Cannot query field "missing" on type "Query".'

Example 2

// This variant uses a custom rule list and validation options.
import { parse } from 'graphql/language';
import { buildSchema } from 'graphql/utilities';
import { FieldsOnCorrectTypeRule, validate } from 'graphql/validation';
 
const schema = buildSchema(`
  type Query {
    greeting: String
  }
`);
const document = parse('{ missingOne missingTwo }');
 
const errors = validate(
  schema,
  document,
  [FieldsOnCorrectTypeRule],
  { maxErrors: 1 },
);
 
errors.length; // => 2
errors[1].message; // => 'Too many validation errors, error limit reached. Validation aborted.'
 
const hiddenSuggestionErrors = validate(
  schema,
  parse('{ name }'),
  [FieldsOnCorrectTypeRule],
  { hideSuggestions: true },
);
 
hiddenSuggestionErrors[0].message; // => 'Cannot query field "name" on type "Query".'

Types

ValidationOptions

Interface. Options used when validating a GraphQL document.

Members

Name	Type	Description
maxErrors?	`number`	Maximum number of validation errors before validation stops.
hideSuggestions?	`Maybe<boolean>`	Whether suggestion text should be omitted from validation errors.

graphql/utilities