Skip to content
Last updated

rules

Introduction

The rules configuration blocks configure linting rules and their severity. Configure built-in rules included by default, configurable rules you add yourself, and rules from plugins. The rules block can be used at the root of a configuration file, or inside an API-specific section.

Options

OptionTypeDescription
{rule name}Rule objectREQUIRED. Add as many rule entries as you like. Specify built-in rules (for example security-defined), configurable rules (for example rule/my-custom-rule), or plugin rules (for example my-plugin/add-awesome).

To configure rules for a specific specification version, use one of the specification-specific rule sections instead of rules. They accept the same options and rule objects:

  • oas2Rules
  • oas3_0Rules
  • oas3_1Rules
  • oas3_2Rules
  • async2Rules
  • async3Rules
  • arazzo1Rules
  • arazzo1_1Rules
  • overlay1Rules
  • openrpc1Rules
  • graphqlRules

Rule object

OptionTypeDescription
severitystringSeverity level of this rule. Must be one of error, warn, or off.
messagestringOptional custom message for this rule. Example: My Error Description. {{message}}. The {{message}} placeholder renders with the default error message for the rule. Include the {{message}} placeholder if you want to provide the user with your custom message as well as the default error message for the rule.
{additional properties}anySome rules allow additional configuration. Check each rule's details to find out the values you can supply here. For example the boolean-parameter-prefixes rule supports an additional option of prefixes that accepts an array of strings.

Examples

This section covers some examples and common use cases.

Use shorthand format

When the only configuration needed for a rule is the severity, you can set this as the value for the rule. The example below sets the tag-description rule to error:

rules:
  tag-description: error

This shorter syntax can help to keep your configuration file more readable.

Configure built-in rules

It's rare for our default rulesets to perfectly fit your project. Adjust the severity level of the rules to suit your needs, so that you can have certainty about the quality of your APIs. The following example shows some rules configuration:

rules:
  info-license: error
  no-ambiguous-paths: error
  boolean-parameter-prefixes:
    severity: error
    prefixes:
      - is
      - can

All the rules are configured to produce errors if their criteria are not met, the first two use the shorthand syntax to configure the severity of the rule since no other options are needed for those rules. The boolean-parameter-prefixes rule also accepts a list of allowed prefixes, and those are also configured in the example.

Configure your own rules

Redocly supports configurable rules, and those are configured in the config file. A rule to check that all operationId fields are in camel case is shown in the following example:

rules:
  rule/operationId-casing:
    subject:
      type: Operation
      property: operationId
    assertions:
      casing: camelCase

The configurable rules have user-defined names that all start with rule/ and then a meaningful name. Read the configurable rules documentation for all the details on what configurable rules can do and how to to use them.

Configure rules from custom plugins

Redocly also supports custom plugins for advanced users. Those are also configured in the rules section of the configuration file, using the plugin's module name as a prefix.

The following example shows how to enable a rule named validate from a plugin called openapi-markdown:

plugins:
  - './openapi-markdown.js'

rules:
  openapi-markdown/validate: warn

The example includes an example of including the plugin in your configuration.

  • apis configuration options allow setting per-API configuration in redocly.yaml.
  • decorators offer some transformations for your OpenAPI documents.

Resources

Custom plugins