Spectral has been the default OpenAPI linter for years, and it did serve the community well. It made linting API descriptions in CI a normal thing, ensuring quality and consistency across your API documentation. Unfortunately, the recent state of its maintenance has raised security and reliability concerns to the extent that some are forking the project to continue development independently. In August 2026, SmartBear even had to explain the reasons in this blog post that describes how the July 14 supply chain attack reached Spectral.
However, there's a better option than forking Spectral: migrating your linter to Redocly CLI. It was built in the same spirit, but on a different architecture, and it is actively maintained. Let me explain why the architecture matters.
A typical Spectral rule contains the given section, which is intended to describe the target. It usually looks like a cryptic enchantment of JSONPath expressions like this:
$..[?(@ && @.type=="array")]
(and it's not even the hardest one). Can you guess what this means without asking an AI tool? I cannot. As you can imagine, writing and maintaining such rules can be quite challenging and error-prone. This is not a glitch but an architectural flaw: JSONPath matches patterns in a document tree and knows nothing about the specification.
It affects even the built-in rules. The expression above is the target of array-items from the spectral:oas ruleset, which requires every array schema to define its items type. However, it can report false positives where the same properties appear in a different context. Here is a valid OpenAPI description with an example payload:
openapi: 3.1.2
info:
title: Widgets
version: 1.0.0
paths:
/widgets:
get:
responses:
'200':
description: A form field
content:
application/json:
example:
type: array # just data, not a schema
Spectral 6.16.3 reports an error on the last line: the example payload is not a schema, but JSONPath cannot tell the difference. And this is not the only case of possible false positives.
Instead of matching paths, Redocly CLI walks a type tree defined by the specification, so a Schema is always a schema, and $refs are followed into other files. The equivalent rule from the Redocly cookbook is a few lines of YAML that say exactly that: subject Schema, where type is array, require items. It passes the description above and still reports a real type: array schema without items. This makes rules easier to understand, more precise, and less error-prone.
It's easy to add and maintain new API specifications too, and this is one of the reasons Redocly CLI supports the widest range of API standards out of the box.
The performance is also significantly better, which makes Redocly much more suitable for large-scale API projects, especially when you are running your checks in CI/CD pipelines (see OpenAPI linters: which one is the best in a real test?).
And if you've been into API documentation for some time, you probably already know that Redocly CLI has always been the best tool for multi-file setups, which are far easier to maintain than one huge file. So, chances are you already have it installed in your project for bundling API documents prior to other steps. But it also lints the whole API description from the entry point and reports problems in the file where they are, so you don't have to bundle your description before you can check it.
The Migration
If the above sounds convincing, and you've decided to change the linter, it might be an afternoon task if you're using a default ruleset. Check out the official migration guide first if this is the case. However, if you have lots of custom rules, migrating them might be challenging.
As mentioned earlier, reading and understanding the existing Spectral rules is an art form of its own. On the other hand, the Redocly rules system offers you three levels of complexity: built-in, configurable, and plugin rules. So you might ask yourself which type is right for a specific rule. If there's a built-in rule that fits your needs, it's usually the easiest and most efficient choice. If not, configurable rules allow you to define custom criteria without writing any code -- just declarative YAML in your config file. And for the most complex scenarios, plugin rules -- custom code in a plugin -- give you the flexibility to implement any specialized logic you require.
Sounds complicated? It might be at first glance, but it's actually easier than you might think, especially with the new tools Redocly just dropped.
The Skill
If you're using an AI agent, you can leverage Redocly skills, in particular redocly-lint-rules:
npx skills add https://redocly.com
We've built it with efficiency in mind, grounded in metrics. And it works even better with the new Redocly CLI inspect-node-types command, which helps you (or your LLM) explore the node types of your API description in detail, so the rule targets the right node from the start.
We ran sample migrations using different Claude models for the sake of comparison, with and without the skill and the inspect-node-types command.
Update: While I was working on this article, the repository I took as a migration sample (it's the Azure API Style Guide) was archived precisely because of a migration from Spectral. They actually decided to go with TypeSpec, but it's curious that they were also considering migration around the same time.
The table lists the percentage of the rules that were migrated correctly.
| Model | Bare LLM | Skill alone | Skill and Command |
|---|---|---|---|
| Haiku 4.5 | 22% | 27% | 31% |
| Sonnet 5 | 75% | 82% | 80% |
| Opus 5 | 93% | 97% | 98% |
From the figures, it's clear that Haiku was not capable of migrating the rules whether used with the skill or not. Sonnet performed a lot better, especially with the skill and the command, exploring the node types instead of guessing and retrying, but still required manual intervention in 1 of 5 cases.
The most interesting case was Opus, which showed 93% correctness even as a bare LLM. However, the quality of the rules written matters as much as the count. Built-in and configurable rules are pure YAML, whereas plugins are custom JavaScript you have to write and maintain. The chart breaks the correct rules down by type.
Without the skill, the model wrote three-quarters of the correct rules as plugins. With the skill and the command, that share dropped to a quarter, so you have far less custom code to maintain.
Also, the skill actually improved around 10% of the source rules while migrating them: the resulting rules catch cases the original rules missed. This is no surprise, given how hard it is to comprehend the Spectral targeting, even for the rule authors.
Based on the impact, we baked the inspect-node-types command into the new skill so you don't have to worry about it at all -- an agent will call it when needed.
Update: While I was finishing this article, Anthropic released Opus 5.5 and Sonnet 5.5, so I re-ran the same migration with them. I didn't go through the results in the same detail, but at first glance Opus 5.5 performed about the same as Opus 5, while Sonnet 5.5 did much better and got close to Opus. The skill had the same effect as before: fewer plugins, more configurable rules.
Visual Builder
Still, there might always be some corner cases that require manual intervention to ensure the rules are correctly constructed. So, if you want to tune the rules, or you just want to create one manually, Redocly just shipped a visual builder for configurable rules.
It helps you construct a rule by playing with your specific API description, so you can instantly see which nodes it matches. It is kind of similar to using Redocly's VS Code extension, where you can inspect the targets simply by hovering over them in the editor, but it lets you write a rule without even touching the keyboard.
What's next
The new redocly-lint-rules skill and visual builder are intended not only for migration. More importantly, they can help you write better rules on top of Redocly's default presets, which is the intended way to use a linter -- your API style guide should reflect your team's needs. The quality of rules matters: the skill ensures not only their correctness but also that the setup is optimized for maintenance. And if you are migrating from another linter, chances are that you can even improve the existing rules along the way.
Disclaimer: I'm a Redocly CLI maintainer
Top comments (0)