# Lint Overlay with Redocly CLI

[Overlay](https://spec.openapis.org/overlay/latest.html#Overlay-specification) is an open standard from the OpenAPI Initiative for describing a set of changes to be applied or “overlaid” onto an existing OpenAPI description.
Redocly CLI offers support for checking that your Overlay files are valid.

**Experimental Overlay support**

This feature is at an early stage, please send us lots of [feedback](https://github.com/redocly/redocly-cli/issues)!

## Lint an Overlay file

Use your existing Overlay files, or use the Overlay examples in the [Museum API project](https://github.com/Redocly/museum-openapi-example) if you'd prefer to use sample data to try things out.

**Pro-tip:** linting is much more interesting if the file actually does contain problems.
Be your own chaos monkey and introduce some errors before you proceed!

Lint using a command like the following:

```bash
redocly lint overlay/museum-api.overlay.yaml
```

If the file does not match the specification, the tool shows the details of each error that it finds, like in the following example:

```text
validating overlay/museum-api.overlay.yaml...
[1] overlay/museum-api.overlay.yaml:5:3 at #/info/description

Property `description` is not expected here.

3 |   title: Sample Overlay Configuration
4 |   version: 1.0.0
5 |   description: ""
6 | extends: openapi.yaml
7 | actions:

Error was generated by the struct rule.

validating overlay/museum-api.overlay.yaml...
[1] overlay/museum-api.overlay.yaml:11:3 at #/actions/1/descript

Property `descript` is not expected here.

Did you mean: description ?

10 | - target: $.paths['/museum-hours']
11 |   descript: "not a valid field(misspelled)"
12 |   remove: true

Error was generated by the struct rule.

```

## Configure the linting rules

Choose from the ready-made rulesets (`minimal`, `recommended` or `recommended-strict`), or go one better and configure the rules that suit your use case.
There's a full [list of built-in rules for Overlay](/docs/cli/v1/rules/built-in-rules#overlay-rules) to refer to.

Add the rules to `redocly.yaml`, but for Overlay specifications.
The following example shows configuration for the minimal ruleset with additional rules configuration:

```yaml
extends:
  - minimal

rules:
  info-contact: warn
```

The configuration shown here gives some good entry-level linting using the `minimal` standard, and warns if info contact information is missing.

## Choose output format

Since Redocly CLI is already a fully-featured lint tool, additional features such as a choice of formats are already included.

Get a report in **Markdown format** with the following command:

```bash
redocly lint --format=markdown overlay/museum-api.overlay.yaml
```

Choose your preferred output format from `codeframe`, `stylish`, `json`, `checkstyle`, `codeclimate`, `github-actions`, `markdown`, or `summary`.
The [lint command page](/docs/cli/v1/commands/lint) has full details of the command's options.

## Add Overlay linting to GitHub Actions

To make sure that your Overlay description remains valid, add linting to your CI (Continuous Integration) setup.
You can use Redocly CLI with the `github-actions` output format to get annotations directly in your pull request if any validation problems are found.
The following snippet shows an example of configuring a GitHub action for linting:

```yaml
name: Validate museum overlay descriptions

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Set up node
        uses: actions/setup-node@v4
      - name: Install Redocly CLI
        run: npm install -g @redocly/cli@latest
      - name: Run linting
        run: redocly lint overlay/*yaml --format=github-actions
```

With this action in place, the intentional errors I added to the Overlay description are shown as annotations on the pull request:

![Screenshot of annotation flagging "description" as an unexpected value](/content-assets/museum-overlay-lint-2a2304d5a6137374.png)

## Participate in Redocly CLI

Redocly CLI is an open source project, so we invite you to check out the [code on GitHub](https://github.com/Redocly/redocly-cli/), and open issues to report problems or request features.