Lint Overlay with Redocly CLI

Overlay 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 1.0, 1.1, and 1.2 files are valid. To apply an Overlay to an API description, see Apply overlays.

Use your existing Overlay files, or use the Overlay examples in the Museum API project 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:

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:

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

Property `summary` is not expected here.

3 |   title: Sample Overlay Configuration
4 |   version: 1.0.0
5 |   summary: ""
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.

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 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:

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.

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:

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 has full details of the command's options.

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:

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:

Redocly CLI is an open source project, so we invite you to check out the code on GitHub, and open issues to report problems or request features.