feat(Insomnia): custom linting rules for cloud and local

[juliamrch]

Description

Closes #5284

Preview Links

https://deploy-preview-5287--kongdeveloper.netlify.app/how-to/add-custom-linting-rules/

How to test

This test uses an Insomnia Git project and the beta release (set it in Preferences > Update channel > Early Access (beta))

1. Create a custom rules file and upload it to an Insomnia project. For example:

# Spectral ruleset for linting the OpenAPI specs in this Insomnia workspace.
# Docs: https://docs.stoplight.io/docs/spectral/
#
# Run locally with:  spectral lint insomnia.wrk_*.yaml
# Insomnia's Design/Spec tab will also pick up this file automatically.

extends: ["spectral:oas"]

rules:
  # --- Info / metadata ---
  info-contact: error # require a contact in info
  info-description: warn # require a description in info
  info-license: warn # require a license in info

  # --- Operations ---
  operation-description: warn # every operation should be documented
  operation-operationId: error # every operation needs a unique operationId
  operation-operationId-unique: error
  operation-tags: warn # operations should be tagged for grouping
  operation-success-response: error # operations must define a 2xx/3xx response

  # --- Parameters & components ---
  no-$ref-siblings: error
  oas3-unused-component: warn # flag schemas/components that are never referenced

  # --- Style: kebab-case paths (loosen or remove if not desired) ---
  paths-kebab-case:
    description: Path segments should be kebab-case (e.g. /pet-store)
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(/|[a-z0-9-]+|{[a-zA-Z0-9_]+})+$"

2. Upload it to an Insomnia project
3. Create another file with different rules, name it my-rules.yaml:

# Custom Spectral rules for this Insomnia workspace.
# Imported by ../.spectral.yaml via:  extends: [spectral:oas, ./rules/my-rules.yaml]
#
# Each rule below is fully custom (its own given/then logic), not just a
# severity toggle of a built-in rule.
# Function reference: https://docs.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions

rules:
  # 1. Paths must be kebab-case (allow path params like {petId}).
  paths-kebab-case:
    description: Path segments should be kebab-case, e.g. /pet-store.
    message: "{{property}} is not kebab-case: {{error}}"
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(/|[a-z0-9-]+|{[a-zA-Z0-9_]+})+$"

  # 2. No trailing slash on paths (except the root "/").
  no-trailing-slash:
    description: Paths should not end with a trailing slash.
    severity: error
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        notMatch: ".+/$"

  # 3. operationId must be camelCase.
  operation-id-camel-case:
    description: operationId should be camelCase, e.g. getPetById.
    severity: warn
    given: $.paths[*][get,put,post,delete,patch,options,head].operationId
    then:
      function: casing
      functionOptions:
        type: camel

  # 4. Every operation must have a summary that is reasonably descriptive.
  operation-summary-length:
    description: Operation summary should be present and >= 5 characters.
    severity: warn
    given: $.paths[*][get,put,post,delete,patch].summary
    then:
      function: length
      functionOptions:
        min: 5

  # 5. Summaries should not end with a period (style consistency).
  summary-no-trailing-period:
    description: Summaries should not end with a period.
    severity: hint
    given: $.paths[*][*].summary
    then:
      function: pattern
      functionOptions:
        notMatch: "\\.$"

  # 6. All schema properties must have a description.
  schema-properties-described:
    description: Every schema property should have a description.
    severity: hint
    given: $.components.schemas[*].properties[*]
    then:
      field: description
      function: truthy

  # 7. Forbid the verbs "get"/"create" etc. in path segments (use HTTP methods).
  no-verbs-in-paths:
    description: Use HTTP methods, not verbs in the path (e.g. avoid /getPet).
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        notMatch: "/(get|post|put|delete|patch|create|update|remove|fetch)[A-Za-z]*"

  # 8. Tags defined at the root must each have a description.
  tag-has-description:
    description: Every tag declared in the root `tags` array needs a description.
    severity: warn
    given: $.tags[*]
    then:
      field: description
      function: truthy

  # 9. Server URLs must be https (no plaintext http).
  server-url-https:
    description: Server URLs should use https.
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  # 10. 2xx responses must define a response body (content).
  success-response-has-content:
    description: 2xx responses should describe a response body.
    severity: warn
    given: $.paths[*][get,post,put,patch].responses[?(@property.match(/^2/))]
    then:
      field: content
      function: truthy

Leave it in your home path.
4. Download the beta artifacts (macOS-X64-artifacts
5. Dezip it and find insomnia-inso/artifacts/inso-macos-13.0.0-beta.1.zip, click it
6. Rename the inso binary to inso-beta-13 and move it to your home
7. Open an Insomnia project in your terminal (copy and paste the command provided from Insomnia in Project settings > Path to local files).
8. Run this command: ~/inso-beta-13-1 lint spec -r ~/my-rules.yaml

Checklist

• Tested how-to docs. If not, note why here.
• All pages contain metadata.
• Any new docs link to existing docs.
• All autogenerated instructions render correctly (API, decK, Konnect, Kong Manager).
• Style guide (capitalized gateway entities, placeholder URLs) implemented correctly.
• Every page has a description entry in frontmatter.
• Add new pages to the product documentation index (if applicable).

[netlify]

✅ Deploy Preview for kongdeveloper ready!

Name	Link
🔨 Latest commit	b7cc455
🔍 Latest deploy log	https://app.netlify.com/projects/kongdeveloper/deploys/6a2abbf16e8d180007a8240b
😎 Deploy Preview	https://deploy-preview-5287--kongdeveloper.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[Copilot]

Pull request overview

This PR updates the Insomnia documentation to reflect the new approach for applying custom Spectral linting rules in both Insomnia projects and locally via Inso CLI.

Changes:

• Updates the “Add custom linting rules” how-to to use project-based ruleset uploads and clarifies supported Spectral properties.
• Adjusts the Insomnia API specs “Linting” section to reflect the updated custom rules workflow.
• Adds no_wrap frontmatter to the how-to page (currently with invalid YAML formatting).

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
app/insomnia/api-specs.md	Updates linting guidance to describe custom ruleset usage for local linting and Insomnia UI.
app/_how-tos/insomnia/add-custom-linting-rules.md	Revises the how-to steps for custom rulesets and adds a Spectral properties note (plus frontmatter change).

[fiosman]

Looks good, thanks for your hard work! Please see comments below

[Guaris]

Let's describe this warning instead of screenshot to save ourselves maintaining a screenshot.

[Guaris]

@juliamrch This contains the CLI files and the version files. Can we make those a different PR?

[cloudjumpercat]

Reviewed and it worked for me! Here's some of my feedback:

• I provided suggestions to change the wording to describe where you upload the ruleset.
• Recommend moving the ## Define the rules heading before the ## Upload the ruleset file heading.
• Suggested modifications to the verification section to trigger the ruleset more reliably.

I'm trying to be mindful of your deadlines and scope creep, but in the spirit of many users using automations/agents/AI, ideally we'd convert this how to to Inso CLI instructions instead of UI. Could be a future docs ticket. We should leave some note or FAQ about if users want to do this in the UI, do xyz, because Insomnia users do definitely ask for UI instructions frequently.

[cloudjumpercat]

Just one nitpick! This is good to merge as long as Cam has also approved it.

[cloudjumpercat]

Suggested change

	{{ site.data.products.insomnia.name }} provides a default linting ruleset. Override it to add your custom linting rules by following these steps:
	{{ site.data.products.insomnia.name }} provides a default linting ruleset. Override it to add your custom linting rules by following these steps.