redocly-cli/docs/configuration/extends.md

Extend included or existing configuration

Use extends to use the built-in configurations and other configuration files as the base settings. If you don't override this base configuration, it is used for all APIs specified in your configuration file.

If you don't have a Redocly configuration file, Redocly CLI automatically uses the recommended configuration. To override the default settings, you can either configure different settings for specific rules in the rules object, or create your own configuration files and reference them in the extends list.

The extends list is structured as an array of strings. It supports the following types of values:

• Built-in ruleset name (minimal, recommended or recommended-strict)
• A plugin's registered configuration name
• Path or URL to another Redocly configuration file containing rules, preprocessors, decorators or custom plugins.

When providing values as URLs, they must be publicly accessible.

extends:
  - built-in-configuration-name
  - local-plugin-name/configuration-name
  - ./path/to/another/redocly-configuration.yaml
  - https://url-to-remote/redocly.yaml

See also: Visit the detailed documentation on how to use custom plugins to set configuration.

Nested configuration

Other configuration files linked in the extends list of your main Redocly configuration file may contain their own extends list.

Custom plugins can't contain the extends list because recursive extension is not supported in that case.

The following examples illustrate configuration nesting with multiple configuration files.

Add extends to the project redocly.yaml file:

extends:
  - custom.yaml

Define another extends and some additional rules in the custom.yaml file referenced before:

extends:
  - nested.yaml
rules:
  tags-alphabetical: error
  paths-kebab-case: warn

The nested.yaml file is another Redocly configuration file containing rules:

rules:
  path-parameters-defined: error
  tag-description: warn

Priority and overrides

In case of conflict, individual API settings specified in the apis object always override settings globally specified.

Redocly CLI applies the extends configuration in the order in which items are listed, from top to bottom. The further down an item appears, the higher its priority.

In case of conflicting settings, content in the rules and decorators objects always overrides any content in the extends list.

In the following example, the rules object and another configuration file in the extends list configure the same rule (tags-alphabetical). Due to the conflict, priority goes to the inline rules over the extends list, and the tags-alphabetical has a resulting severity level of error.

Set the extends first in redocly.yaml, plus any other rules you want to add to the base configuration

extends:
  - custom.yaml
rules:
  tags-alphabetical: error
  paths-kebab-case: warn

Set up a base configuration with the rules you want to re-use. In this example, the file is called custom.yaml (example below) and it's referenced from redocly.yaml (above):

rules:
  tags-alphabetical: warn
  path-parameters-defined: warn

The same approach applies within the extends list. If you have multiple configurations that try to configure the same rule, only the setting from the last configuration in the list applies.

In the following example, Redocly CLI uses the setting for the conflicting tags-alphabetical rule from the testing.yaml file, because that file is further down in the extends list.

This means you can control the priority of configurations by reordering them in the extends list, and override all lint configurations (custom and built-in) by specifying individual rule settings in the rules object.

The main redocly.yaml file:

extends:
  - custom.yaml
  - testing.yaml

The custom.yaml file is included first:

rules:
  tags-alphabetical: warn
  paths-kebab-case: warn

Then the testing.yaml file, which overrides because it's referenced second:

rules:
  tags-alphabetical: error
  path-parameters-defined: warn

Use the extends list with the rules configuration to build up the rulesets and overrides as appropriate for your needs.