GraphQL Formatter: Check Input, Mode, and Indentation Behavior

What GraphQL Formatter currently returns

GraphQL Formatter accepts GraphQL query or schema text and exposes choices for mode and indentation. Its useful behavior to examine is the distinction between blank and nonblank input: a blank or whitespace-only value completes with empty formatted text, whereas ordinary text does not produce formatted output. This guide therefore helps you check what the controls and returned values mean before treating the tool as a document formatter. It also covers alternate input names, accepted value types, the size condition, and the difference between a successful empty-input response and a failed nonblank request. A blank submission can confirm how the empty-input path reports its values, but it cannot show the appearance of a formatted query or schema.

Steps to check input, mode, and indentation

1. Prepare the query or schema as a string. The primary input begins empty. When that value is falsey, a truthy string supplied through the legacy graphql name or the gql_input name can be selected instead. After selection, a non-string value fails rather than producing formatted text.

2. Choose the mode you want to check. For nonblank text, the default is beautify, and the value is lowercased. Only minify selects the minification path; another value follows the beautification path. A truthy non-string mode can fail while it is being lowercased.

3. Set indentation for a nonblank request. The default is 2 spaces per level. A supplied value is converted to an integer when possible. Negative values, values above 8, and values that cannot be converted fall back to 2.

4. Submit the value and separate the two outcomes. Blank or whitespace-only text completes with empty formatted text. A nonblank string that passes the type and size checks still fails during result processing, so changing the mode or indentation does not create formatted output.

5. Check the size condition for a large document. Nonblank text whose UTF-8 encoding exceeds 1,000,000 bytes fails instead of being formatted. With blank text, normalization is bypassed: the returned mode and indentation remain as supplied, and both reported sizes are 0.

How to interpret the returned outcome

An empty formatted-text value means that the blank-input path completed; it is not a representation of a GraphQL document. The same response reports zero for both sizes and keeps the supplied mode and indentation instead of applying the conversions used for nonblank text. This lets you distinguish a blank submission from a document that was processed successfully.

A nonblank failure can occur because the selected value is not a string, because its UTF-8 size exceeds 1,000,000 bytes, or because ordinary string processing fails after the earlier checks. A string below the size threshold can therefore still end without formatted text. The mode and indentation choices do not change that outcome.

The minification path is described as removing hash-prefixed comment-like text, collapsing whitespace, and removing surrounding spaces around braces, parentheses, colons, and commas. Spaces around square brackets are not removed. Since nonblank processing fails before text is returned, those transformations are not available as a successful output to inspect.

Worked example

A developer submits a whitespace-only value to check the blank-input path before investigating why a nonblank GraphQL query produces no formatted text.

Submit a whitespace-only string while leaving the mode and indentation controls at their defaults, then inspect the empty text and the two reported size values.

The returned result has empty formatted text, reports 0 for both sizes, and preserves the supplied mode and indentation values.

Limitations

• Nonblank requests do not return formatted text, so the described beautification and minification transformations cannot be inspected through a successful response.

Common errors

• Sending a non-string after alias selection. A falsey primary value can make a truthy alias take precedence, after which the selected value is checked as the input. Send the query or schema as a string and inspect the graphql and gql_input values when an unexpected type is supplied.

FAQ

Can I format a GraphQL query with this tool?

Yes, but only as an empty result: blank or whitespace-only input succeeds with empty formatted text. Nonblank input does not return formatted text under the reviewed implementation.

Which mode should I use for GraphQL formatting?

For nonblank text, choose minify to select the minification path; another mode value follows the beautification path. Both paths fail during processing for ordinary nonblank strings.

What input type does GraphQL Formatter accept?

The query or schema should be supplied as a string. If the primary value is falsey, a truthy value from graphql or gql_input can be selected first, and a non-string selected value then fails.