{"templateId":"markdown","versions":[{"version":"v1","label":"1.x (archive)","link":"/docs/cli/v1/guides/lint-overlay","default":false,"active":false,"folderId":"6f4800fc"},{"version":"v2","label":"2.x (current)","link":"/docs/cli/guides/lint-overlay","default":true,"active":true,"folderId":"6f4800fc"}],"sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"redocly_category":"Redocly CLI","type":"markdown"},"seo":{"title":"Lint Overlay with Redocly CLI","description":"Unlock powerful linting capabilities for Overlay documents. Use the Redocly CLI to enforce basic validation, configure rules, or even build custom plugins for Overlay.","siteUrl":"https://redocly.com","image":"/assets/redocly-card.f670aae34a39545a5ea633a540cb3a4a333a1f23bb2ed3c4a1b17a5fbcf0ac85.db81178d.png","lang":"en-US"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"lint-overlay-with-redocly-cli","__idx":0},"children":["Lint Overlay with Redocly CLI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://spec.openapis.org/overlay/latest.html#Overlay-specification"},"children":["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 files are valid."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Experimental Overlay support"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This feature is at an early stage, please send us lots of ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/redocly/redocly-cli/issues"},"children":["feedback"]},"!"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"lint-an-overlay-file","__idx":1},"children":["Lint an Overlay file"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Use your existing Overlay files, or use the Overlay examples in the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/Redocly/museum-openapi-example"},"children":["Museum API project"]}," if you'd prefer to use sample data to try things out."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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!"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Lint using a command like the following:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly lint overlay/museum-api.overlay.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the file does not match the specification, the tool shows the details of each error that it finds, like in the following example:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"text","header":{"controls":{"copy":{}}},"source":"validating overlay/museum-api.overlay.yaml...\n[1] overlay/museum-api.overlay.yaml:5:3 at #/info/description\n\nProperty `description` is not expected here.\n\n3 |   title: Sample Overlay Configuration\n4 |   version: 1.0.0\n5 |   description: \"\"\n6 | extends: openapi.yaml\n7 | actions:\n\nError was generated by the struct rule.\n\n\n\nvalidating overlay/museum-api.overlay.yaml...\n[1] overlay/museum-api.overlay.yaml:11:3 at #/actions/1/descript\n\nProperty `descript` is not expected here.\n\nDid you mean: description ?\n\n10 | - target: $.paths['/museum-hours']\n11 |   descript: \"not a valid field(misspelled)\"\n12 |   remove: true\n\nError was generated by the struct rule.\n\n","lang":"text"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"configure-the-linting-rules","__idx":2},"children":["Configure the linting rules"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose from the ready-made rulesets (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minimal"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommended"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["recommended-strict"]},"), or go one better and configure the rules that suit your use case."," ","There's a full ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/rules/built-in-rules#overlay-rules"},"children":["list of built-in rules for Overlay"]}," to refer to."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Add the rules to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["redocly.yaml"]},", but for Overlay specifications."," ","The following example shows configuration for the minimal ruleset with additional rules configuration:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"extends:\n  - minimal\n\nrules:\n  info-contact: warn\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The configuration shown here gives some good entry-level linting using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["minimal"]}," standard, and warns if info contact information is missing."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"choose-output-format","__idx":3},"children":["Choose output format"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Since Redocly CLI is already a fully-featured lint tool, additional features such as a choice of formats are already included."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Get a report in ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Markdown format"]}," with the following command:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"redocly lint --format=markdown overlay/museum-api.overlay.yaml\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Choose your preferred output format from ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["codeframe"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["stylish"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["json"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkstyle"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["codeclimate"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["github-actions"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["markdown"]},", or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["summary"]},"."," ","The ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/cli/commands/lint"},"children":["lint command page"]}," has full details of the command's options."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"add-overlay-linting-to-github-actions","__idx":4},"children":["Add Overlay linting to GitHub Actions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To make sure that your Overlay description remains valid, add linting to your CI (Continuous Integration) setup."," ","You can use Redocly CLI with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"yaml","header":{"controls":{"copy":{}}},"source":"name: Validate museum overlay descriptions\n\non: [pull_request]\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout\n        uses: actions/checkout@v4\n      - name: Set up node\n        uses: actions/setup-node@v4\n      - name: Install Redocly CLI\n        run: npm install -g @redocly/cli@latest\n      - name: Run linting\n        run: redocly lint overlay/*yaml --format=github-actions\n","lang":"yaml"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["With this action in place, the intentional errors I added to the Overlay description are shown as annotations on the pull request:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/museum-overlay-lint.5e715d61a3366b32d1313caaf5385ccb5ced24b9af4da1410fa2f935d5c82707.c10889f1.png","alt":"Screenshot of annotation flagging \"description\" as an unexpected value"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"participate-in-redocly-cli","__idx":5},"children":["Participate in Redocly CLI"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Redocly CLI is an open source project, so we invite you to check out the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://github.com/Redocly/redocly-cli/"},"children":["code on GitHub"]},", and open issues to report problems or request features."]}]},"headings":[{"value":"Lint Overlay with Redocly CLI","id":"lint-overlay-with-redocly-cli","depth":1},{"value":"Lint an Overlay file","id":"lint-an-overlay-file","depth":2},{"value":"Configure the linting rules","id":"configure-the-linting-rules","depth":2},{"value":"Choose output format","id":"choose-output-format","depth":2},{"value":"Add Overlay linting to GitHub Actions","id":"add-overlay-linting-to-github-actions","depth":2},{"value":"Participate in Redocly CLI","id":"participate-in-redocly-cli","depth":2}],"frontmatter":{"seo":{"title":"Lint Overlay with Redocly CLI","description":"Unlock powerful linting capabilities for Overlay documents. Use the Redocly CLI to enforce basic validation, configure rules, or even build custom plugins for Overlay."}},"lastModified":"2026-07-03T11:19:50.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/cli/guides/lint-overlay","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}