OpenLint
Type to search documentation.

JavaScript Ruleset Format

View as MarkdownOpen in ChatGPTOpen in ClaudeOpen in GrokOpen in Perplexity

Spectral v6.0 added support for a JavaScript ruleset format, similar to the JSON and YAML formats.

This has a few benefits:

  • It lets you explicitly load formats or rulesets to get control over versioning.
  • You can load common functions from popular JS libraries.
  • It feels a lot more welcoming to developers experienced with JavaScript, especially when it comes to working with custom functions.

Example

To create a JavaScript ruleset, the first step is creating a folder. In your terminal, run the following commands:

mkdir style-guide
cd style-guide

Next, install two dependencies using npm:

Terminal window
pnpm add --save @openlint/openlint-functions
pnpm add --save @openlint/openlint-formats

Installing these packages isn’t required for creating a JavaScript ruleset, but you’ll use them in the example to create some common rules used with Spectral and to target a specific OpenAPI format.

Next, create a JavaScript file to hold your ruleset:

touch spectral.js

Inside the file, create a couple of rules:

javascript
import { truthy, undefined as pattern, schema } from "@openlint/openlint-functions";
import { oas3 } from "@openlint/openlint-formats";


export default {
  rules: {
    "api-home-get": {
      description: "APIs root path (`/`) MUST have a GET operation.",
      message: "Otherwise people won't know how to get it.",
      given: "$.paths[/]",
      then: {
        field: "get",
        function: truthy,
      },
      severity: "warn",
    },


    // Author: Phil Sturgeon (https://github.com/philsturgeon)
    "no-numeric-ids": {
      description: "Avoid exposing IDs as an integer, UUIDs are preferred.",
      given: '$.paths..parameters[*].[?(@property === "name" && (@ === "id" || @.match(/(_id|Id)$/)))]^.schema',
      then: {
        function: schema,
        functionOptions: {
          schema: {
            type: "object",
            not: {
              properties: {
                type: {
                  const: "integer",
                },
              },
            },
            properties: {
              format: {
                const: "uuid",
              },
            },
          },
        },
      },
      severity: "error",
    },


    // Author: Nauman Ali (https://github.com/naumanali-stoplight)
    "no-global-versioning": {
      description: "Using global versions just forces all your clients to do a lot more work for each upgrade. Please consider using API Evolution instead.",
      message: "Server URL should not contain global versions",
      given: "$.servers[*].url",
      then: {
        function: pattern,
        functionOptions: {
          notMatch: "/v[1-9]",
        },
      },
      formats: [oas3],
      severity: "warn",
    },
  },
};

If you use custom functions, the keywords functions and functionOptions have been removed, as they were designed to help Spectral find your functions. Now functions are passed as a variable, instead of using a string that contains the name like the JSON/YAML formats.

Next, publish the ruleset as an npm package, and then install that package as part of your API project and reference it in your Spectral ruleset as:

extends: ["@your-js-ruleset"]

Or using unpkg:

extends:
  - https://unpkg.com/@your-js-ruleset

For a more detailed example of creating a JavaScript ruleset and publishing it to npm, check out Distribute Spectral Style Guides with npm at APIs You Won’t Hate.

Last updated Oct 24, 2026