Guide

GraphQL Schema Inspector: Validate and Explore SDL Files

Short answer: To validate a GraphQL schema, paste your schema (SDL) or drop a .graphql / .gql file into the GraphQL Schema Inspector. It reports syntax errors with line and column, checks the schema for common mistakes, lets you browse types, fields and arguments, searches the whole schema, and exports Markdown documentation or a JSON representation. It runs in your browser and never contacts a GraphQL endpoint.

What a GraphQL schema and SDL are

A GraphQL schema describes everything a client can ask an API for: object types, their fields, the arguments those fields accept, and the types they return. It is usually written in SDL (Schema Definition Language), for example:

type Query {
  user(id: ID!): User
}

type User implements Node {
  id: ID!
  name: String
  posts(first: Int = 10): [Post!]!
}

interface Node {
  id: ID!
}

Besides object types, SDL has interfaces, unions, enums, scalars, input objects, directive definitions, the schema block and type extensions.

SDL vs introspection

  • SDL is the human-written text file (schema.graphql). It keeps comments, descriptions and directives.
  • Introspection is a special query a running server answers with a JSON description of its schema. It is machine-readable, but it omits comments and most directive usage.

Where possible, keep and review the SDL. If you only have a live API, export its schema as SDL with your tooling and paste that text here. The inspector's JSON export is not an introspection result, so tools that expect introspection JSON cannot use it.

Why inspect a schema

  1. Catch mistakes before the server does. A schema with an unknown type, a mismatched interface or a bad default value fails at startup or in CI.
  2. Understand someone else's API. Large schemas are hard to read as text. A type-by-type explorer is faster.
  3. Review changes. Search for a field or directive across the whole schema before you rename or remove it (see also Text Diff Checker).
  4. Produce documentation. Export a readable reference as Markdown.
  5. Find structural problems such as non-null cycles between input objects.

What the inspector checks

  • Syntax: errors are shown with line and column. The parser keeps going, so several errors can appear at once.
  • Model checks after parsing:
  • duplicate definitions;
  • unknown type references, with suggestions;
  • fields and arguments that use the wrong kind of type (for example, an object type where an input type is required);
  • interface implementations that do not match the interface;
  • unions with non-object members;
  • invalid default values;
  • unknown or misplaced directives;
  • non-null cycles between input objects.

How to validate a GraphQL schema with the inspector

  1. Open the GraphQL Schema Inspector.
  2. Paste SDL, open a .graphql or .gql file, or drop one anywhere on the tool. You can also load the example.
  3. Read the Summary and the Problems list. Fix the first syntax error, then recheck.
  4. Explore: the explorer follows the path Type → Field → Arguments → Return type. Select a type, read its fields and arguments, and click a return type to open it. A breadcrumb lets you step back.
  5. Search: look across type, field, argument, enum value and directive names, optionally including descriptions. Filter by type kind. Matches are highlighted.
  6. Operations tab: lists every query, mutation and subscription.
  7. Documentation tab: renders the schema as readable reference you can download as Markdown. Preview it with the Markdown ↔ HTML Converter, whose Preview tab shows how the Markdown will look (see what converts exactly between Markdown and HTML).
  8. Export: choose a JSON representation with options (statistics, problems, source locations, built-in directives). Send JSON on to the JSON Formatter or the JSON Tree Viewer, or compare two JSON files after a schema change.

Large schemas are analysed in a background worker, and long lists are shown a page at a time.

Common schema errors and what they usually mean

Symptom Usual cause Fix
Unknown type Foo Typo, or the type is defined elsewhere Fix the name (the tool suggests close matches) or add the definition
Interface field missing or wrong type An object says implements Node but does not match its fields Add or correct the field so it matches
Union member is not an object type A scalar, enum or interface used in a union Unions may contain object types only
Output type used as an input A normal type used as an argument or input field Define an input type for it
Duplicate definition The same type or field defined twice Merge or rename
Invalid default value Default does not match the argument's type Correct the value
Unknown directive Directive used but not defined Define it, or ignore it if your framework supplies it

Limits to know

  • It is not the reference GraphQL validator. A schema that is error-free here has parsed and passed this tool's checks. That does not guarantee a particular server or framework will accept it, because servers add their own rules and directives.
  • It inspects SDL only. Queries, mutations and fragments are operations, not schema, and are rejected with an explanation.
  • It does not run introspection, send queries or contact any endpoint.
  • Types or directives that your framework adds for you (some scalars and directives, for example) are reported as undefined so you can define or ignore them. That is expected, not necessarily a bug.
  • Columns are counted in UTF-16 code units, the same as most editors. Descriptions can be in any language, but names must be ASCII, as the GraphQL specification requires.
  • When you send JSON or documentation to another tool on the site, the text passes through your browser's session storage and is cleared after it is received. The schema itself is not uploaded, logged or stored.

Good practice for schemas

  1. Keep a single source-of-truth schema.graphql in version control.
  2. Validate it in CI with your framework's own tooling as well as a quick inspection like this.
  3. Give every type and field a description. They show up in the documentation export.
  4. Mark fields deprecated instead of deleting them, and search the schema before removing anything.
  5. Be careful with non-null (!) on fields that may fail. A null in a non-null field propagates upward.

Frequently asked questions

How do I validate a GraphQL schema? Paste the SDL into the GraphQL Schema Inspector and read the Problems list, then also run your server's own validation.

What is the difference between SDL and introspection? SDL is the text definition; introspection is a JSON answer from a running server that omits comments and most directive usage.

Can I check a live endpoint? Not with this tool, which never contacts an endpoint. Export the schema as SDL first.

Does it validate queries? No. It checks schema definitions only.

Is my schema private? It is processed in your browser. It is not uploaded, logged or stored.

Related tools and guides

Sources and further reading