# 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](/assets/museum-overlay-lint.5e715d61a3366b32d1313caaf5385ccb5ced24b9af4da1410fa2f935d5c82707.c5aaf6fd.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.