Built in rules

All of our built-in rules are listed below. We don't ship any built-in preprocessors or decorators. To change your settings for any given rule, just add or modify a corresponding item in the rules section of the .redocly.yaml in your working directory.

Each of the rules entries can be one of following:

  • rule-name: {severity}, where {severity} is on of error, warn or off
  • rule-name:
    severity: {severity}
    rule-option-one: value
    rule-option-two: value

List of built in rules


Validate against the declared OpenAPI specification (currently supports version 2 and 3.0).


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

    severity: {severity}
    prefixes: ["can", "is"]


Verifies the info contact object is present and correctly structured.


Verifies the license is declared.


Verifies the license URL is declared.


Verifies that each tag has a description.


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


Verifies that each parameter has a description.


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


Server URL should not point to example.com.


Server URL should not have a trailing slash.

Some tooling forgets to strip trailing slashes off when it's joined with the servers.url with paths, and you can get awkward URLs like https://example.com/api//pets. This rule will remind you to strip them off yourself.


Verifies the path parameters are defined.


Verifies each operation has a description.


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


Verifies parameters are unique for any given operation.


Resolves all refs.


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

      severity: warn
      disallowAdditionalProperties: false


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


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


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.


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.


Every operation must have a unique operationId.

Why? A lot of documentation systems use this as an identifier, some SDK generators convert them to a method name, and all sorts of things like that.


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


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


Use just one tag for an operation, which is helpful for some documentation systems which use tags to avoid duplicate content.


Operation tags should be defined in global tags.


Enum values should respect the type specifier.


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


Keep trailing slashes off of paths, as it can cause some confusion. 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. Avoid any confusion by just documenting them without the slash, and maybe some tooling will let people shove a / on there when they're using it or maybe not, but at least the docs are suggesting how it should be done properly.


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


Verifies that paths do not end with a trailing slash.


Verifies that paths are not identical including templated paths.

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



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:


The following paths are considered identical and invalid:


The following may lead to ambiguous resolution:



All path items should be in kebab-case.

There are three built-in configurations:

  • minimal
  • recommended
  • all

The recommended configuration can be enabled by adding

    - recommended

in the .redocly.yaml file (and it is enabled by default).

You may override any specific rule's severity then in the 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-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
      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

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