To follow along, you’ll need:

• - [_Insomnia 13 or later_](https://insomnia.rest/download)_Insomnia 13 or later_
• - An Insomnia project with an API design document
• - An OpenAPI 3.x specification

*Note: In Insomnia 13, custom linting supports Spectral rulesets using the top-level rules and extends properties. Custom JavaScript functions are not permitted, but Spectral built-in core functions are supported.*

First, open Insomnia and create a new project, or open an existing project that contains an OpenAPI document.

For this walkthrough, I'll use a small KongAir OpenAPI specification. You can download it from the GitHub Gist below and import the kongair-openapi.yaml file into your project.

[_KongAir OpenAPI Spec (GitHub Gist)_](https://gist.github.com/sjuhi/b9d9f2ce7c589a2bddea2a108383f6e8)_KongAir OpenAPI Spec (GitHub Gist)_

https://gist.github.com/sjuhi/b9d9f2ce7c589a2bddea2a108383f6e8

This spec is intentionally incomplete. It is still useful for the demo because it lets us show two layers of validation: Default OAS linting catches general OpenAPI quality issues. Custom linting catches organization-specific API style rules. 

Before uploading any custom rules, look at the linting status in Insomnia. You should see warnings from the Default OAS Ruleset. These may include issues such as: missing `info.contact`, missing operation IDs, missing operation descriptions, and so on.

At this stage, these warnings are not coming from a custom ruleset. They are from Insomnia’s default OpenAPI linting. This is a good first step because it helps ensure the spec is structurally healthy before adding team-specific rules. Now update the spec so it passes the default OAS linting checks.

After updating the spec, the default OAS linting status should be clean or close to clean. At this point, the OpenAPI document is valid and follows the baseline expectations.

Next, we'll create a custom ruleset file named: `kongair-rules.yaml`

Paste the following rules:

https://gist.github.com/sjuhi/1d83068565fcb222db14420d0354554b

kongair-rules.yaml

This custom Spectral ruleset extends the default OpenAPI ruleset by adding four team-specific standards. It enforces HTTPS server URLs, removes trailing slashes from API paths, encourages resource-based path names instead of verbs, and ensures summaries follow a consistent formatting style.

Now upload the ruleset into Insomnia.

In Insomnia:

1. - Open the KongAir API 1.0.0 design document.
2. - Confirm the spec is clean with the Default OAS Ruleset.
3. - Click the upload icon next to Default OAS Ruleset at the bottom of the editor.
4. - Select kongair-custom-rules.yaml.
5. - Insomnia applies the custom ruleset to the OpenAPI document.
6. - After uploading, Insomnia stores the custom ruleset in the project and renames it as: .spectral.yaml

You can view the uploaded ruleset by selecting Custom Ruleset in Insomnia.

*Note: If you have already uploaded a custom ruleset in this project while testing, remove or reset it before recording the demo. Otherwise, your custom rules may already be active before you reach this step.*

After uploading the custom ruleset, the same OpenAPI spec should now show new issues. These issues are not baseline OpenAPI problems. They are team-specific style and governance rules.

• - You should see a few validation issues. For example, the `server-url-https` rule flags the server URL because it uses `http://` instead of `https://`. 
• - The `no-verbs-in-paths` rule reports the `/get-flights` path because API paths should use resource names instead of verbs such as `get`, `create`, `update`, `delete`, or `fetch`.
• - You may also see the `summary-no-trailing-period` rule, which flags operation summaries that end with a period. For example, `summary: Get KongAir planned flights`.

Now update the spec to satisfy the custom rules. 

The custom validation issues have now been resolved. The server URL has been updated to use `https://`, the `/get-flights` endpoint has been renamed to the resource-based `/flights`, and periods have been removed from the operation summaries. With these changes, the API specification now passes both the default OpenAPI validation rules and the custom team-specific Spectral rules.

Custom linting in Insomnia 13 brings API governance directly into the API design workflow. Teams can fix default OpenAPI linting issues and apply custom Spectral rulesets to validate APIs against both OpenAPI best practices and their own standards.

This helps catch issues early, keeps APIs consistent across teams, and lets the same rules be reused in local development and CI/CD pipelines, all from within Insomnia.

To get started, open an API design document in Insomnia 13, fix the default OAS linting issues, upload your custom Spectral ruleset, and validate your API against your team's standards.

Try Insomnia 13 today and simplify API design, testing, and governance in one place. [_**Download Kong Insomnia**_](https://insomnia.rest/download)_**Download Kong Insomnia**_ or [_**explore the documentation**_](https://developer.konghq.com/how-to/add-custom-linting-rules/)_**explore the documentation**_ to learn more.