Built-in rules

The built-in rules are the ones we use ourselves and think apply to the majority of APIs. Some have some additional configuration, but otherwise all you need to do is decide whether each rule should error, warn or be off.

All the built-in rules are listed here, 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

• no-unresolved-refs : Every $ref must exist
• no-unused-components : All components must be used
• security-defined : Security rules must be defined, either globally or per-operation
• spec : Conform to the declared OpenAPI specification version
• spec-components-invalid-map-name : Use only alphanumeric and basic punctuation as key names in the components section

Info

• info-contact : Contact section is defined under info
• info-license : License section is defined under info
• info-license-url : License section contains a url to the license

Operations

• operation-2xx-response : Every operation needs at least one 2xx response
• operation-4xx-response : Every operation needs at least one 4xx response
• operation-4xx-problem-details-rfc7807 : All 4xx responses use RFC7807 format
• operation-description : Description field is required for every operation
• operation-operationId : OperationId is required for every operation
• operation-operationId-unique : OperationId must be unique
• operation-operationId-url-safe : OperationIds can only contain characters that are safe to use in URLs
• operation-summary : Summary is required for every operation

Parameters

• boolean-parameter-prefixes : All boolean paramater names start with a particular prefix (such as "is")
• no-invalid-parameter-examples : Parameter examples must match declared schema types
• operation-parameters-unique : No repeated parameter names within an operation
• parameter-description : Parameters must all have descriptions
• path-declaration-must-exist : Paths must define template variables where placeholders are needed
• path-not-include-query : No query parameters in path declarations (declare them as parameters with in: query )
• path-parameters-defined : Path template variables must be defined as parameters

Paths

• no-ambiguous-paths : No path can match more than one PathItem entry, including template variables
• no-http-verbs-in-paths : Verbs like "get" cannot be used in paths
• no-identical-paths : Paths cannot be identical, including template variables
• no-path-trailing-slash : No trailing slashes on paths
• path-excludes-patterns : Set a regular expression that cannot be used in paths
• path-segment-plural : All URL segments in a path must be plural (exceptions can be configured)
• paths-kebab-case : Paths must be in kebab-case format

Requests, Responses, and Schemas

• no-enum-type-mismatch : Enum options must match the data type declared in the schema
• no-example-value-and-externalValue : Either the value or externalValue may be present, but not both
• no-invalid-media-type-examples : Example request bodies must match the declared schema
• no-invalid-schema-examples : Schema examples must match declared types
• request-mime-type : Configure allowed mime types for requests
• response-mime-type : Configure allowed mime types for responses
• response-contains-header : List headers that must be included with specific response types
• response-contains-property : Specify properties that should be present in specific response types
• scalar-property-missing-example : All required scalar (non-object) properties must have examples defined
• required-string-property-missing-min-length : All required properties of type string must have a minLength configured

Servers

• no-empty-servers : Servers array must be defined
• no-server-example.com : example.com is not acceptable as a server URL
• no-server-trailing-slash : Server URLs cannot end with a slash (paths usually start with a slash)
• no-server-variables-empty-enum : Require that enum values are set if variables are used in server definition
• no-undefined-server-variable : All variables in server definition must be defined

Tags

• operation-singular-tag : Each operation may only have one tag
• operation-tag-defined : Tags can only be used if they are defined at the top level
• tag-description : Tags must have descriptions
• tags-alphabetical : Tags in the top-level tags section must appear alphabetically

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 rules object, or use per-API settings by adding a rules object under each API in apis.

You can format each entry in the rules object 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
    rules:
      specific-api-rule: warn
rules:
  example-rule-name: error

• Verbose syntax, where you can configure additional options for rules that support them.

apis:
  main:
    root: ./openapi/openapi.yaml
    rules:
      specific-api-rule:
        severity: warn
rules:
  example-rule-name:
    severity: error
    rule-option-one: value
    rule-option-two: value

Next steps

• Learn more about API linting , or follow the guide to configuring a ruleset .
• If you didn't find the rule you need, build a configurable rule for a perfect linting fit.