GraphQL Schema Formatter

Reformat GraphQL SDL or operations with two-space indentation and one field per line, keeping descriptions and # comments. Invalid input is reported.

The interactive tool loads here when JavaScript runs.

About this tool

What is the GraphQL Schema Formatter?

The GraphQL Schema Formatter parses a schema written in SDL (type, input, enum, interface, union, scalar, directive and schema definitions) and prints it back in a consistent layout: two-space indentation, one field per line, a blank line between definitions and normalized spacing around colons, defaults and directives. Queries, mutations and fragments are formatted the same way.

Because it parses rather than pattern-matches, minified input like type User{id:ID! name:String!} comes out correctly split into fields, colons inside description strings are left alone, and argument lists stay on one line unless they are long or documented. Descriptions keep their "quoted" or """block""" style, and # comments stay attached to the line they were on.

If the input does not parse, you get the syntax error with its line and column instead of half-formatted output. Formatting happens in your browser.

  • Real GraphQL parser, not regex replacements
  • Handles SDL, operations and fragments
  • Keeps descriptions and # comments
  • Reports syntax errors with line and column
  • Copy or download as .graphql; runs locally
Read the guide: GraphQL Schemas and Queries: Validation, Types and Query Cost

Updated

How to use the GraphQL Schema Formatter

  1. Paste a schema or operation into the input box, or press Load Sample for a minified example.
  2. Press Format. If the input has a syntax error, a message shows the line and column.
  3. Review the output, then Copy it or Download it as formatted-schema.graphql.
  4. Use Clear to start again.

Worked examples

Minified SDL

Input

type User{id:ID! name:String! posts:[Post!]!}type Query{user(id:ID!):User}

Output

type User {
  id: ID!
  name: String!
  posts: [Post!]!
}

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

Fields are separated even though the input had no newlines or commas, which a regex-based formatter cannot do reliably.

Comments and descriptions survive

Input

# Users
type User { "Display name: shown publicly" name: String # trailing note
}

Output

# Users
type User {
  "Display name: shown publicly"
  name: String # trailing note
}

The colon inside the description is not touched, and the trailing comment stays on its field.

Background and insight

SDL, the Schema Definition Language, became part of the GraphQL specification in the June 2018 edition. Before that, schemas were mostly built in code, and every server library printed them slightly differently. A shared text format is what made schema files reviewable in pull requests, and a consistent layout is what keeps those diffs small: when every field sits on its own line, adding a field is a one-line change.

Commas in GraphQL are insignificant: the lexer treats them like whitespace. That is why some codebases separate arguments with commas and others do not, and why a formatter can safely normalize them. Descriptions are different: they are part of the schema, returned by introspection and shown in GraphiQL, so they are kept exactly.

Common use cases

  • Cleaning up a printed schema

    Tidy SDL dumped by a server library or an introspection-to-SDL script before committing it.

  • Reviewing schema changes

    Format both versions the same way so a diff shows real changes instead of whitespace noise.

  • Reading minified queries

    Expand a one-line query copied from a network log into readable, indented form.

  • Preparing docs

    Produce consistently indented SDL snippets for READMEs and API docs.

Tips and limitations

  • Formatting checks syntax only. Use the GraphQL Schema Validator to catch unknown types, broken interfaces and missing root types.
  • Running the formatter on its own output gives the same output, so it is safe to apply in a pre-commit habit.
  • Comments at the very end of a selection set are folded onto the last field; move important notes into descriptions, which are part of the schema.
  • For large codebases, a Prettier setup with GraphQL support formats files on save; this tool is for quick one-off cleanups.

Sources and further reading

  1. GraphQL Specification, June 2018 edition, GraphQL Foundation. The edition that added the Schema Definition Language
  2. GraphQL Specification, October 2021 edition, GraphQL Foundation. Insignificant commas, comments and descriptions
  3. Schemas and Types, GraphQL Foundation

Frequently asked questions

Does the GraphQL Schema Formatter remove comments?

No. Lines starting with # are kept and printed above the definition, field or value they precede, and a comment at the end of a line stays at the end of that line. Descriptions in quotes or triple quotes are kept exactly too.

Can I format GraphQL queries as well as schemas?

Yes. Queries, mutations, subscriptions and fragments are parsed and printed with the same two-space indentation, including variables, aliases, arguments, directives and inline fragments.

Why does the formatter refuse my schema?

Because it could not parse it, and printing a guess would hide the mistake. The error gives a line and column. Typical causes are a missing colon between a field and its type, an unclosed brace or bracket, or an empty block like type User {}.

Are commas required between GraphQL fields or arguments?

No, commas are optional everywhere in GraphQL and treated like whitespace. The formatter prints fields on separate lines without commas and separates arguments with ", " when they fit on one line.

Does formatting change what my GraphQL schema means?

No. Only whitespace, commas and line breaks change. Names, types, default values, directives and descriptions are printed as parsed, so the formatted schema builds the same server schema as the original.

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

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.