API Linting with Spectral Keeps Getting Better

Ask 100 developers where a semicolon should go, and you’ll either get 100 answers or an all-out fistfight.

To save this from happening, most API teams that grow beyond a handful will implement a style guide. These style guides contain rules about how to handle versioning, filtering, error formats, naming conventions, pagination, or any of a million other variable parts of an API, which different teams would likely make different decisions on.

Announcing the biggest update to Spectral, our open-source API linting tool: OAS 3.1 support, improved ruleset creation and validation, ESLint-like overrides, better custom function support, and cleaner code.

We’ve made it easier than ever to create excellent style guides, and prevent wars over semicolons.

What is Spectral?

Spectral is an open-source API linting tool by Stoplight that allows users to create custom style guides to enforce validations on API design automatically. Typically, these would be in description languages such as OpenAPI, AsyncAPI, or JSON Schema.

Hundreds of companies across the globe use Spectral to create consistent APIs. Over the past year we have had tons of feedback, feature requests, and like any other open-source tool have gained some tech debt. In a quest to make API linting with a style guide even more powerful and make it easy for the community to contribute to the project, we set on the path to release the latest version of Spectral.

What’s New?

OpenAPI 3.1 and latest JSON Schema Support

OpenAPI 3.1 is the latest OpenAPI version released in January 2021 and our users are already jumping onto it. Keeping that in mind, we have added support for the latest version of OpenAPI with a built-in ruleset by Stoplight which can be extended to lint OAS 3.1 documents. Moreover, we have also added support for the latest JSON schema drafts.

JavaScript ruleset format that’s considerably more powerful

The current ruleset design (while very useful) caused various issues for Spectral’s power users. The newly added JavaScript ruleset format provides an alternative option for users enabling parity between Spectral CLI and Stoplight Studio usage, easy distribution of rulesets with custom functions across different repositories, and the ability to easily import and use external JS libraries. Read more about the new ruleset format here.

Don’t repeat complex JSON Paths with aliases

Targeting certain parts of an OpenAPI spec is powerful but it can become cumbersome to write and repeat complex JSON path expressions across various rules. Spectral V6 adds the ability to define aliases for commonly used JSON paths on a global level which can then be reused across the ruleset. This makes writing rules easier and faster. Read about path aliases here. 

This will be followed by our core rulesets providing a common set of aliases for OpenAPI and AsyncAPI so that our users don’t have to do the work at all. If you have ideas about what kind of aliases could be useful leave your thoughts here.

Go granular with ESLint like overrides

Previously Spectral supported exceptions, which were limited in their ability to target particular rules on specific files or parts of files, or changing parts of a rule. Overrides is the much more powerful version of exceptions, with the ability to customize ruleset usage for different files and projects without having to duplicate any rules. Read about overrides here.

Ruleset updates

Spectral comes with built-in rulesets for OpenAPI and AsyncAPI. Over the years they had become inconsistent with some redundant rules and messages that weren’t consistent. In the latest update, we have been meticulous about the messages, covering corner cases and removing unused rules. See the latest ruleset here.

Contribute easily to Spectral

Community is very important to us and for that reason, we wanted to make it easier to contribute to this project. That’s why we have restructured the packages to separate concerns, upgraded our CI/CD pipeline, and rewritten our documentation.

Ruleset Validation

If you have an existing ruleset this could result in validation errors in your ruleset like using an error that was removed in a previous version. Learn more in this migration guide.

We have made spectral’s validation for rulesets more robust. This makes it easier to write valid rulesets. Read more about the changes to spectral rulesets in our changelog.

Try it out today

Get started with the latest spectral here or sign up for Stoplight Platform to use it with first-class integration in Stoplight Studio.