GraphQL documents

A file with the .graphql, .graphqls or .gql extension is formatted as a GraphQL document, a schema (type system definitions) or operations, with the graphql section of commands.format. The layout is that of Prettier: a file formatted by Prettier with the same line width and indentation is left unchanged, and nothing is sorted unless sort says so.

Layout

The formatter:

• writes selection sets, fields, enum values and input fields one per line
• keeps argument lists, variable definitions, directives, list and object values, implements lists and union members on one line if they fit in the line width, and puts one item per line otherwise
• keeps single blank lines between definitions and between members; several blank lines become one, and no blank lines are added
• writes block strings (""") on lines of their own, and trims the spaces around the text of a single line block string
• keeps shorthand queries ({ ... }) and the query keyword as written
• optionally sorts definitions and the members of types

No comment is lost. Comments stay before or after the node they are written next to, and move with it when it is sorted. A node with a # prettier-ignore comment before it is written as it is in the source.

Documents that are syntactically correct but break validation rules, for example with fields of unknown types, are formatted. Files with syntax errors are reported with the position of each error and left untouched.

Differences from Prettier

The output differs from that of Prettier in a few cases, where Prettier loses comments or writes documents that cannot be read back:

• control characters in quoted strings, other than tabs, are written as escapes ("\r", "\u0001") instead of as they are
• two comments after nodes that end on the same line are written on two lines; Prettier writes them on one line, which makes the second one part of the first
• a comment on its own line between a description and a definition, or after the last variable or argument before ), stays there; Prettier moves it into the middle of a line, and moves it again on the next run

Like Prettier, the formatter drops a blank line that follows a comment at the end of a member, and attaches comments written in the middle of a definition, such as between a field name and its type, to the nearest node, from where they can move again on the next run.

Settings

Key	Values	Recommended	Description
indent	1 to 8	2	Number of spaces for one level of nesting.
line_width	20 to 1000	80	Line length that groups must fit in to stay on one line. East Asian wide characters count as two columns.
sort.definitions	original, grouped, sorted	original	grouped puts definitions in this order: schema, directives, scalars, enums, interfaces, object types, input types, unions, operations, fragments. sorted also sorts them by name within their groups, with extensions after the definitions they extend.
sort.fields	original, sorted	original	Sorts the fields of object types, interfaces and input types, and of their extensions, by name.
sort.enum_values	original, sorted	original	Sorts enum values by name.
sort.arguments	original, sorted	original	Sorts the argument definitions of fields and directives by name.
sort.union_members	original, sorted	original	Sorts the member types of unions by name.
sort.interfaces	original, sorted	original	Sorts the interfaces that types implement by name.

Without a configuration file, the recommended settings are used. Neither the recommended nor the original configuration sorts anything, because the order of definitions and fields shows in introspection results, generated code and documentation. Selections, arguments and variables of operations are never sorted, as selections define the order of the response.

Example - 4-space indentation, a line width of 100 characters, and definitions and fields sorted by name

commands:
  format:
    extends:
      - recommended
    graphql:
      indent: 4
      line_width: 100
      sort:
        definitions: sorted
        fields: sorted

apigenie format schema/*.graphql --config api-style-guide.yaml