graphql-schema-linter: Lint a GraphQL Schema
graphql-schema-linter validates a GraphQL SDL schema against configurable rules such as requiring descriptions and consistent naming, exiting non-zero on errors.
A schema linter enforces conventions (types described, enums uppercased, input names) so a large GraphQL API stays consistent. It complements diff/validate, which check compatibility rather than style.
What it does
The CLI loads one or more .graphql schema files, runs the enabled rules, and prints violations grouped by rule. Rules and config come from .graphql-schema-linterrc, package.json, or flags. It exits non-zero when errors are found.
Common usage
graphql-schema-linter schema.graphql
# choose specific rules and JSON output for CI
graphql-schema-linter --rules types-have-descriptions,enum-values-all-caps \
--format json "schema/**/*.graphql"Options
| Flag | What it does |
|---|---|
| --rules <list> | Comma-separated rules to enable |
| --only <list> | Run only these rules |
| --except <list> | Run all rules except these |
| -f, --format <text|json|compact> | Output format |
| -c, --config-directory <dir> | Where to look for config |
| --custom-rule-paths <glob> | Load custom rule modules |
In CI
Commit a .graphql-schema-linterrc and run the linter as a required check so new schema files follow the same conventions. Use --format json if a bot posts findings to the PR. Keep it separate from the breaking-change check; they catch different problems.
Common errors in CI
Output ends with a summary like 2 errors detected and a non-zero exit. Each line names the rule, e.g. The object type User is missing a description. (types-have-descriptions). "Invalid rule ..." means a typo in --rules. "Cannot find module" for a custom rule means a bad --custom-rule-paths. A parse error such as Syntax Error: Expected Name, found ... means invalid SDL.