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 path/to/*.graphql"]
  }
}

The above configuration assumes that you have either one schema.graphql file or multiple .graphql files that should be concatenated together and linted as a whole.

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 client/*.graphql"],
    "server/*.graphql": ["graphql-schema-linter server/*.graphql"]
  }
}

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 have a description.

This rule will validate that all enum values are sorted alphabetically.

This rule will validate that object type field and interface type field names are camel cased.

This rule will validate that object type fields and interface type fields have a description.

This rule will validate that input object value names are camel cased.

This rule will validate that input object values have a description.

This rule will validate that interface types and object types have capitalized names.

This will will validate that interface types, object types, union types, scalar types, enum types and input 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.  types-have-descriptions
6:3 The field `QueryRoot.a` is missing a description.      fields-have-descriptions

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"
      },
      "rule": "types-have-descriptions"
    },
    {
      "message": "The field `QueryRoot.a` is missing a description.",
      "location": {
        "line": 6,
        "column": 3,
        "file": "schema.graphql"
      },
      "rule": "fields-have-descriptions"
    }
  ]
}

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 invalid configuration was provided. Information about this can be obtained by reading the stderr.

If the process exits with 3 it means an uncaught error happened. This most likely means you found a bug.