docs: add Overlay linting guides

.changeset/free-fans-march.md

@@ -0,0 +1,6 @@
+---
+"@redocly/cli": patch
+"@redocly/openapi-core": patch
+---
+
+Add Overlay linting guides.

docs/@v1/guides/lint-overlay.md

@@ -0,0 +1,126 @@
+---
+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.
+---
+
+# 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.
+
+{% admonition type="info" name="Experimental Overlay support" %}
+This feature is at an early stage, please send us lots of [feedback](https://github.com/redocly/redocly-cli/issues)!
+{% /admonition %}
+
+## 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](../rules/built-in-rules.md#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](../commands/lint.md) 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:
+
+<!-- TODO: Replace with actual image link -->
+
+![Screenshot of annotation flagging "description" as an unexpected value](images/museum-overlay-lint.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.

docs/@v1/rules/built-in-rules.md

@@ -138,6 +138,15 @@ The below rules are being migrated to Respect:
 - [no-criteria-xpath](./respect/no-criteria-xpath.md): the `xpath` type criteria is not supported by Respect.
 - [respect-supported-versions](./respect/respect-supported-versions.md): the `version` property must be one of the supported values.
 
+## Overlay rules
+
+Rules for the main Overlay specification format.
+
+### Overlay
+
+- [info-contact](./overlay/info-contact.md): Contact section is defined under `info`
+- [no-unresolved-refs](./oas/no-unresolved-refs.md): Every `$ref` must exist
+
 ## Resources
 
 - Learn more about [API linting](../api-standards.md), or follow the [guide to configuring a ruleset](../guides/configure-rules.md).

docs/@v1/rules/overlay/info-contact.md

@@ -0,0 +1,74 @@
+---
+slug: /docs/cli/v1/rules/overlay/info-contact
+---
+
+# info-contact
+
+Requires the `Contact` info object defined in your API.
+
+| Overlay | Compatibility |
+| ------- | ------------- |
+| 1.0     | ✅            |
+
+```mermaid
+flowchart TD
+
+Root ==> Info --> Contact
+
+style Contact fill:#codaf9,stroke:#0044d4,stroke-width:5px
+```
+
+## API design principles
+
+When it comes to APIs, we generally want more consumers.
+If they need help to purchase, integrate, or troubleshoot, your contact info should be front and center.
+
+## Configuration
+
+| Option   | Type   | Description                                             |
+| -------- | ------ | ------------------------------------------------------- |
+| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. |
+
+An example configuration:
+
+```yaml
+rules:
+  info-contact: warn
+```
+
+## Examples
+
+Given this configuration:
+
+```yaml
+rules:
+  info-contact: error
+```
+
+Example of **incorrect** contact:
+
+```yaml Incorrect example
+info:
+  version: 1.0.0
+  title: Incorrect example missing contact
+```
+
+Example of **correct** contact:
+
+```yaml Correct example
+info:
+  contact:
+    name: Redocly API Support
+    url: https://www.redocly.com/support
+    email: [email protected]
+```
+
+## Related rules
+
+- [spec](./struct.md)
+- [configurable rules](../configurable-rules.md)
+
+## Resources
+
+- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/common/info-contact.ts)
+- [Contact object docs](https://redocly.com/docs/openapi-visual-reference/contact/)

docs/@v1/rules/overlay/struct.md

@@ -0,0 +1,28 @@
+---
+slug: /docs/cli/v1/rules/overlay/struct
+---
+
+# struct
+
+Ensures that your API document conforms to the [Overlay specification](https://spec.openapis.org/overlay/latest.html#Overlay-specification).
+
+| Overlay | Compatibility |
+| ------- | ------------- |
+| 1.x     | ✅            |
+
+The default setting for this rule (in the `recommended` and `minimal` configuration) is `error`.
+
+This is an essential rule. Do not turned it off, except in rare and special cases.
+
+## Configuration
+
+| Option   | Type   | Description                                                                                |
+| -------- | ------ | ------------------------------------------------------------------------------------------ |
+| severity | string | Possible values: `off`, `warn`, `error`. Default `error` (in `recommended` configuration). |
+
+An example configuration:
+
+```yaml
+rules:
+  struct: error
+```

docs/@v2/guides/lint-overlay.md

@@ -0,0 +1,126 @@
+---
+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.
+---
+
+# 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.
+
+{% admonition type="info" name="Experimental Overlay support" %}
+This feature is at an early stage, please send us lots of [feedback](https://github.com/redocly/redocly-cli/issues)!
+{% /admonition %}
+
+## 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](../rules/built-in-rules.md#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](../commands/lint.md) 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:
+
+<!-- TODO: Replace with actual image link -->
+
+![Screenshot of annotation flagging "description" as an unexpected value](images/museum-overlay-lint.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.

docs/@v2/rules/built-in-rules.md

@@ -149,6 +149,15 @@ The below rules are being migrated to Respect:
 - [x-security-scheme-name-reference](./respect/x-security-scheme-name-reference.md): when multiple `sourceDescriptions` exist, `workflow.x-security.schemeName` must reference a source description (for example, `$sourceDescriptions.{name}.schemeName`)
 - [x-security-scheme-required-values](./respect/x-security-scheme-required-values.md) validate that `x-security` have all required `values` described according to the used `scheme`.
 
+## Overlay rules
+
+Rules for the main Overlay specification format.
+
+### Overlay
+
+- [info-contact](./overlay/info-contact.md): Contact section is defined under `info`
+- [no-unresolved-refs](./common/no-unresolved-refs.md): Every `$ref` must exist
+
 ## Open-RPC rules
 
 Use the rules in this section for Open-RPC specific linting.