GraphQL Schema Validator

Validate GraphQL SDL for syntax errors, unknown types, duplicate fields, bad interface implementations and a missing Query root, with line numbers.

The interactive tool loads here when JavaScript runs.

About this tool

What is the GraphQL Schema Validator?

The GraphQL Schema Validator checks a schema written in SDL the way a GraphQL server does when it starts up. It parses the text, merges any extend definitions, and then checks the rules from the GraphQL specification: every referenced type exists, names are unique, input types are only used for arguments and input fields, object types implement their interfaces correctly, unions only contain object types, enums and objects are not empty, and the schema has a query root.

Each problem is listed with its line number. A schema with no errors is valid; warnings point out types that nothing can reach, and suggestions cover naming conventions (PascalCase types, camelCase fields, SCREAMING_SNAKE_CASE enum values) and missing descriptions. Validation runs in your browser.

It validates one SDL document on its own. Federation directives such as @key are reported as unknown unless you declare them with a directive definition, and operations (queries, fragments) are flagged because they belong in a client, not in a schema file.

  • Spec rules for types, fields, arguments, interfaces, unions, enums and inputs
  • Supports extend type, schema definitions and custom directives
  • Errors with line numbers
  • Reachability warnings and naming suggestions
  • Runs locally in your browser
Read the guide: GraphQL Schemas and Queries: Validation, Types and Query Cost

Updated

How to use the GraphQL Schema Validator

  1. Paste your SDL into the GraphQL Schema box, or press Load Sample.
  2. Press Validate Schema.
  3. Fix the errors in order. Each one names the type or field and the line it is on.
  4. Review warnings and suggestions, which do not stop the schema from building but are worth a look.
  5. Copy or download the schema as schema.graphql when it passes.

Worked examples

An interface field is missing

Input

interface Node { id: ID! }
type User implements Node { name: String }
type Query { node: Node }

Output

Line 2: Interface field "Node.id" expected but "User" does not provide it.

Implementing an interface is a promise to provide all of its fields with compatible types.

An input type used as a field type

Input

input Filter { name: String }
type Query { filter: Filter }

Output

Line 2: The type of "Query.filter" must be an output type, but got input type "Filter".

Input objects can only appear as argument types or inside other input objects.

Background and insight

The rules being checked come from the "Type System" and "Type Validation" sections of the GraphQL specification. Some of them are easy to break by hand. A field on an output type cannot use an input type, and an argument cannot use an object type, because inputs and outputs are deliberately separate type families. An object that implements an interface must provide every interface field with a compatible type, and "compatible" allows narrowing: if Node.friend returns Node, User.friend may return User, and a nullable interface field may be non-null on the object.

The query root is the other common surprise. If there is no schema { ... } block, servers look for a type literally named Query (and Mutation, Subscription). If you rename the root to RootQuery you must add schema { query: RootQuery }. Names starting with two underscores are reserved for introspection (__typename, __schema), so your own types and fields cannot use them.

Common use cases

  • Before a deploy

    Catch a schema that would make the server crash at startup, such as a typo in a type name.

  • Reviewing a schema pull request

    Paste the changed SDL to check interface and union rules without running the server.

  • Designing a schema first

    Iterate on a schema-first design and keep it valid before any resolvers exist.

  • Learning the type system rules

    See exactly which rule a schema breaks, with the spec's wording.

Tips and limitations

  • Declare custom directives before using them, for example directive @auth(role: String) on FIELD_DEFINITION.
  • Federation and other server-specific directives are not built in; add their directive definitions or expect "Unknown directive" errors.
  • A type that nothing references still builds but is invisible to clients; the warning helps you find leftovers after a refactor.
  • Breaking-change detection (removing a field clients use) needs the old and new schema compared, which this validator does not do.

Sources and further reading

  1. GraphQL Specification, October 2021 edition, GraphQL Foundation. The Type System and type validation rules this validator applies
  2. Schemas and Types, GraphQL Foundation. Object, input, interface and union types
  3. Introspection, GraphQL Foundation. The reserved double-underscore names

Frequently asked questions

What does the GraphQL Schema Validator check?

It checks syntax plus the type system rules a server enforces at startup: unknown or duplicate types and fields, input versus output type misuse, interface implementations, union members, empty types and enums, unknown directives, reserved __ names, invalid default values and a missing query root type.

Why does my schema fail with "Query root type must be provided"?

Every GraphQL schema needs a query root. Without a schema block, servers look for a type named exactly Query. Either add type Query { ... } or declare schema { query: YourRootType }.

Can I validate an Apollo Federation subgraph schema here?

Partly. The core rules apply, but directives like @key, @shareable and @external are not built in, so they show as unknown. Paste the federation directive definitions above your types to validate the rest.

Can I use an input type as a field type in GraphQL?

No. Input object types can only be used for arguments and fields of other input types, and object, interface and union types can only be used for output fields. Create a separate output type with the same fields if you need both.

Is a GraphQL schema with warnings still valid?

Yes. Only errors make a schema invalid. Warnings flag types that cannot be reached from the root types, and suggestions are naming and documentation conventions. A server will build the schema either way.

Does this validate queries against my schema?

No. It validates the schema document itself. If you paste a query or fragment it reports that operations do not belong in a schema file. Run queries against a server with the GraphQL Playground to have them validated against the live schema.

Is there an in-depth guide to the GraphQL Schema Validator?

Yes. “GraphQL Schemas and Queries: Validation, Types and Query Cost” covers the background, how it works, common pitfalls and worked examples. Read the full guide.