Schema Linting
Enforce GraphQL formatting conventions and best practices
GraphOS provides schema linting to help you enforce formatting conventions and other GraphQL best practices with every proposed change to your graph's schema.
- If you set up schema checks for your graph, linting runs as a separate check type alongside build and operation checks.
- You can also perform one-off linting with the Rover CLI.
ⓘ NOTE
GraphOS schema linting only analyzes parts of your modified schema that differ from your published schema. It does not flag any existing violations.
Linter configuration
The GraphOS schema linter uses a predefined collection of rules to identify issues with proposed schema changes. The predefined collection includes schema composition rules. The graph-wide linter defaults you define apply to all variants of a particular graph.
To navigate to your linter configuration:
- In GraphOS Studio, go to your graph's Checks page.
- Click Configuration in the upper right to open the checks configuration page.
- From the checks configuration page, open the Linter section.
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 thename
argument of the@tag
directive. This directive is used most commonly with GraphOS contracts.- If you don't use the
@tag
directive, you can ignore this category. - Using a non-approved value for
name
raises theTAG_DIRECTIVE_USES_UNKNOWN_NAME
violation.
- If you don't use the
- Rule Severity Configuration enables you to set the severity level for violations of each rule.
If you view this configuration for a single variant, each category displays a Use Graph Settings toggle in the upper right. If this toggle is enabled, the variant uses whatever graph-wide defaults are set for that category. At this time, the Use Graph Settings toggle is always enabled for all variants.
Setting severity levels
The Rules Severity Configuration category of your linter configuration displays all predefined rules and the current severity level for each. 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.
For information on specific rules, see the reference list of rules.
Running the linter
Schema linting runs automatically as part of your graph's schema checks. You can also perform one-off linting of local schema changes via the Rover CLI.
Linting via schema checks
If you set up schema checks for your graph, schema linting automatically runs as a separate check type alongside build and operation checks. You can view the results of all check types from your graph's Checks page in Studio. For example, the screenshot below shows successful build and operations checks with a failed linting check.
💡 TIP
For the best experience running linter checks, install v0.16 or later of the Rover CLI. Earlier versions of Rover 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
ⓘ NOTE
One-off linting requires v0.16 or later of the Rover CLI. Install the latest version.
The Rover CLI provides subgraph lint
and graph lint
commands for running the GraphOS linter against your local schema changes.
- Use
subgraph lint
for subgraphs in a supergraph. - 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.
rover subgraph lint --name products --schema ./products-schema.graphql my-graph@my-variant
The argument my-graph@my-variant
in the example above is a graph ref that specifies the ID of the graph you're comparing your schema changes against, along with which variant you're comparing against.
Command options include:
Name | Description |
---|---|
| Required. The path to a local Alternatively, you can provide |
| Required for |
| If provided, the linter only flags violations that are present in the diff between your local schema and your published schema. By default, one-off linting flags all violations in your local schema. |
Linter rules
See this reference list of rules.