{"templateId":"markdown","versions":[{"version":"v1","label":"1.x (archive)","link":"/docs/cli/v1/guides/lint-graphql","default":false,"active":false,"folderId":"6f4800fc"},{"version":"v2","label":"2.x (current)","link":"/docs/cli/guides/lint-graphql","default":true,"active":true,"folderId":"6f4800fc"}],"sharedDataIds":{"sidebar":"sidebar-docs-cli.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Redocly CLI","type":"markdown"},"seo":{"title":"Lint GraphQL with Redocly CLI","description":"Use the Redocly CLI to validate GraphQL SDL schemas, or configure rules for GraphQL.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"lint-graphql-with-redocly-cli","__idx":0},"children":["Lint GraphQL with Redocly CLI"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Experimental"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is an experimental feature. Its behavior may change in future releases."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In addition to providing lint functionality for multiple OpenAPI formats, Redocly CLI also supports GraphQL."," ","Redocly CLI supports the following linting approaches with GraphQL documents:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["GraphQL SDL syntax and schema validation"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["built-in rules for checking common standards requirements (see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"#graphql-rules"},"children":["list of GraphQL rules"]},")"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/rules/configurable-rules"},"children":["configurable rules"]}," for building rules following common patterns"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"lint-an-existing-graphql-file","__idx":1},"children":["Lint an existing GraphQL file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly CLI takes its settings from a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," configuration file."," ","The following is an example of a simple configuration file that checks if a GraphQL SDL file is well-formed and has a valid structure:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n  struct: error\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["struct"]}," rule reports an error if the SDL contains a syntax error or if the schema is structurally invalid (for example, a field that references a type that isn't defined)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With this configuration file, and your GraphQL schema file, run the linting command:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"sh","header":{"controls":{"copy":{}}},"source":"redocly lint schema.graphql\n","lang":"sh"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The output describes structural problems with the document, or reports that it is valid."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Syntax errors always stop linting"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A GraphQL syntax error is always reported as an error and ends linting for that file, regardless of how ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["struct"]}," is configured."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"graphql-rules","__idx":2},"children":["GraphQL rules"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The supported rules are:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["struct"]},": Ensures that the GraphQL SDL is well-formed and that the schema is structurally valid."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["no-unused-types"]},": Every declared type must be referenced by another type or directive, or serve as a root operation type."," ","Root types are the ones named in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," definition or its extensions; when there is no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["schema"]}," definition, types named ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Query"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Mutation"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Subscription"]}," are the roots."," ","Types that are declared but never referenced are reported."," ","If the document has no root operation type, this rule reports nothing."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["type-description"]},": Every type definition (object, interface, enum, input object, union, and scalar) must have a non-empty description."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["We expect the list to expand over time, so keep checking back - and let us know if you have any requests by ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/Redocly/redocly-cli/issues"},"children":["opening an issue on the GitHub repo"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The rules are available in our predefined rulesets."," ","To tweak a rule's severity, configure it in your ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]}," file, for example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n  type-description: error\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configurable-rule-example","__idx":3},"children":["Configurable rule example"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly CLI also offers ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/rules/configurable-rules"},"children":["configurable rules"]}," that enable you to set assertions about the document being linted."," ","This functionality works for GraphQL too."," ","Instead of OpenAPI node types, the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["subject.type"]}," targets GraphQL AST node kinds, such as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ObjectTypeDefinition"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FieldDefinition"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["EnumTypeDefinition"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ScalarTypeDefinition"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following example shows a configurable rule that displays a warning when an object type name is not in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PascalCase"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"rules:\n  rule/graphql-type-casing:\n    subject:\n      type: ObjectTypeDefinition\n    assertions:\n      casing: PascalCase\n    severity: warn\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With the extensive configurable rules options available, there are many opportunities to make sure that your GraphQL schema conforms with expectations."," ","We'd also love to see what you're building - it helps us know how things are going!"]}]},"headings":[{"value":"Lint GraphQL with Redocly CLI","id":"lint-graphql-with-redocly-cli","depth":1},{"value":"Lint an existing GraphQL file","id":"lint-an-existing-graphql-file","depth":2},{"value":"GraphQL rules","id":"graphql-rules","depth":2},{"value":"Configurable rule example","id":"configurable-rule-example","depth":2}],"frontmatter":{"seo":{"title":"Lint GraphQL with Redocly CLI","description":"Use the Redocly CLI to validate GraphQL SDL schemas, or configure rules for GraphQL."}},"lastModified":"2026-07-02T18:19:56.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/cli/guides/lint-graphql","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}