Add custom linting rules in Insomnia

Insomnia provides a default linting ruleset. Override it to add your custom linting rules by following these steps:

Define the rules

The custom ruleset overrides the default one. To create a new ruleset, add your rules in the file using the Spectral syntax. If you want to extend an existing ruleset, specify the ruleset with the extends property.

Available Spectral top level properties in Insomnia are rules and extends. Custom functions are not permitted. However, Insomnia provides support for Spectral built-in core functions.

For example, to extend the default Spectral OpenAPI ruleset to add a warning when tags don’t have a description, add the following content to your ruleset file:

extends: spectral:oas
rules:
  tag-description:
    description: Tags must have a description.
    given: $.tags[*]
    severity: warn
    then:
      field: description
      function: truthy

Upload the ruleset file

1. In the Insomnia app, navigate to the API Collection with the OAS file you want to lint.
2. Click the Spec tab.
3. Click the upload icon for Default OAS Ruleset at the bottom of the pane.

This places the ruleset file in the local working directory. Insomnia renames this custom ruleset as .spectral.yaml.

You can view the content of the file by clicking Custom Ruleset in Insomnia. If you want to make changes to the file, edit it locally.

Validate

In this example, you can confirm the rule triggers by removing the description for the GET /flights endpoint. This will be flagged since the ruleset doesn’t allow tags without a description:

"/flights":
    get:
      summary: Get KongAir planned flights
      tags:
      - flight-data

This causes a new warning to appear:

tag-description Tags must have a description.

Override the rules v13+

Override the linting rules and use another ruleset, by using either Inso CLI or .spectral.yaml:

extends:
  - spectral:oas
  - ./rules/my-rules.yaml

Make sure users in your team are running at least Insomnia 13.0 to avoid compatibility issues with this feature.