This package provides a command line tool to validate GraphQL schema definitions against a set of rules.
If you're looking to lint your GraphQL queries, check out this ESLint plugin: apollographql/eslint-plugin-graphql.
Yarn:
yarn global add graphql-schema-linter
npm:
npm install -g graphql-schema-linter
Usage: graphql-schema-linter [options] [schema.graphql ...]
Options:
-r, --rules <rules>
only the rules specified will be used to validate the schema
example: --rules fields-have-descriptions,types-have-descriptions
-f, --format <format>
choose the output format of the report
possible values: json, text
-s, --stdin
schema definition will be read from STDIN instead of specified file
--version
output the version number
-h, --help
output usage information
Using lint-staged and husky, you can lint your staged GraphQL schema file before you commit. First, install these packages:
yarn add --dev lint-staged husky
Then add a precommit
script and a lint-staged
key to your package.json
like so:
{
"scripts": {
"precommit": "lint-staged"
},
"lint-staged": {
"*.graphql": ["graphql-schema-linter"]
}
}
The above configuration assumes that you have either one schema.graphql
file or multiple files that should be linted
concatenated together. If you have both client and server schema in the same project, you'll likely need to put
multiple entries in the lint-staged
object above - one for client and one for server. Something like:
{
"scripts": {
"precommit": "lint-staged"
},
"lint-staged": {
"client/*.graphql": ["graphql-schema-linter"],
"server/*.graphql": ["graphql-schema-linter"],
}
}
In addition to being able to configure graphql-schema-linter
via command line options, it can also be configured via
one of the following configuration files.
For now, only rules
can be configured in a configuration file, but more options may be added in the future.
{
"graphql-schema-linter": {
"rules": ["enum-values-sorted-alphabetically"]
}
}
{
"rules": ["enum-values-sorted-alphabetically"]
}
module.exports = {
rules: ['enum-values-sorted-alphabetically'],
};
This rule will validate that all defined types are used at least once in the schema.
This rule will validate that all deprecations have a reason.
This rule will validate that all enum values are capitalized.
This rule will validate that all enum values are sorted alphabetically.
This rule will validate that all fields have a description.
This rule will validate that interface types and object types have capitalized names.
This will will validate that interface types and object types have descriptions.
The format of the output can be controlled via the --format
option.
The following formatters are currently available: text
, json
.
Sample output:
5:1 The object type `QueryRoot` is missing a description.
6:3 The field `QueryRoot.a` is missing a description.
2 errors detected
Each error is prefixed with the line number and column the error occurred on.
Sample output:
{
"errors": [
{
"message": "The object type `QueryRoot` is missing a description.",
"location": {
"line": 5,
"column": 1,
"file": "schema.graphql"
}
},
{
"message": "The field `QueryRoot.a` is missing a description.",
"location": {
"line": 6,
"column": 3,
"file": "schema.graphql"
}
}
]
}
Verifying the exit code of the graphql-schema-lint
process is a good way of programmatically knowing the
result of the validation.
If the process exits with 0
it means all rules passed.
If the process exits with 1
it means one or many rules failed. Information about these failures can be obtained by
reading the stdout
and using the appropriate output formatter.
If the process exits with 2
it means an uncaught error happen. This most likely means you found a bug.