Published: Jun 14, 2026

OpenAPI Linting: What it is and How to get Started

API contracts are complex and ever changing. If you're building a new API, it can seem easy to set some standards and follow them (such as casing for paths or properties). However, as your API evolves, or additional members join the API development process, it can become difficult to remember all the standards you initially decided and make sure all API changes abide by these standards.

In comes OpenAPI linting with Spectral rulesets using Vacuum as the implementation engine.

What is OpenAPI Linting?

OpenAPI Linting is the process of analyzing your OpenAPI file against a set of rules. Some examples of rules you could define are:

Operation paths must use kebab-casing.
All operations must define at least 1 4XX status code.
All operations must include a default response.
Component schemas and schema properties must use snake_casing.
Responses with a 204 (No Content) status code must not include a response body.
GET and DELETE operations must not include a request body.
Detect unused component schemas (where possible with custom rules or tooling).
Require all operations to include a description.
If your API versioning strategy includes required headers, OpenAPI linting can identify operations missing the required parameter.

Having a linter configured means you can continuously run your OpenAPI file through an analyzer to catch changes that don't conform to your standard. You can also use an OpenAPI linter to help migrate from legacy patterns to newer patterns by defining rules, such as:

If you are changing your API pagination strategy from a limit/offset pagination to page/pageSize pagination, you can create a rule to throw a warning when a limit or offset query parameter are detected, allowing you to gradually migrate over time.
If you are migrating responses to be the child of a data key in the root response object, a rule can be configured to warn of response bodies that don't conform to this structure.

Why should you use OpenAPI linting?

APIs are ever changing, and the people involved in them will change. Therefore, having API standards only resolved in the minds of particular people makes it difficult to share these standards and enforce them.

OpenAPI linting enables you to create an automated workflow that ensures your API always conforms to your standards, and catches issues early on. Not only does OpenAPI linting help ensure your API's "style" remains consistent, it can also enforce good OpenAPI hygiene practices such as including descriptions, requiring authentication on all operations, or requiring at least 1 4XX response status code in all operations.

Using an OpenAPI linter is free, integrates easily into CI/CD pipelines, and scales excellently as your organization grows. If your API is used by external stakeholders or critical for internal systems, OpenAPI linting is a low effort/high impact addition to your API workflow.

What is Stoplight Spectral?

Stoplight Spectral is one of the most popular open-source OpenAPI linter; it can actually be used to analyze any YAML or JSON file or specification. You can define rulesets that outline how it should analyze your OpenAPI file, and run it against your OpenAPI file.

Spectral includes many built-in recommended rules to get you started without building your own ruleset from scratch. The below examples are some of those included rules:

Operation Tag Uniqueness - Catch duplicate operation tags, since the tag property of is an array of string tag names.
Required Path Params - If a path includes a path param, such as userId in /users/{userId}, then this rules makes sure that an appropriate parameter is defined on the path level or on the operation level.
Unique Operation Id - Detect if multiple operations share the same operationId. There is also a rule to ensure the operation id is URL safe.

The rules provided by Spectral will not be comprehensive enough for everyone. Each API has its own style and guidelines that need to be enforced. You can define your own rules to enforce your organization's own standards. Below is a set of example rules that enforce different styles:


component-schema-properties-camelcase:
    description: "All component schema property names must be in camelCase."
    message: "Property must be camelCase."
    severity: error
    given: "$.components.schemas.*.properties.*~"
    then:
      function: casing
      functionOptions:
        type: camel


warn-get-operation-limit-offset:
    description: "Warn when both limit and offset query parameters are used on a GET operation."
    severity: warn
    message: "GET operations should avoid using both 'limit' and 'offset', you should use 'page' and 'pageSize' instead."
    given: 
      - $.paths.*.get.parameters[?(@.in === 'query')].name
    then:
      function: pattern
      functionOptions:
        notMatch: "^(limit|offset)$"


response-body-must-only-have-data-and-pagination-properties:
    description: "Response bodies must only include 'data' and 'pagination' as top-level keys."
    message: "Response body schema must only contain 'data' and 'pagination'."
    severity: error
    given: "$.paths[*][*].responses[*].content[*].schema.properties"
    then:
      function: pattern
      functionOptions:
        match: "^(data|pagination)$"


headers-must-start-with-x:
    description: Custom headers must start with 'x-'.
    given: $.paths.*.*.parameters[?(@.in === 'header')].name
    message: Headers must start with 'x-'.
    severity: error
    then:
      function: pattern
      functionOptions:
        match: ^(x-).+

What is Vacuum?

Vacuum is an open-source linter for OpenAPI and other YAML/JSON specifications. It is fully compatible with Spectral rulesets, and was created to resolve performance short-comings of Stoplight Spectral. The author has an excellent Why Vacuum? article that I encourage you to read.

For Restly, we decided to use Vacuum for OpenAPI linting instead of Stoplight spectral because it integrated better with our technical stack. We have a more in-depth article about how we integrated OpenAPI linting into Restly that goes into more detail.

Disclaimer: Vacuum and Restly are not affiliated with one another. We decided to use Vacuum on merit alone; it's an open-source tool to consider.

How do I get started with Vacuum?

There are a number of ways to install Vacuum. Once installed, you can lint your OpenAPI file against Vacuum's default recommended ruleset with:


vacuum lint openapi.yaml

If you already have your own custom ruleset, you can include it using the following command:


vacuum lint openapi.yaml --ruleset ruleset.yaml

For more information on running against multiple OpenAPI files and using advanced CLI arguments, visit Vacuum's article on lint commands.

OpenAPI Linting in Restly

Restly now automatically lints your OpenAPI file as you make changes in the form editor to catch issues as early as possible. You can define your own Ruleset, or use Vacuum's default recommended ruleset, for all your OpenAPI projects.

Try Restly for Free