Lint GraphQL with Redocly CLI

In addition to providing lint functionality for multiple OpenAPI formats, Redocly CLI also supports GraphQL. Redocly CLI supports the following linting approaches with GraphQL documents:

• GraphQL SDL syntax and schema validation
• built-in rules for checking common standards requirements (see the list of GraphQL rules)
• configurable rules for building rules following common patterns

Redocly CLI takes its settings from a redocly.yaml configuration file. The following is an example of a simple configuration file that checks if a GraphQL SDL file is well-formed and has a valid structure:

rules:
  struct: error

The struct rule reports an error if the SDL contains a syntax error or if the schema is structurally invalid (for example, a field that references a type that isn't defined).

With this configuration file, and your GraphQL schema file, run the linting command:

redocly lint schema.graphql

The output describes structural problems with the document, or reports that it is valid.

The supported rules are:

• struct: Ensures that the GraphQL SDL is well-formed and that the schema is structurally valid.
• no-unused-types: Every declared type must be referenced by another type or directive, or serve as a root operation type. Root types are the ones named in the schema definition or its extensions; when there is no schema definition, types named Query, Mutation, or Subscription are the roots. Types that are declared but never referenced are reported. If the document has no root operation type, this rule reports nothing.
• type-description: Every type definition (object, interface, enum, input object, union, and scalar) must have a non-empty description.

We expect the list to expand over time, so keep checking back - and let us know if you have any requests by opening an issue on the GitHub repo.

The rules are available in our predefined rulesets. To tweak a rule's severity, configure it in your redocly.yaml file, for example:

rules:
  type-description: error

Redocly CLI also offers configurable rules that enable you to set assertions about the document being linted. This functionality works for GraphQL too. Instead of OpenAPI node types, the subject.type targets GraphQL AST node kinds, such as ObjectTypeDefinition, FieldDefinition, EnumTypeDefinition, or ScalarTypeDefinition.

The following example shows a configurable rule that displays a warning when an object type name is not in PascalCase:

rules:
  rule/graphql-type-casing:
    subject:
      type: ObjectTypeDefinition
    assertions:
      casing: PascalCase
    severity: warn

With the extensive configurable rules options available, there are many opportunities to make sure that your GraphQL schema conforms with expectations. We'd also love to see what you're building - it helps us know how things are going!