Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

graphql-schema-linter

Package Overview
Dependencies
Maintainers
1
Versions
54
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

graphql-schema-linter

Command line tool and package to validate GraphQL schemas against a set of rules.

  • 0.2.4
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
57K
decreased by-4.51%
Maintainers
1
Weekly downloads
 
Created
Source

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 <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: compact, json, text

  -s, --stdin

    schema definition will be read from STDIN instead of specified file

  -c, --config-direction <path>

    path to begin searching for config files

  -p, --custom-rule-paths <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, customRulePaths and schemaPaths 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"]
  }
}

In .graphql-schema-linterrc

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

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'],
};

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

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

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.

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 <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 <paths> option flag.

For sample rules, see the src/rules folder of this repository or GraphQL.js' src/validation/rules folder.

FAQs

Package last updated on 27 Jan 2020

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc