GraphQL Formatter

GraphQL source often moves through several hands before it reaches a service: a pull request, an API console, a client file, an operation registry, or a schema review. A document can be easy for a machine to tokenize and still be hard for a person to review when nested fields, variables, directives, and fragments have been squeezed into one line.

Readable formatting gives that source a shape again. Indentation makes parent and child selections visible, line breaks show where definitions begin and end, and comments can stay beside the query or schema part they explain. Compact formatting has a different job. It removes spacing that GraphQL ignores so a named operation can be stored, compared, or sent as a smaller payload after it has already been checked in the right environment.

GraphQL gives whitespace, line breaks, comments, and commas very little semantic weight. A formatter can change many of those characters while keeping the same names, strings, numbers, variables, directives, and punctuators in order. That does not make formatting a substitute for validation. A tidy query can still request a field that the target schema does not have, use a fragment on the wrong type, pass the wrong variable shape, or depend on a directive the service does not support.

Separate readability from correctness. Formatting helps people review the text, compare payload size, and notice structural mistakes such as unclosed strings or brackets. The final verdict for an operation still comes from the GraphQL service, client compiler, or schema-aware validator that knows the actual type system.

How to Use This Tool:

Start with the intended handoff, then check the warning state before copying the readable or compact result.

1. Choose Formatting profile. Use Review workspace for readable inspection, Persisted query handoff when you need compact executable text, Schema SDL cleanup for type definitions, or Custom after changing the visible settings yourself.
2. Paste the GraphQL text into GraphQL document, drop a supported file onto the editor, use Browse GraphQL, or load Sample. The file picker accepts .graphql, .gql, and .txt files under 1 MB.
3. Set Document role when the source has a known purpose. Auto detect works for normal pasted snippets, while the operation, schema, and mixed roles add warnings when the detected definitions do not match the intended use.
4. Pick Indent width from 1 to 8 spaces. Two spaces is a common GraphQL default; four spaces may match repositories that use wider indentation.
5. Open Advanced when comments or the trailing newline matter. Keep comments applies to the readable Formatted Document; Persisted Query removes comments regardless of that switch. Final newline is useful for saved files and can be turned off for exact clipboard text.
6. Read the summary and warning alert. Syntax Needs Review, an unclosed string message, an unexpected character, or an unmatched bracket means the compact payload should wait until the source is fixed.
7. Use Formatted Document for readable review, Persisted Query for compact text, Payload Footprint for byte and line comparison, Definition Inventory for detected definitions, Formatter Audit for status checks, and JSON when you need a structured report of the current run.

Interpreting Results:

Trust the warning state before trusting the output. GraphQL Formatted Locally, Persisted Query Ready, or Schema SDL Formatted means the browser pass could read the text, balance brackets, and produce the selected artifacts. Formatted with Caveats means output exists, but role mismatch, operation naming, or size warnings need review.

Formatter Audit is the strongest final local check. Bracket structure should be Balanced before a compact body is copied. Role fit should match the handoff. Operation naming matters when more than one executable operation appears or when persisted-query systems, tracing, caching, or registries expect stable names.

Technical Details:

A GraphQL document is read as source text made of lexical tokens and ignored characters. Names, numbers, strings, block strings, punctuators, and spread markers carry the structure. Spaces, line terminators, comments, and commas mainly separate tokens and improve readability. A formatter can move line breaks and indentation when the significant token order stays the same.

The hard boundary is the schema. Syntax answers whether the document can be read as GraphQL-shaped text. Validation answers whether the document is meaningful for a particular type system, including field existence, argument names, fragment type conditions, variable usage, directive locations, and required input values. A local formatting pass can catch structure problems, but it cannot prove server acceptance without the schema.

Transformation Core:

Rule Core:

Mechanism Walkthrough:

A compact operation such as query GetOrder($id:ID!){order(id:$id){id status}} is tokenized into the operation keyword, operation name, variable marker, names, punctuation, and selection-set braces. The readable output adds line breaks after structural braces and indents id and status under order. The compact output keeps the same semantic tokens and removes spacing that is not needed between them.

The same pass handles comments differently by output purpose. A review copy can keep # comments so teammates see context beside the query or SDL. A persisted-query body strips comments because GraphQL comments are ignored during execution and should not be part of a compact handoff payload.

Formula Core:

Payload comparison uses UTF-8 byte counts rather than visible character counts, so non-ASCII text inside strings or comments is measured by transport size.

The formatter is deterministic for the current text and settings. It is best understood as a local formatting, footprint, and structural-review pass, not a complete GraphQL parser, query planner, or schema validator.

Privacy Notes:

Pasted GraphQL text and selected files are processed in the browser for formatting, inventory, payload comparison, audit rows, and JSON output. Avoid including secrets, bearer tokens, customer identifiers, or production-only examples in text that you plan to copy, download, or share.

Worked Examples:

Review a query before an API-console test

A paste containing query GetOrder($id: ID!) with a nested order selection works well with Review workspace and Auto detect. Formatted Document should show the nested fields on separate indented lines, and Definition Inventory should include the named operation with variable and selection-block signals.

Prepare a persisted-query body

A named operation that has already passed schema validation can use Persisted query handoff. Persisted Query should become a one-line body with comments and optional commas removed. Before copying it, check Formatter Audit for Bracket structure set to Balanced and Operation naming set to Ready.

Clean up schema SDL for a pull request

A schema 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 report schema definition rows, while Role fit warns if an executable query or fragment is accidentally mixed into the SDL file.

Fix an unclosed string before handoff

If a string starts with " and never closes, the warning alert should name the unclosed string location, the summary should show Syntax Needs Review, and Persisted Query should remain unavailable. Close the string first, then return to Formatter Audit before using the compact output.

FAQ:

Glossary:

Operation

A GraphQL query, mutation, or subscription that can be executed by a GraphQL service.

Selection set

The fields inside braces that describe the data requested from a parent field or operation.

Fragment

A reusable selection set that can be included in operations or other fragments.

Directive

An annotation beginning with @ that can affect execution, validation, schema behavior, or tooling depending on where it appears.

Schema SDL

GraphQL schema definition language, the text form used to describe types, fields, arguments, directives, and root operation types.

Persisted query

A compact executable operation commonly stored or identified separately from the variables sent with a request.

Schema-aware validation

A check that compares an operation with the target GraphQL type system, including fields, variables, fragments, and directives.

References:

• GraphQL Specification, September 2025 Edition, The GraphQL Foundation, September 2025.
• Queries, GraphQL documentation.
• Schemas and Types, GraphQL documentation.
• Validation, GraphQL documentation.