Built-in rules

All of our built-in Redocly CLI rules are listed on this page. We don't ship any built-in preprocessors.

To change your settings for any given rule, add or modify its corresponding entry in the lint.rules section of the Redocly configuration file in your working directory.

You can specify global settings in the top-level lint.rules section, or use per-API settings by adding a lint.rules section under each API in apis.

You can format each entry in the lint.rules section in one of the following ways:

• Short syntax with single-line configuration rule-name: {severity} , where {severity} is one of error , warn or off . 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 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.

List of built-in rules

assertions

Configure assertions to enforce your API design standards without coding custom rules. Learn how to configure assertions.

boolean-parameter-prefixes

name fields of parameters with type boolean should have a is or has prefix. You can specify different prefixes.

lint:
  boolean-parameter-prefixes:
    severity: {severity}
    prefixes: ["can", "is"]

info-contact

Verifies the info contact object is present and correctly structured.

info-license

Verifies the license is declared.

info-license-url

Verifies the license URL is declared.

no-ambiguous-paths

Verifies that paths are not ambiguous as defined in the spec:

Assuming the following paths, the concrete definition, /pets/mine, will be matched first if used:

  /pets/{petId}
  /pets/mine

The following paths are considered identical and invalid:

  /pets/{petId}
  /pets/{name}

The following may lead to ambiguous resolution:

  /{entity}/me
  /books/{id}

no-empty-servers

Empty servers defaults to localhost. This rule verifies the servers have been defined.

no-enum-type-mismatch

Enum values should respect the type specifier.

no-example-value-and-externalValue

Examples for requestBody or response examples can have an externalValue or a value, but they cannot have both.

no-http-verbs-in-paths

Prevent HTTP verbs in paths like GET /getAllCustomers. Configure splitIntoWords to split path into words using casing before matching:

lint:
  no-http-verbs-in-paths:
    severity: {severity}
    splitIntoWords: true

no-identical-paths

Verifies that paths are not identical, including templated paths.

For example, these paths are identical because only the parameter name changed.

/pets/{id}
/pets/{hash}

no-invalid-media-type-examples

Verifies media type examples comply with the defined schema. Disallows additional properties by default. Adjust that behavior in configuration:

lint:
  rules:
    no-invalid-media-type-examples:
      severity: warn
      disallowAdditionalProperties: false

no-invalid-parameter-examples

Verifies that parameter example value conforms to the schema. Disallows additional properties by default.

lint:
  no-invalid-parameter-examples:
    severity: error
    disallowAdditionalProperties: false

no-invalid-schema-examples

Verifies that schema example value conforms to the schema. Disallows additional properties by default.

lint:
  no-invalid-schema-examples:
    severity: error
    disallowAdditionalProperties: false

no-path-trailing-slash

Verifies that paths do not end with a trailing slash.

Some web tooling (like mock servers, real servers, code generators, application frameworks, etc.) will treat example.com/foo and example.com/foo/ as the same thing, but other tooling will not. Enable this rule to avoid confusion in your documentation.

no-server-example.com

Server URL should not point to example.com.

no-server-trailing-slash

Server URL should not have a trailing slash.

Some tooling forgets to strip trailing slashes off the servers.url is joined with paths, and you can get awkward URLs like https://example.com/api//pets. This rule helps prevent such issues.

no-unresolved-refs

Resolves all refs.

no-unused-components

Verifies there are no unused components. Note: it does not verify there aren't any unused files.

operation-2xx-response

Operation must have at least one 2xx response. Any API operation (endpoint) can fail but presumably it is also meant to do something constructive at some point. If you forget to write out a success case for this API, then this rule will let you know.

operation-4xx-response

Operation must have at least one 4xx response.

Any API may return an error. Verifies that every API operation has at least one error case described.

operation-description

Verifies each operation has a description.

operation-operationId

Every operation must have an operationId defined. Useful in the docs for deep-linking. Useful elsewhere by having a common ID to refer to any operation.

operation-operationId-unique

Every operation must have a unique operationId.

Why? A lot of documentation systems use this as an identifier and some SDK generators convert them to a method name. Enforcing this rule helps prevent issues in those and many other similar cases.

operation-operationId-url-safe

Seeing as operationId is often used for unique URLs in documentation systems, it's a good idea to avoid non-URL safe characters.

operation-parameters-unique

Verifies parameters are unique for any given operation.

operation-security-defined

Operation security values must match a scheme defined in the components.securitySchemes object.

operation-singular-tag

Use just one tag for an operation. Helpful for some documentation systems that use tags to avoid duplicate content.

operation-summary

Verifies each operation has a summary. Operation summaries are used to generate API docs.

operation-tag-defined

Operation tags should be defined in global tags.

parameter-description

Verifies that each parameter has a description.

path-declaration-must-exist

Path parameter declarations cannot be empty, e.g. /given/{}is invalid.

path-excludes-patterns

Disallow specific regular expressions to match against paths.

lint:
  path-excludes-patterns:
    severity: error
    patterns:
      - ^\/[a-z]

path-not-include-query

Don't put query string items in the path, they belong in parameters with in: query.

path-parameters-defined

Verifies the path parameters are defined.

path-segment-plural

All path segments should be plural. You can skip last segment or add exceptions using configuration:

lint:
  boolean-parameter-prefixes:
    severity: {severity}
    ignoreLastPathSegment: true
    exceptions:
      - v1

paths-kebab-case

All path items should be in kebab-case.

request-mime-type

Limit the allowed request body mime types. The rule inverses behavior for webhooks and events: it enforces responses mime types.

lint:
  request-mime-type:
    severity: error
    allowedValues:
      - application/json

response-mime-type

Limit the allowed response mime types. The rule inverses behavior for webhooks and events: it enforces requests mime types.

lint:
  response-mime-type:
    severity: error
    allowedValues:
      - application/json

spec

Validate against the declared OpenAPI specification (currently supports version 2.0, 3.0, and 3.1).

tag-description

Verifies that each tag has a description.

tags-alphabetical

Verifies that tags (names) are declared in alphabetical order.

response-contains-header

Enforces using specified response headers.

lint:
  rules:
    response-contains-header:
      severity: error
      names:
        2XX: 
          - x-request-id
        400:
          - Content-Length

response-contains-property

Enforces definition of specific response properties based on HTTP status code or HTTP status code range. A specific status code takes priority over the status code range.

response-contains-property:
  severity: error
  names:
    2XX:
      - created_at
    400:
      - title

scalar-property-missing-example

Verifies that every scalar property has an example defined.

Recommended config

There are three built-in configurations:

• minimal
• recommended
• all

The recommended configuration can be enabled by adding

lint:
  extends:
    - recommended

to the Redocly configuration file (and it is enabled by default).

You may then override the severity for any specific rule in the lint.rules section.

Here is the equivalent of the recommended configuration values:

    info-description: warn
    info-contact: off
    info-license: warn
    info-license-url: warn
    tag-description: warn
    tags-alphabetical: off
    parameter-description: off
    no-path-trailing-slash: error
    no-ambiguous-paths: warn
    path-declaration-must-exist: error
    path-not-include-query: error
    path-parameters-defined: error
    operation-description: off
    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-tag-defined: off
    operation-security-defined: error
    operation-singular-tag: off
    no-unresolved-refs: error
    no-enum-type-mismatch: error
    boolean-parameter-prefixes: off
    paths-kebab-case: off
    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

Built-in rule ideas

Redocly CLI supports 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.