Staaarter Tools

GraphQL Schema Validator

Validates GraphQL SDL (Schema Definition Language) for the mistakes that break most GraphQL parsers and codegen tools: unbalanced braces or parentheses, invalid type/interface/enum/input/scalar/union/schema declarations, malformed field syntax, duplicate type names, and fields or implements/union/schema references that point at a type nothing in the document ever defines. A free online tool from Staaarter, right in your browser.

Runs locallyUpdated 2026-07-27
validationgraphqlsdl

Overview

Introduction

A hand-written or hand-edited GraphQL schema is easy to get subtly wrong: a field that references a type you renamed, a missing closing brace three types down, two types accidentally sharing a name after a copy-paste.

This tool checks a GraphQL SDL document for exactly those structural mistakes and reports each one with its location, entirely in your browser.

What Is GraphQL Schema Validator?

A structural validator for GraphQL SDL (Schema Definition Language) documents.

It's part of this site's API Tools collection and runs entirely client-side. It pairs with the GraphQL Schema Generator, which produces SDL from a described data model rather than checking existing SDL.

How GraphQL Schema Validator Works

The document is first checked for balanced braces and parentheses. It's then split into top-level type/interface/enum/input/scalar/union/schema declarations by scanning for those keywords outside any nested brace block, so a field named the same as a keyword never gets mistaken for a new declaration.

Each declaration is checked against the syntax its kind requires (a brace body with at least one field for type/interface/input, an "= Member | Member" list for union, values for enum, no body for scalar), every field is checked for valid "name: Type" or "name(args): Type" syntax, and every type name referenced anywhere (fields, implements clauses, union members, schema operation types) is checked against the set of names actually declared in the document.

When To Use GraphQL Schema Validator

Use it after hand-editing a GraphQL schema file, before feeding it to a server implementation or codegen tool that will fail on a structural mistake.

It's also useful for spot-checking SDL pulled from a third-party API or generated by another tool before trusting it.

Often used alongside GraphQL Schema Generator, OpenAPI Validator and Swagger Validator.

Features

Advantages

  • Catches the specific structural mistakes that most commonly break GraphQL parsers, not just generic bracket-matching.
  • Cross-checks every type reference in the document (fields, interfaces, unions, schema operations) against what's actually declared, catching typos and renamed types that a simple syntax check would miss.
  • Reports each issue's location (which declaration and, where relevant, which field) alongside a plain-language explanation.

Limitations

  • Doesn't validate argument types, directive definitions or usage beyond stripping them out, or default-value literals, so a schema that passes here can still be rejected by a full GraphQL parser.
  • Doesn't support field arguments that themselves contain nested parentheses, an uncommon pattern in hand-written SDL.

Examples

A field referencing an undefined type

Input

type Product {
  id: ID!
  category: Category
}

Output

Error at type Product.category: References type "Category", which is never defined.

"Category" is used as a field type but no "type Category", "enum Category", or other declaration for it exists anywhere in the document.

A malformed field type

Input

type Product {
  tags: [String
}

Output

Error at type Product.tags: "[String" is not a syntactically valid field type.

The list type is opened with "[" but never closed with a matching "]", so it can't be parsed as a valid GraphQL type expression.

Best Practices & Notes

Best Practices

  • Run this after any manual edit to a schema, since a renamed or deleted type is easy to leave a dangling reference to.
  • Fix errors before warnings; warnings like unrecognized trailing text often just mean a comment or directive this tool doesn't model, while errors will break parsing outright.
  • Pair with the GraphQL Query Tester to confirm the schema actually behaves as expected against a live endpoint once it structurally validates here.

Developer Notes

Declarations are located by scanning for the type/interface/enum/input/scalar/union/schema keywords only at brace-nesting depth zero (computed with a single forward pass tracking `{`/`}` balance), which is what lets a field literally named "type" or "schema" pass through untouched. Field declarations are matched with a single regex whose optional argument-list group consumes the whole `(...)` span in one match, so a `name: Type` pair inside a default value's arguments doesn't get mistaken for a sibling field. Description strings (`"..."` and `"""..."""`) and `#` comments are blanked to same-length whitespace before any of this scanning happens, so braces or keywords hidden inside them can't skew the brace count or the declaration split.

GraphQL Schema Validator Use Cases

  • Validating a hand-written or hand-edited GraphQL schema before wiring it up to a resolver implementation
  • Checking SDL exported or copied from a third-party API for structural mistakes before trusting it
  • Catching a dangling type reference left behind after renaming or deleting a type

Common Mistakes

  • Assuming a schema that passes here is fully valid GraphQL; it targets structural and reference mistakes, not full spec conformance (argument types, directive schemas, default-value literals).
  • Forgetting that "extend type" blocks aren't checked for a matching base type declaration, since resolving extensions against their base type is out of scope for a structural check.

Tips

  • Fix duplicate-type-name errors first; once two declarations share a name, every reference to that name becomes ambiguous for the rest of the report.

References

Frequently Asked Questions