Need help with graphql-schema-linter?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

cjoudrey
481 Stars 52 Forks MIT License 467 Commits 48 Opened issues

Description

Validate GraphQL schema definitions against a set of rules

Services available

!
?

Need anything else?

Contributors list

graphql-schema-linter Travis CI npm version

This package provides a command line tool to validate GraphQL schema definitions against a set of rules.

Screenshot

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

only the rules specified will be used to validate the schema

example: --rules fields-have-descriptions,types-have-descriptions

-o, --rules-options

configure the specified rules with the passed in configuration options

example: --rules-options '{"enum-values-sorted-alphabetically":{"sortOrder":"lexicographical"}}'

-i, --ignore

ignore errors for specific schema members (see "Inline rule overrides" for an alternative way to do this)

example: --ignore '{"fields-have-descriptions":["Obvious","Query.obvious","Query.something.obvious"]}'

-f, --format

choose the output format of the report

possible values: compact, json, text

-s, --stdin

schema definition will be read from STDIN instead of specified file

-c, --config-directory

path to begin searching for config files

-p, --custom-rule-paths

path to additional custom rules to be loaded. Example: rules/*.js

--comment-descriptions

use old way of defining descriptions in GraphQL SDL

--old-implements-syntax

use old way of defining implemented interfaces in GraphQL SDL

--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 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 your project has

.graphql
query files and
.graphql
schema files, you'll likely need multiple entries in the
lint-staged
object - one for queries and one for schema. For example:
{
  "scripts": {
    "precommit": "lint-staged"
  },
  "lint-staged": {
    "client/*.graphql": ["eslint . --ext .js --ext .gql --ext .graphql"],
    "server/*.graphql": ["graphql-schema-linter server/*.graphql"]
  }
}

If you have multiple schemas in the same folder, your

lint-staged
configuration will need to be more specific, otherwise
graphql-schema-linter
will assume they are all parts of one schema. For example:

Correct:

{
  "scripts": {
    "precommit": "lint-staged"
  },
  "lint-staged": {
    "server/schema.public.graphql": ["graphql-schema-linter"],
    "server/schema.private.graphql": ["graphql-schema-linter"]
  }
}

Incorrect (if you have multiple schemas):

{
  "scripts": {
    "precommit": "lint-staged"
  },
  "lint-staged": {
    "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
,
schemaPaths
,
customRulePaths
, and
rulesOptions
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"],
    "schemaPaths": ["path/to/my/schema/files/**.graphql"],
    "customRulePaths": ["path/to/my/custom/rules/*.js"],
    "rulesOptions": {
      "enum-values-sorted-alphabetically": { "sortOrder": "lexicographical" }
    }
  }
}

In
.graphql-schema-linterrc

{
  "rules": ["enum-values-sorted-alphabetically"],
  "schemaPaths": ["path/to/my/schema/files/**.graphql"],
  "customRulePaths": ["path/to/my/custom/rules/*.js"],
  "rulesOptions": {
      "enum-values-sorted-alphabetically": { "sortOrder": "lexicographical" }
    }
}

In
graphql-schema-linter.config.js

module.exports = {
  rules: ['enum-values-sorted-alphabetically'],
  schemaPaths: ['path/to/my/schema/files/**.graphql'],
  customRulePaths: ['path/to/my/custom/rules/*.js'],
  rulesOptions: {
    'enum-values-sorted-alphabetically': { sortOrder: 'lexicographical' }
  }
};

Inline rule overrides

There could be cases where a linter rule is undesirable for a specific part of a GraphQL schema.

Rather than disable the rule for the entire schema, it is possible to disable it for that specific part of the schema using an inline configuration.

There are 4 different inline configurations:

  • lint-disable rule1, rule2, ..., ruleN
    will disable the specified rules, starting at the line it is defined, and until the end of the file or until the rule is re-enabled by an inline configuration.
  • lint-enable rule1, rule2, ..., ruleN
    will enable the specified rules, starting at the line it is defined, and until the end of the file or until the rule is disabled by an inline configuration.
  • lint-disable-line rule1, rule2, ..., ruleN
    will disable the specified rules for the given line.
  • lint-enable-line rule1, rule2, ..., ruleN
    will enable the specified rules for the given line.

One can use these inline configurations by adding them directly to the GraphQL schema as comments.

# lint-disable types-have-descriptions, fields-have-descriptions
type Query {
  field: String
}
# lint-enable types-have-descriptions, fields-have-descriptions

""" Mutation root """ type Mutation { """ Field description """ field: String

field2: String # lint-disable-line fields-have-descriptions }

Note: If you are authoring your GraphQL schema using a tool that prevents you from adding comments, you may use the

--ignore
to obtain the same functionality.

Built-in rules

arguments-have-descriptions

This rule will validate that all field arguments have a description.

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.

descriptions-are-capitalized

This rule will validate that all descriptions, if present, start with a capital letter.

enum-values-all-caps

This rule will validate that all enum values are capitalized.

enum-values-have-descriptions

This rule will validate that all enum values have a description.

enum-values-sorted-alphabetically

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

Accepts following rule options:

  • sortOrder
    :
     - either 
    alphabetical
    or
    lexicographical
    , defaults:
    alphabetical

fields-are-camel-cased

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

fields-have-descriptions

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

input-object-fields-sorted-alphabetically

This rule will validate that all input object fields are sorted alphabetically.

Accepts following rule options:

  • sortOrder
    :
     - either 
    alphabetical
    or
    lexicographical
    , defaults:
    alphabetical

input-object-values-are-camel-cased

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

input-object-values-have-descriptions

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

interface-fields-sorted-alphabetically

This rule will validate that all interface object fields are sorted alphabetically.

Accepts following rule options:

  • sortOrder
    :
     - either 
    alphabetical
    or
    lexicographical
    , defaults:
    alphabetical

relay-connection-types-spec

This rule will validate the schema adheres to section 2 (Connection Types) of the Relay Cursor Connections Specification.

More specifically:

  • Only object type names may end in
    Connection
    . These object types are considered connection types.
  • Connection types must have a
    edges
    field that returns a list type.
  • Connection types must have a
    pageInfo
    field that returns a non-null
    PageInfo
    object.

relay-connection-arguments-spec

This rule will validate the schema adheres to section 4 (Arguments) of the Relay Cursor Connections Specification.

More specifically:

  • A field that returns a
    Connection
    must include forward pagination arguments, backward pagination arguments, or both.
  • To enable forward pagination, two arguments are required:
    first: Int
    and
    after: *
    .
  • To enable backward pagination, two arguments are required:
    last: Int
    and
    before: *
    .

Note: If only forward pagination is enabled, the

first
argument can be specified as non-nullable (i.e.,
Int!
instead of
Int
). Similarly, if only backward pagination is enabled, the
last
argument can be specified as non-nullable.

This rule will validate the schema adheres to section 5 (PageInfo) of the Relay Cursor Connections Specification.

More specifically:

  • A GraphQL schema must have a
    PageInfo
    object type.
  • PageInfo
    type must have a
    hasNextPage: Boolean!
    field.
  • PageInfo
    type must have a
    hasPreviousPage: Boolean!
    field.

type-fields-sorted-alphabetically

This rule will validate that all type object fields are sorted alphabetically.

Accepts following rule options:

  • sortOrder
    :
     - either 
    alphabetical
    or
    lexicographical
    , defaults:
    alphabetical

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
,
compact
,
json
.

Text (default)

Sample output:

app/schema.graphql
5:1 The object type `QueryRoot` is missing a description.  types-have-descriptions
6:3 The field `QueryRoot.songs` is missing a description.  fields-have-descriptions

app/songs.graphql 1:1 The object type Song is missing a description. types-have-descriptions

3 errors detected

Each error is prefixed with the line number and column the error occurred on.

Compact

Sample output:

app/schema.graphql:5:1 The object type `QueryRoot` is missing a description. (types-have-descriptions)
app/schema.graphql:6:3 The field `QueryRoot.a` is missing a description. (fields-have-descriptions)
app/songs.graphql:1:1 The object type `Song` is missing a description. (types-have-descriptions)

Each error is prefixed with the path, the line number and column the error occurred on.

JSON

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

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 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.

Customizing rules

graphql-schema-linter
comes with a set of rules, but it's possible that it doesn't exactly match your expectations.

The

--rules 
allows you pick and choose what rules you want to use to validate your schema.

In some cases, you may want to write your own rules.

graphql-schema-linter
leverages GraphQL.js' visitor.js in order to validate a schema.

You may define custom rules by following the usage of visitor.js and saving your newly created rule as a

.js
file.

You can then instruct

graphql-schema-linter
to include this rule using the
--custom-rule-paths 
option flag.

For sample rules, see the

src/rules
folder of this repository or GraphQL.js'
src/validation/rules
folder.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.