{"id":13433194,"url":"https://github.com/cjoudrey/graphql-schema-linter","last_synced_at":"2025-04-29T18:51:06.559Z","repository":{"id":39615026,"uuid":"99191574","full_name":"cjoudrey/graphql-schema-linter","owner":"cjoudrey","description":"Validate GraphQL schema definitions against a set of rules","archived":false,"fork":false,"pushed_at":"2025-04-26T10:53:56.000Z","size":2177,"stargazers_count":699,"open_issues_count":69,"forks_count":62,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-26T11:34:36.607Z","etag":null,"topics":["graphql","linter"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cjoudrey.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-08-03T04:44:30.000Z","updated_at":"2025-04-22T22:15:06.000Z","dependencies_parsed_at":"2023-01-21T05:46:45.475Z","dependency_job_id":"950469b9-2f49-452d-8392-f5b1a467f480","html_url":"https://github.com/cjoudrey/graphql-schema-linter","commit_stats":{"total_commits":380,"total_committers":32,"mean_commits":11.875,"dds":0.3631578947368421,"last_synced_commit":"fb0dd421138a5385de9be783393fd5f684219400"},"previous_names":[],"tags_count":52,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjoudrey%2Fgraphql-schema-linter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjoudrey%2Fgraphql-schema-linter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjoudrey%2Fgraphql-schema-linter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjoudrey%2Fgraphql-schema-linter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cjoudrey","download_url":"https://codeload.github.com/cjoudrey/graphql-schema-linter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251564827,"owners_count":21609965,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graphql","linter"],"created_at":"2024-07-31T02:01:22.275Z","updated_at":"2025-04-29T18:51:06.535Z","avatar_url":"https://github.com/cjoudrey.png","language":"JavaScript","funding_links":[],"categories":["JavaScript","Honourable mentions","Linters"],"sub_categories":["GraphQL"],"readme":"# graphql-schema-linter [![Travis CI](https://travis-ci.org/cjoudrey/graphql-schema-linter.svg?branch=master)](https://travis-ci.org/cjoudrey/graphql-schema-linter) [![npm version](https://badge.fury.io/js/graphql-schema-linter.svg)](https://yarnpkg.com/en/package/graphql-schema-linter)\n\nThis package provides a command line tool to validate GraphQL schema definitions against a set of rules.\n\n![Screenshot](https://raw.githubusercontent.com/cjoudrey/graphql-schema-linter/master/screenshot-v0.0.24.png)\n\nIf you're looking to lint your GraphQL queries, check out this ESLint plugin: [apollographql/eslint-plugin-graphql](https://github.com/apollographql/eslint-plugin-graphql).\n\n## Install\n\n`graphql-schema-linter` depends on `graphql` as a peer dependency.\n\nIn order to use `graphql-schema-linter`, you can either add it to an existing project that uses the `graphql` package:\n\n```\n# Using yarn\nyarn add graphql-schema-linter\n\n# Using npm\nnpm install --save graphql-schema-linter\n```\n\nOr, you may install it globally along side `graphql`:\n\n```\n# Using yarn\nyarn global add graphql-schema-linter graphql\n\n# Using npm\nnpm install -g graphql-schema-linter graphql\n```\n\n## Usage\n\n```\nUsage: graphql-schema-linter [options] [schema.graphql ...]\n\n\nOptions:\n\n  -r, --rules \u003crules\u003e\n\n    only the rules specified will be used to validate the schema\n\n    example: --rules fields-have-descriptions,types-have-descriptions\n\n  -o, --rules-options \u003crulesOptions\u003e\n\n    configure the specified rules with the passed in configuration options\n\n    example: --rules-options '{\"enum-values-sorted-alphabetically\":{\"sortOrder\":\"lexicographical\"}}'\n\n  -i, --ignore \u003cignore list\u003e\n\n    ignore errors for specific schema members (see \"Inline rule overrides\" for an alternative way to do this)\n\n    example: --ignore '{\"fields-have-descriptions\":[\"Obvious\",\"Query.obvious\",\"Query.something.obvious\"]}'\n\n  -f, --format \u003cformat\u003e\n\n    choose the output format of the report\n\n    possible values: compact, json, text\n\n  -s, --stdin\n\n    schema definition will be read from STDIN instead of specified file\n\n  -c, --config-directory \u003cpath\u003e\n\n    path to begin searching for config files\n\n  -p, --custom-rule-paths \u003cpaths\u003e\n\n    path to additional custom rules to be loaded. Example: rules/*.js\n\n  --comment-descriptions\n\n    use old way of defining descriptions in GraphQL SDL\n\n  --old-implements-syntax\n\n    use old way of defining implemented interfaces in GraphQL SDL\n\n  --version\n\n    output the version number\n\n  -h, --help\n\n    output usage information\n```\n\n### Usage with pre-commit Hooks\n\nUsing [lint-staged](https://github.com/okonet/lint-staged) and [husky](https://github.com/typicode/husky), you can lint\nyour staged GraphQL schema file before you commit. First, install these packages:\n\n```bash\nyarn add --dev lint-staged husky\n```\n\nThen add a `precommit` script and a `lint-staged` key to your `package.json` like so:\n\n```json\n{\n  \"scripts\": {\n    \"precommit\": \"lint-staged\"\n  },\n  \"lint-staged\": {\n    \"*.graphql\": [\"graphql-schema-linter path/to/*.graphql\"]\n  }\n}\n```\n\nThe above configuration assumes that you have either one `schema.graphql` file or multiple `.graphql` files that should\nbe concatenated together and linted as a whole.\n\nIf your project has `.graphql` query files and `.graphql` schema files, you'll likely need multiple entries in the\n`lint-staged` object - one for queries and one for schema. For example:\n\n```json\n{\n  \"scripts\": {\n    \"precommit\": \"lint-staged\"\n  },\n  \"lint-staged\": {\n    \"client/*.graphql\": [\"eslint . --ext .js --ext .gql --ext .graphql\"],\n    \"server/*.graphql\": [\"graphql-schema-linter server/*.graphql\"]\n  }\n}\n```\n\nIf you have multiple schemas in the same folder, your `lint-staged` configuration will need to be more specific, otherwise\n`graphql-schema-linter` will assume they are all parts of one schema. For example:\n\n**Correct:**\n\n```json\n{\n  \"scripts\": {\n    \"precommit\": \"lint-staged\"\n  },\n  \"lint-staged\": {\n    \"server/schema.public.graphql\": [\"graphql-schema-linter\"],\n    \"server/schema.private.graphql\": [\"graphql-schema-linter\"]\n  }\n}\n```\n\n**Incorrect (if you have multiple schemas):**\n\n```json\n{\n  \"scripts\": {\n    \"precommit\": \"lint-staged\"\n  },\n  \"lint-staged\": {\n    \"server/*.graphql\": [\"graphql-schema-linter\"]\n  }\n}\n```\n\n## Configuration file\n\nIn addition to being able to configure `graphql-schema-linter` via command line options, it can also be configured via\none of the following configuration files.\n\nFor now, only `rules`, `schemaPaths`, `customRulePaths`, and `rulesOptions` can be configured in a configuration file, but more options may be added in the future.\n\n### In `package.json`\n\n```json\n{\n  \"graphql-schema-linter\": {\n    \"rules\": [\"enum-values-sorted-alphabetically\"],\n    \"schemaPaths\": [\"path/to/my/schema/files/**.graphql\"],\n    \"customRulePaths\": [\"path/to/my/custom/rules/*.js\"],\n    \"rulesOptions\": {\n      \"enum-values-sorted-alphabetically\": { \"sortOrder\": \"lexicographical\" }\n    }\n  }\n}\n```\n\n### In `.graphql-schema-linterrc`\n\n```json\n{\n  \"rules\": [\"enum-values-sorted-alphabetically\"],\n  \"schemaPaths\": [\"path/to/my/schema/files/**.graphql\"],\n  \"customRulePaths\": [\"path/to/my/custom/rules/*.js\"],\n  \"rulesOptions\": {\n      \"enum-values-sorted-alphabetically\": { \"sortOrder\": \"lexicographical\" }\n    }\n}\n```\n\n### In `graphql-schema-linter.config.js`\n\n```js\nmodule.exports = {\n  rules: ['enum-values-sorted-alphabetically'],\n  schemaPaths: ['path/to/my/schema/files/**.graphql'],\n  customRulePaths: ['path/to/my/custom/rules/*.js'],\n  rulesOptions: {\n    'enum-values-sorted-alphabetically': { sortOrder: 'lexicographical' }\n  }\n};\n```\n\n## Inline rule overrides\n\nThere could be cases where a linter rule is undesirable for a specific part of a GraphQL schema.\n\nRather 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.\n\nThere are 4 different inline configurations:\n\n- `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.\n\n- `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.\n\n- `lint-disable-line rule1, rule2, ..., ruleN` will disable the specified rules for the given line.\n\n- `lint-enable-line rule1, rule2, ..., ruleN` will enable the specified rules for the given line.\n\nOne can use these inline configurations by adding them directly to the GraphQL schema as comments.\n\n```graphql\n# lint-disable types-have-descriptions, fields-have-descriptions\ntype Query {\n  field: String\n}\n# lint-enable types-have-descriptions, fields-have-descriptions\n\n\"\"\"\nMutation root\n\"\"\"\ntype Mutation {\n  \"\"\"\n  Field description\n  \"\"\"\n  field: String\n\n  field2: String # lint-disable-line fields-have-descriptions\n}\n```\n\n**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.\n\n## Built-in rules\n\n### `arguments-have-descriptions`\n\nThis rule will validate that all field arguments have a description.\n\n### `defined-types-are-used`\n\nThis rule will validate that all defined types are used at least once in the schema.\n\n### `deprecations-have-a-reason`\n\nThis rule will validate that all deprecations have a reason.\n\n### `descriptions-are-capitalized`\n\nThis rule will validate that all descriptions, if present, start with a capital letter.\n\n### `enum-values-all-caps`\n\nThis rule will validate that all enum values are capitalized.\n\n### `enum-values-have-descriptions`\n\nThis rule will validate that all enum values have a description.\n\n### `enum-values-sorted-alphabetically`\n\nThis rule will validate that all enum values are sorted alphabetically.\n\nAccepts following rule options:\n\n- `sortOrder`: `\u003cString\u003e` - either `alphabetical` or `lexicographical`, defaults: `alphabetical`\n\n### `fields-are-camel-cased`\n\nThis rule will validate that object type field and interface type field names are camel cased.\n\n### `fields-have-descriptions`\n\nThis rule will validate that object type fields and interface type fields have a description.\n\n### `input-object-fields-sorted-alphabetically`\n\nThis rule will validate that all input object fields are sorted alphabetically.\n\nAccepts following rule options:\n\n- `sortOrder`: `\u003cString\u003e` - either `alphabetical` or `lexicographical`, defaults: `alphabetical`\n\n### `input-object-values-are-camel-cased`\n\nThis rule will validate that input object value names are camel cased.\n\n### `input-object-values-have-descriptions`\n\nThis rule will validate that input object values have a description.\n\n### `interface-fields-sorted-alphabetically`\n\nThis rule will validate that all interface object fields are sorted alphabetically.\n\nAccepts following rule options:\n\n- `sortOrder`: `\u003cString\u003e` - either `alphabetical` or `lexicographical`, defaults: `alphabetical`\n\n### `relay-connection-types-spec`\n\nThis rule will validate the schema adheres to [section 2 (Connection Types)](https://facebook.github.io/relay/graphql/connections.htm#sec-Connection-Types) of the [Relay Cursor Connections Specification](https://facebook.github.io/relay/graphql/connections.htm).\n\nMore specifically:\n\n- Only object type names may end in `Connection`. These object types are considered connection types.\n- Connection types must have a `edges` field that returns a list type.\n- Connection types must have a `pageInfo` field that returns a non-null `PageInfo` object.\n\n### `relay-connection-arguments-spec`\n\nThis rule will validate the schema adheres to [section 4 (Arguments)](https://facebook.github.io/relay/graphql/connections.htm#sec-Arguments) of the [Relay Cursor Connections Specification](https://facebook.github.io/relay/graphql/connections.htm).\n\nMore specifically:\n\n- A field that returns a `Connection` must include forward pagination arguments, backward pagination arguments, or both.\n- To enable forward pagination, two arguments are required: `first: Int` and `after: *`.\n- To enable backward pagination, two arguments are required: `last: Int` and `before: *`.\n\nNote: 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.\n\nThis rule will validate the schema adheres to [section 5 (PageInfo)](https://facebook.github.io/relay/graphql/connections.htm#sec-undefined.PageInfo) of the [Relay Cursor Connections Specification](https://facebook.github.io/relay/graphql/connections.htm).\n\nMore specifically:\n\n- A GraphQL schema must have a `PageInfo` object type.\n- `PageInfo` type must have a `hasNextPage: Boolean!` field.\n- `PageInfo` type must have a `hasPreviousPage: Boolean!` field.\n\n### `type-fields-sorted-alphabetically`\n\nThis rule will validate that all type object fields are sorted alphabetically.\n\nAccepts following rule options:\n\n- `sortOrder`: `\u003cString\u003e` - either `alphabetical` or `lexicographical`, defaults: `alphabetical`\n\n### `types-are-capitalized`\n\nThis rule will validate that interface types and object types have capitalized names.\n\n### `types-have-descriptions`\n\nThis will will validate that interface types, object types, union types, scalar types, enum types and input types have descriptions.\n\n## Output formatters\n\nThe format of the output can be controlled via the `--format` option.\n\nThe following formatters are currently available: `text`, `compact`, `json`.\n\n### Text (default)\n\nSample output:\n\n```\napp/schema.graphql\n5:1 The object type `QueryRoot` is missing a description.  types-have-descriptions\n6:3 The field `QueryRoot.songs` is missing a description.  fields-have-descriptions\n\napp/songs.graphql\n1:1 The object type `Song` is missing a description.  types-have-descriptions\n\n3 errors detected\n```\n\nEach error is prefixed with the line number and column the error occurred on.\n\n### Compact\n\nSample output:\n\n```\napp/schema.graphql:5:1 The object type `QueryRoot` is missing a description. (types-have-descriptions)\napp/schema.graphql:6:3 The field `QueryRoot.a` is missing a description. (fields-have-descriptions)\napp/songs.graphql:1:1 The object type `Song` is missing a description. (types-have-descriptions)\n```\n\nEach error is prefixed with the path, the line number and column the error occurred on.\n\n### JSON\n\nSample output:\n\n```json\n{\n  \"errors\": [\n    {\n      \"message\": \"The object type `QueryRoot` is missing a description.\",\n      \"location\": {\n        \"line\": 5,\n        \"column\": 1,\n        \"file\": \"schema.graphql\"\n      },\n      \"rule\": \"types-have-descriptions\"\n    },\n    {\n      \"message\": \"The field `QueryRoot.a` is missing a description.\",\n      \"location\": {\n        \"line\": 6,\n        \"column\": 3,\n        \"file\": \"schema.graphql\"\n      },\n      \"rule\": \"fields-have-descriptions\"\n    }\n  ]\n}\n```\n\n## Exit codes\n\nVerifying the exit code of the `graphql-schema-lint` process is a good way of programmatically knowing the\nresult of the validation.\n\nIf the process exits with `0` it means all rules passed.\n\nIf the process exits with `1` it means one or many rules failed. Information about these failures can be obtained by\nreading the `stdout` and using the appropriate output formatter.\n\nIf the process exits with `2` it means an invalid configuration was provided. Information about this can be obtained by\nreading the `stderr`.\n\nIf the process exits with `3` it means an uncaught error happened. This most likely means you found a bug.\n\n## Customizing rules\n\n`graphql-schema-linter` comes with a set of rules, but it's possible that it doesn't exactly match your expectations.\n\nThe `--rules \u003crules\u003e` allows you pick and choose what rules you want to use to validate your schema.\n\nIn some cases, you may want to write your own rules. `graphql-schema-linter` leverages [GraphQL.js' visitor.js](https://github.com/graphql/graphql-js/blob/6f151233defaaed93fe8a9b38fa809f22e0f5928/src/language/visitor.js#L138)\nin order to validate a schema.\n\nYou may define custom rules by following the usage of [visitor.js](https://github.com/graphql/graphql-js/blob/6f151233defaaed93fe8a9b38fa809f22e0f5928/src/language/visitor.js#L138) and saving your newly created rule as a `.js` file.\n\nYou can then instruct `graphql-schema-linter` to include this rule using the `--custom-rule-paths \u003cpaths\u003e` option flag.\n\nFor sample rules, see the [`src/rules`](https://github.com/cjoudrey/graphql-schema-linter/tree/master/src/rules) folder of this repository or\nGraphQL.js' [`src/validation/rules`](https://github.com/graphql/graphql-js/tree/6f151233defaaed93fe8a9b38fa809f22e0f5928/src/validation/rules) folder.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcjoudrey%2Fgraphql-schema-linter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcjoudrey%2Fgraphql-schema-linter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcjoudrey%2Fgraphql-schema-linter/lists"}