Rules
All Redocly CLI rules are listed on this page.
To learn how to configure rules, read more about their configuration syntax.
Rules are roughly grouped by the OpenAPI object they apply to. The Special rules group contains rules that may apply to multiple objects or to the entire OpenAPI document.
Special rules
Info
Operations
- operation-2xx-response
- operation-4xx-response
- operation-description
- operation-operationId
- operation-operationId-unique
- operation-operationId-url-safe
- operation-summary
Parameters
- boolean-parameter-prefixes
- no-invalid-parameter-examples
- operation-parameters-unique
- parameter-description
- path-declaration-must-exist
- path-not-include-query
- path-parameters-defined
Paths
- no-ambiguous-paths
- no-http-verbs-in-paths
- no-identical-paths
- no-path-trailing-slash
- path-excludes-patterns
- path-segment-plural
- paths-kebab-case
Requests, Responses, and Schemas
- no-enum-type-mismatch
- no-example-value-and-externalValue
- no-invalid-media-type-examples
- no-invalid-schema-examples
- request-mime-type
- response-mime-type
- response-contains-header
- response-contains-property
- scalar-property-missing-example
Servers
- no-empty-servers
- no-server-example.com
- no-server-trailing-slash
- no-empty-enum-servers
- no-undefined-server-variable
Tags
Rule configuration syntax
To change your settings for any given rule, add or modify its corresponding entry in your Redocly configuration file.
You can specify global settings in the top-level lint
and rules
object, or use per-API settings by adding a lint
and rules
object under each API in apis
.
You can format each entry in the lint
and rules
object in one of the following ways:
-
Short syntax with single-line configuration
rule-name: {severity}
, where{severity}
is one oferror
,warn
oroff
. You can't configure additional rule options with this syntax.
apis:
main:
root: ./openapi/openapi.yaml
lint:
rules:
specific-api-rule: warn
lint:
rules:
example-rule-name: error
- Verbose syntax, where you can configure additional options for rules that support them.
apis:
main:
root: ./openapi/openapi.yaml
lint:
rules:
specific-api-rule:
severity: warn
lint:
rules:
example-rule-name:
severity: error
rule-option-one: value
rule-option-two: value
Severity settings
Severity settings determine how the rule is treated during the validation process.
-
severity: error
- if the rule is triggered, the output displays an error message and the API definition doesn't pass validation. -
severity: warn
- if the rule is triggered, the output displays a warning message. Your API definition may still be valid if no other errors are detected. -
severity: off
- disables the rule altogether. The rule is skipped during validation.
Recommended config
There are two built-in configurations:
- minimal
- recommended
The recommended configuration can be enabled by adding
lint:
extends:
- recommended
to the Redocly configuration file.
You may then override the severity for any specific rule in the rules
object.
Here is the equivalent of the recommended
configuration values:
info-description: warn
info-license: warn
info-license-url: warn
tag-description: warn
no-path-trailing-slash: error
no-ambiguous-paths: warn
path-declaration-must-exist: error
path-not-include-query: error
path-parameters-defined: error
operation-2xx-response: warn
operation-4xx-response: warn
operation-operationId: warn
operation-summary: error
operation-operationId-unique: error
operation-operationId-url-safe: error
operation-parameters-unique: error
operation-security-defined: error
no-unresolved-refs: error
no-enum-type-mismatch: error
spec: error
no-invalid-media-type-examples:
severity: warn
disallowAdditionalProperties: true
no-server-example.com: warn
no-server-trailing-slash: error
no-empty-servers: error
no-example-value-and-externalValue: error
no-unused-components: warn
no-undefined-server-variable: error
Rule ideas
Redocly CLI supports assertions and custom rules. However, if you have an idea for a built-in rule you believe will benefit the greater API community, please open an issue in the Redocly CLI repository.