graphql-schema-linter: schema rules on the command line and in CI

A linter for the schema, not for the queries

graphql-schema-linter is a command line tool for validating GraphQL schema definitions against a set of rules, and the first thing the README does is draw a boundary. It lints the schema, the SDL document that describes your types, and if what you want is to lint GraphQL queries, it points you at the apollographql ESLint plugin instead. That distinction is the whole design of the tool. A schema is a contract that changes slowly and is read by many people, so a rule that says every type must carry a description, or that enum values must be sorted, is cheap to enforce and expensive to notice by eye. The audience is backend and platform engineers who want those conventions checked mechanically rather than during review, and the tool ships as both a CLI and a package. The repository is MIT licensed, with the LICENSE.txt file at the root and the package metadata agreeing.

Installing locally or globally, with graphql as a peer dependency

The install section states that the tool depends on graphql as a peer dependency, which is the detail that matters for anyone deploying it. You can add it to an existing project that already uses the graphql package:

# Using yarn
yarn add graphql-schema-linter

# Using npm
npm install --save graphql-schema-linter

Or you can install it globally alongside graphql itself:

# Using yarn
yarn global add graphql-schema-linter graphql

# Using npm
npm install -g graphql-schema-linter graphql

The peer dependency is declared as graphql ^15.0.0 || ^16.0.0, which is a hard boundary rather than a preference. A project on graphql 17 does not satisfy that range, and the tool was published when 16 was current. The repository also carries a renovate.json for dependency updates, a CHANGELOG.md, and a Travis configuration, and the top-level entries are the usual small set: src, test, a yarn.lock and the readme.

The rule set is chosen on the command line or in a config file

The command line is where the tool is at its simplest, taking one or more schema files as positional arguments. The option list in the README is worth reading closely because it shows the shape of the tool. The rules option selects which rules are used, and the example given is --rules fields-have-descriptions,types-have-descriptions. The rules-options option passes configuration to individual rules, with the example setting a sortOrder of lexicographical for enum-values-sorted-alphabetically. The ignore option silences errors for specific schema members, with the example listing type names and field paths such as Query.obvious. The format option chooses between compact, json and text output, which is what makes the tool usable both for a human reading a terminal and for a CI job parsing results. There is also a stdin mode, a config-directory path, custom rule paths, and two flags for legacy SDL syntax.

Inline lint-disable comments for the exceptions you need

The feature that keeps this tool usable on a real schema is inline rule overrides, and the README devotes a section to it. The premise is that a rule is often right for the schema as a whole and wrong for one specific part, and disabling it everywhere is a blunt instrument. Four inline configurations are supported, written as comments in the schema itself. lint-disable and lint-enable switch rules off and on from that point to the end of the file or until the opposite directive appears, while lint-disable-line and lint-enable-line apply to a single line. The example shows a block of rules disabled around a Query type and re-enabled afterwards, and a single field exempted with a trailing lint-disable-line comment. The ignore option is the CLI counterpart for the same problem, but the inline form travels with the schema, which is why it survives code review and pull requests.

Configuration lives in package.json, an rc file or a JS config

Beyond the command line, the tool can be configured through one of three configuration files, and the README is explicit that only four keys can be set this way: rules, schemaPaths, customRulePaths and rulesOptions, with the note that more options may be added in the future. In package.json the settings sit under a graphql-schema-linter key, and the same four keys appear in a.graphql-schema-linterrc file and in a graphql-schema-linter.config.js file that exports an object. The tool uses cosmiconfig, which is in the dependency list, and that is what lets the same configuration work in all three places. Note the difference between the two schema-related options: schemaPaths is the list of files to lint, while customRulePaths is the list of files to load extra rules from, and the latter is a plain glob such as path/to/my/custom/rules/*.js. The rules option acts as an allow list: only the rules specified will be used to validate the schema.

Custom rules and the pre-commit hook wiring

The custom-rule-paths option loads additional rules from disk, which means a project can enforce its own conventions alongside the built-in ones, and the README points at a customRulePaths entry of path/to/my/custom/rules/*.js in every configuration example. One way to run it is in a pre-commit hook, and the README builds this on lint-staged and husky, which are listed in the devDependencies. The shape of the wiring is a precommit script in package.json plus a lint-staged key mapping a glob to the linter, for example mapping *.graphql to graphql-schema-linter path/to/*.graphql. The README is careful about a real trap here. If a project has both query files and schema files, you need separate entries, one running ESLint for the client queries and one running the schema linter for the server files. And if you have several schemas in one folder, a wildcard entry is wrong, because the linter would assume they are all parts of one schema, so the configuration has to name each schema file explicitly.

A 2022 release line, with commits still landing

The maintenance picture needs stating precisely. The most recent published releases are v3.0.0 on 2022-05-06, v3.0.1 on 2022-05-22 and v2.0.2 on 2022-05-05, so the npm artefact is four years old as of this writing. The last push to the repository was on 2026-10-13, which means work is still landing on master even though nothing new has been published to the registry under that name, and the repository version field in package.json still reads 3.0.1. The practical consequence is that a project pinning graphql-schema-linter from npm is pinning a 2022 build, and the recent activity may or may not be reflected there. The peer dependency range of graphql ^15.0.0 || ^16.0.0 is the sharper edge, since it is what the published package will accept. The test scripts in the package metadata show the same constraint being worked around in CI, with separate runs against graphql 15 and graphql 16.

Editorial conclusion

graphql-schema-linter fits a team with a GraphQL schema that has conventions worth enforcing, such as documented types and fields, sorted enum values or naming rules, and that wants those checks in a pre-commit hook or a CI job. It does not fit a team on graphql 17, since the declared peer dependency range stops at graphql 16, and it does not replace a query linter, since the README points at the apollographql ESLint plugin for that. Before adopting it, check your graphql major version against the peer range, decide whether the rules run in a hook or in CI, and pin the version you tested, since the most recent published release dates from 2022.

Frequently asked questions

Official sources

1. cjoudrey/graphql-schema-linter on GitHub
2. Issues
3. License: MIT
4. README
5. Releases