GraphQL Formatter

Formatting profile:

Pick a profile first, then tune visible options when the document needs a team-specific handoff.

GraphQL document:

Paste one GraphQL document or drop a .graphql, .gql, or .txt file onto the editor.

Document role:

Use Auto detect for normal paste work; choose a role when reviewing operation-only or schema-only files.

Indent width: {{ indentLabel }}

Use 2 or 4 spaces for most GraphQL repositories.

spaces

{{ warning }}

Keep comments:

Turn off when the formatted handoff should behave like a production persisted-query body.

Final newline:

Leave on for repository files; turn off for exact clipboard payloads.

Artifact	Bytes	Lines	Delta vs input	Review note	Copy
{{ row.artifact }}	{{ row.bytesLabel }}	{{ row.linesLabel }}	{{ row.deltaLabel }}	{{ row.note }}

Definition	Name	Kind	Signals	Copy
`{{ row.definition }}`	{{ row.name }}	{{ row.kind }}	{{ row.signals }}

Check	Status	Detail	Copy
{{ row.check }}	{{ row.status }}	{{ row.detail }}

Export to PDF Fullscreen

Embed:

Customize

Include current inputs

Size

Advanced

Width

Height

Aspect ratio

Max height

Collapsible embed

Allow fullscreen

Referrer policy

Sandbox tokens

GraphQL documents describe API reads, writes, subscriptions, reusable fragments, and schema definitions in a compact structured language. Formatting matters because nested selection sets, arguments, variables, directives, and schema fields can become hard to review when everything is compressed onto one line or pasted from a ticket, console, or generated client.

Readable GraphQL is not only about indentation. A query can be easier to scan when each nested field sits under its parent, when comments stay with the relevant section, and when fragments or schema definitions are easy to count before handoff. A compact persisted-query body has a different goal: remove comments and unnecessary spacing so the operation can travel as a small stable payload.

GraphQL text moving through token and bracket checks into readable and compact outputs.

Formatting still has a hard limit. Balanced braces and tidy output do not prove that a field exists on the target schema, that a fragment is valid for a type, or that variable values will pass server validation. Treat formatted text as review evidence, then validate important operations against the GraphQL service or schema that will execute them.

Schema definition language, often shortened to SDL, is part of the same GraphQL language family but serves a different job from executable operations. SDL describes available types, fields, arguments, directives, and root operation entry points; executable documents ask for data or mutations against a schema that already exists.

How to Use This Tool:

Choose the handoff style first, then load the GraphQL text and check the warning state before copying any result.

Set Formatting profile to Review workspace for readable inspection, Persisted query handoff for compact operation text, Schema SDL cleanup for type-system definitions, or Custom when the visible settings should be controlled directly.
Paste an operation, fragment, schema SDL document, or mixed GraphQL file into GraphQL document. You can also use Browse GraphQL, drop a .graphql, .gql, or .txt file onto the editor, load the sample, or clear the current text.
Use Document role when the document should be treated as operations only, schema SDL only, or a mixed file. Auto detect is the normal choice for pasted snippets.
Set Indent width from 1 to 8 spaces. Two spaces fits most GraphQL examples; four spaces may match repositories that use wider indentation.
Open Advanced when comments or the final newline matter. Keep comments controls the readable formatted document; the compact persisted-query result always removes comments. Final newline is useful for saved repository files and can be turned off for exact clipboard payloads.
Read the summary and warning alert. Syntax Needs Review or an unclosed string, unexpected character, or unmatched bracket warning means the compact persisted-query result should not be used yet.
Use Formatted Document for review text, Persisted Query for the compact body, Payload Footprint for byte and line comparison, Definition Inventory for operations, fragments, and SDL definitions, and Formatter Audit for the final check list.

Interpreting Results:

The summary headline is a status cue, not a schema verdict. GraphQL Formatted Locally, Persisted Query Ready, or Schema SDL Formatted means the local pass could tokenize the text and balance brackets. Formatted with Caveats means output exists, but role mismatch, document shape, or size warnings need review.

Formatter Audit is the safest place to check what happened. Bracket structure should be Balanced before a compact payload is copied. Role fit should match the intended handoff, and Operation naming should be reviewed before using persisted-query output with registries, tracing, or clients that need an explicit operationName. Schema-aware validation is intentionally marked Not run, so field existence, variable types, directive support, fragment cycles, and server-specific rules still need a GraphQL validator or real API check.

GraphQL formatter result signals
Result signal	What it means	What to verify next
Syntax Needs Review	The text has an unclosed string, unexpected character, or bracket mismatch.	Fix the first message in the warning alert, then recheck Formatter Audit.
Definition Inventory count	Top-level operations, fragments, and schema definitions were detected from tokens.	Confirm the names and kinds match the file you intended to format.
Payload Footprint delta	Bytes and lines are compared for the original text, readable output, and compact payload.	Use the compact byte count only after syntax warnings are gone.
Schema-aware validation not run	The local pass did not check the document against a service schema.	Run important operations through your GraphQL server, client compiler, or schema validator.

Technical Details:

GraphQL source text is read as tokens separated by ignored material such as whitespace, line terminators, comments, and commas. Names are case-sensitive and can identify operations, fields, types, variables, directives, fragments, and schema members. Punctuators such as {, }, (, ), [, ], @, $, and ... carry the structure that a formatter must preserve.

Comments begin with # and run to the end of the line. They are useful in review copies and schema notes, but executable GraphQL comments do not change execution. Commas are also insignificant in GraphQL documents, so a compact persisted-query body can remove optional commas without changing the token meaning.

Transformation Core:

GraphQL formatter transformation stages
Stage	Rule	Review point
Normalize text	Line endings are treated consistently so counts, indentation, and warnings refer to one line model.	Line counts in Payload Footprint are comparable across pasted and file-loaded text.
Tokenize GraphQL	Names, numbers, strings, block strings, comments, spread markers, and punctuators are read as separate units.	Unclosed strings, unclosed block strings, and unknown characters stop trustworthy formatting.
Check bracket structure	Braces, parentheses, and square brackets are matched with a stack-style balance check.	Balanced brackets are required for compact payload output, but they do not prove schema validity.
Emit readable text	Nested selection sets and schema blocks are indented with the selected width, with comments kept or removed according to the readable-output setting.	Use this output for code review, tickets, or repository cleanup.
Emit compact text	Comments, optional commas, and unnecessary whitespace are removed while separators needed between adjacent names and literals remain.	Use this only after syntax and role warnings have been addressed.
Inventory definitions	Top-level operations, fragments, SDL definitions, extensions, and directive definitions are summarized with variables, directives, comments, and block counts.	Use the inventory to catch an operation file that accidentally includes schema SDL, or the reverse.

Rule Core:

GraphQL formatter warning and role rules
Check	Rule	Result signal
Operation definitions	`query`, `mutation`, `subscription`, anonymous selection sets, and `fragment` starts are counted as executable definitions.	Definition Inventory reports operation and fragment rows.
Schema definitions	`schema`, `type`, `input`, `enum`, `interface`, `union`, `scalar`, `directive`, and supported `extend` forms are counted as schema definitions.	Role fit warns when schema definitions appear in an operation-only handoff.
Mixed role	Mixed documents are expected to include at least one executable definition and at least one schema definition.	A warning appears when either definition type is missing.
Large input	Text above `1 MB` receives a browser-performance warning.	Formatting may still work, but mobile review can slow down.
Schema validation	No target schema is loaded, so field existence, fragment spread validity, variable coercion, directive support, and resolver behavior are outside the local pass.	Formatter Audit marks schema-aware validation as Not run.

Formula Core:

Payload comparison uses UTF-8 byte counts so multi-byte characters are measured by transport size rather than visible character count.

Delta vs input

Delta percent = \frac{Output bytes - Input bytes}{Input bytes} \times 100

A negative percentage means the selected output is smaller than the original text. A positive percentage means readable formatting or a final newline increased the byte count.

The compact output is deterministic for the current text and settings, but it is not a full GraphQL printer. It preserves the token stream it can read, strips comments for persisted-query use, and stops short of schema-aware rewriting or validation.

Privacy Notes:

Pasted GraphQL text and selected files are processed in the browser for formatting, footprint comparison, inventory rows, audit rows, and JSON output. Avoid putting secrets, access tokens, or production identifiers into examples that you plan to copy, download, or share with teammates.

Worked Examples:

Review a query and fragment before an API console test

A paste containing query GetOrder($id: ID!) plus fragment OrderMoney on Order works well with Review workspace, Auto detect, and Keep comments on. The summary should show formatted local output, and Definition Inventory should list the query and fragment with variable, directive, selection, and comment counts.

Prepare a compact persisted query body

For a named query that has already been validated elsewhere, choose Persisted query handoff. Persisted Query should become a one-line body with comments, optional commas, and extra whitespace removed. Check Payload Footprint before copying it so the compact byte count is based on syntax with no active warnings.

Clean up schema SDL for a pull request

A snippet such as type Query { order(id: ID!): Order } should use Schema SDL cleanup or Document role set to Schema SDL document. Definition Inventory should show schema definition rows, and Role fit should stay clear as long as operation definitions are not mixed into the schema-only file.

Fix an unclosed string before handoff

If a value starts with " and never closes, the warning alert should report an unclosed string with a line and column, the summary should show Syntax Needs Review, and Persisted Query should remain unavailable. Fix the string first, then check Bracket structure and Schema-aware validation again before using the output.

FAQ:

Does formatted GraphQL mean the query is valid for my API?

No. Formatting checks token structure and bracket balance. Your API schema still needs to validate field names, arguments, variable types, directives, fragments, and operation rules.

Why were my comments removed from the compact output?

Persisted Query always strips comments because comments do not affect executable GraphQL behavior. Keep comments applies to Formatted Document only.

Why did the role warning appear?

The selected Document role did not match the detected definitions. For example, an operation-only role warns when schema SDL such as type or directive definitions are present.

What file types can I load?

The file picker accepts GraphQL, GQL, and plain text files. The selected file is read into the editor so the same formatting, inventory, footprint, and audit checks can run.

Why is the persisted-query result unavailable?

A tokenization or bracket problem blocks the compact output. Fix the warning message first, then check that Bracket structure is Balanced in Formatter Audit.

Does my GraphQL text leave the browser?

The formatting pass, local file reading, definition inventory, payload comparison, and audit report are generated in the browser from the current text. Be careful with secrets if you copy or download any result.

Glossary:

Operation: A GraphQL query, mutation, or subscription that can be sent to a GraphQL service.
Fragment: A reusable selection set that can be included by operations or other fragments.
Schema SDL: GraphQL schema definition language, the text form used to describe types, fields, arguments, and directives.
Selection set: The fields inside braces that describe which data an operation or fragment should return.
Directive: An annotation beginning with @ that can affect execution, validation, schema behavior, or tooling depending on where it is allowed.
Persisted query: A compact operation body commonly prepared for systems that store or identify queries separately from variable values.
Definition Inventory: The result table that lists detected operation, fragment, and schema-definition starts with review signals.
Bracket structure: The balance of braces, parentheses, and square brackets in the GraphQL text.

References:

GraphQL Specification, October 2021 Edition, The GraphQL Foundation, October 2021.
Queries, GraphQL documentation.
Schemas and Types, GraphQL documentation.
Validation, GraphQL documentation.