graphql-schema-linter

graphql-schema-linter

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.

Install

Yarn:

yarn global add graphql-schema-linter

npm:

npm install -g graphql-schema-linter

Usage

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

Usage with pre-commit Hooks

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"],
  }
}

Configuration file

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.

In package.json

{
  "graphql-schema-linter": {
    "rules": ["enum-values-sorted-alphabetically"]
  }
}

In .graphql-schema-linterrc

{
  "rules": ["enum-values-sorted-alphabetically"]
}

In graphql-schema-linter.config.js

module.exports = {
  rules: ['enum-values-sorted-alphabetically'],
};

Built-in rules

defined-types-are-used

This rule will validate that all defined types are used at least once in the schema.

deprecations-have-a-reason

This rule will validate that all deprecations have a reason.

enum-values-all-caps

This rule will validate that all enum values are capitalized.

enum-values-sorted-alphabetically

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

fields-have-descriptions

This rule will validate that all fields have a description.

types-are-capitalized

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

types-have-descriptions

This will will validate that interface types, object types, union types, scalar types, enum types and input types have descriptions.

Output formatters

The format of the output can be controlled via the --format option.

The following formatters are currently available: text, json.

TextFormatter (default)

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.

JSONFormatter

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"
      }
    }
  ]
}

Exit codes

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.

Changelog

0.0.19 (November 25th, 2017)

New features

• The types-have-descriptions rule now validates that union types have a description. #56
• The types-have-descriptions rule now validates that input types have a description. #57
• The types-have-descriptions rule now validates that scalar types have a description. #60
• The types-have-descriptions rule now validates that enum types have a description. #61
• GraphQL syntax errors will now be reported like other errors instead of crashing. #59

Bug fixes

• Fix a crash that occured when a .graphql file had no line breaks. #58