Join us for GraphQL Summit, October 10-12 in San Diego. Use promo code ODYSSEY for $400 off your pass.
Launch GraphOS Studio

Schema linting

With GraphOS

provides schema linting to help you enforce formatting conventions and other GraphQL best practices with every proposed change to your graph's .

Linter violations in GraphOS Studio
  • If you set up schema checks for your graph, linting runs as a separate check type alongside build and checks.
  • You can also perform one-off linting with the Rover CLI.

Note: Currently, linting only analyzes parts of your modified that differ from your published . It does not flag any existing violations.

Configuring the linter

The linter uses a predefined collection of rules to identify issues with proposed changes. The predefined collection includes schema composition rules.

  • Currently, you can define graph-wide linter defaults that apply to all s of a particular graph.
  • In a future release, you'll also be able to configure how individual s of your graph treat violations of each linter rule.

Navigate to your linter's configuration:

  1. In GraphOS Studio, go to your graph's Checks page.

  2. Click Configuration in the upper right to open the checks configuration page.

  3. From the checks configuration page, open the Linter section:

    Linter configuration page in GraphOS Studio
  4. To configure graph-wide linter defaults for all of your s, click the This Graph tab.

    • In a future release, you'll be able to configure -specific behavior from the This Variant tab.

This page organizes linter options into the following categories:

  • General Linter Configuration provides high-level options, including disabling the linter entirely.
  • Approved @tag names enables you to specify approved values for the name of the @tag . This directive is used most commonly with GraphOS contracts.
    • If you don't use the @tag , you can ignore this category.
    • Using a non-approved value for name raises the TAG_DIRECTIVE_USES_UNKNOWN_NAME violation.
  • Linter Rules enables you to set the severity level for violations of each rule.

If you're viewing configuration for a single , each category displays a Use Graph Settings toggle in the upper right. If this toggle is enabled, the uses whatever graph-wide defaults are set for that category.

⚠️ At this time, the Use Graph Settings toggle is always enabled for all s.

Setting severity levels

The Linter Rules category of your linter configuration displays all predefined rules and the current severity level for each:

Linter configuration page in GraphOS Studio

Click a rule's severity to set it to any of the following:

  • Error. Any violation of this rule causes the associated linter check to fail.
    • This in turn causes the entire schema checks run to fail, which is useful for failing builds in CI.
  • Warn. Violations of this rule are flagged in checks reports, but they don't cause the associated linter check to fail.
  • Ignore. Violations of this rule are ignored entirely.

Running the linter

linting runs automatically as part of your graph's schema checks. You can also perform one-off linting of local changes via the CLI.

Linting via schema checks

If you set up schema checks for your graph, linting automatically runs as a separate check type alongside build and checks. You can view the results of all check types from your graph's Checks page in Studio:

Checks page in Studio showing all check types

For the best experience running linter checks, install v0.16 or later of the Rover CLI. Earlier versions of can't correctly output the results of linter checks (but they do correctly exit with a nonzero code if a linter check fails).

One-off linting

⚠️ One-off linting requires v0.16 or later of the Rover CLI. Install the latest version.

The CLI provides subgraph lint and graph lint commands for running the linter against your local changes.

  • Use subgraph lint for s in a .
  • Use graph lint for monographs (not recommended).

⚠️ The rover subgraph lint and rover graph lint commands validate all linter rules except for composition rules. Use rover subgraph check or rover supergraph compose to validate composition rules locally.

Example command
rover subgraph lint --name products --schema ./products-schema.graphql my-graph@my-variant

The my-graph@my-variant in the example above is a graph ref that specifies the ID of the graph you're comparing your changes against, along with which variant you're comparing against.

Command options include:


Required. The path to a local .graphql or .gql file, in SDL format.

Alternatively, you can provide -, in which case the command uses an string piped to stdin instead (see Using stdin).


Required for subgraph lint. Omit for graph lint. The name of the published to compare changes against.


If provided, the linter only flags violations that are present in the diff between your local and your published schema.

By default, one-off linting flags all violations in your local .

Linter rules

See this reference list of rules.

Configuring schema checks
Linter rules
Edit on GitHubEditForumsDiscord