This week developer.overheid.nl, the developer portal of the Dutch government, moved all of its tooling to OpenLint. Dimitri van Hees and Joost Farla wrote about it in Dutch: Het is zover: OpenLint vervangt Spectral (“It’s happening: OpenLint replaces Spectral”). Here’s what they said, in English, and why it matters to the rest of us.

What they did

“As of this week, all developer.overheid.nl tooling runs on OpenLint, the successor to Spectral. We’ve been actively involved since July, both in the specification of the ruleset format and in the discussions about the direction of the project. When version 1.0 came out recently, we switched our tooling over straight away, including the DON Checker. The rulesets we wrote for the API Design Rules (ADR), and for validating OAS, publiccode.yml and JSON-FG, work without any changes.”

The API Design Rules are the Dutch government’s standard for REST APIs, maintained by Logius. Spectral is written into the standard itself, so this isn’t a small team swapping a dev dependency. It’s a national API standard moving its reference tooling to OpenLint, and its rulesets running unchanged on it.

Why they moved

Dimitri and Joost tie it back to their July post, written after the 14 July supply chain incident, when two malicious versions of @asyncapi/specs, a Spectral dependency, were published to npm:

“Anyone who did a fresh install in that window pulled in code that could exfiltrate SSH keys, tokens and credentials, among other things. The incident itself was resolved quickly, but the issue about it on the Spectral repository stayed silent. For many users that was the last straw, because hundreds of issues were already open and bugs in the VS Code plugin had gone unaddressed for a long time.”

They didn’t rip Spectral out in a hurry. They pinned it, and looked at vacuum, but it doesn’t fully support the ruleset format, is maintained in practice by one person, and is written in Go, while their tooling also has to run in the browser. So they helped build the fork that started under API Commons instead:

“For everyone who lay awake all summer over ‘Spectralgate’ wondering what the sensible next steps were, OpenLint is now the answer.”

The specification is the part I want to point at

Their biggest contribution isn’t the switch. It’s the specification:

“With Spectral, the ruleset format was nothing more than whatever the linter accepted in practice. We rewrote the format from the existing Spectral code into a specification of its own, published with ReSpec, with a JSON Schema and requirements stated in terms of MUST and SHOULD. That separates the specification from the toolbox, so any linter can implement the format, and OpenLint is one of them.”

They go further, and I agree with every word of it:

“Ideally vacuum becomes a Go implementation of that specification, so that a ruleset gives the same result everywhere, whichever linter you use.”

They also want OpenLint to lint more than OpenAPI, AsyncAPI and Arazzo, including Dutch government standards such as NL-SBB and DCAT-AP-NL. That’s the work we’re scoping in openlint#40: new formats without breaking changes, and rulesets for standards.

And on where the project lives:

“In July we said we’d help find a place to land, because a fork isn’t yet a standard. We found that place at Open Source Europe, where OpenLint will be hosted. That puts the format the ADR ruleset is written in into European public hands.”

How to switch, the way they describe it

If you call Spectral directly, swap the package and the command. Your rulesets don’t need converting, and an existing .spectral.yaml is still picked up. New projects can use .openlint.yaml.

- npm install --save-dev @stoplight/spectral-cli
+ npm install --save-dev openlint

- npx spectral lint openapi.yaml
+ npx openlint lint openapi.yaml

If you call the linter from your own code, the import and the class name change. RulesetDefinition and your ruleset stay the same.

- import { Spectral, type RulesetDefinition } from "@stoplight/spectral-core";
+ import { OpenLint, type RulesetDefinition } from "@openlint/openlint-core";

For Dutch government APIs they recommend the DON Checker, which wraps the ADR and publiccode.yml checks and keeps the linter and rulesets up to date for you:

npx @developer-overheid-nl/don-checker@latest \
  validate --standard adr --input ./openapi.json

What they’re taking on next

• Editors: a language server for OpenLint, so the linter works in every IDE without a separate plugin per editor. That’s the work in discussion #9 and openlint/language-server.
• vacuum: mapping where it differs from OpenLint. Most differences come from Spectral’s JavaScript legacy in regular expressions and JSONPath, and “on some points vacuum follows the underlying standards better than Spectral.”
• A new version of the specification: backwards compatible with existing rulesets, written so a ruleset works the same in OpenLint and in vacuum, and open to formats beyond OpenAPI, AsyncAPI and Arazzo.
• Education: tutorials and reusable aliases for common given paths and regular expressions. If you haven’t seen them, aliases already do a lot of this today.
• Backwards compatibility: testing that existing rulesets, ADR included, keep working with every change to the spec and toolbox.

What this means for OpenLint

A government that wrote a linter into its own API standard has moved to OpenLint, contributed the specification that makes OpenLint more than one tool, and committed people to the roadmap. We’re aiming for the official launch on 3 December in the Europe API track at apidays Paris, but as Dimitri and Joost say, you don’t have to wait: version 1.0 is out and you can use it now.

Thank you, Dimitri and Joost, and the developer.overheid.nl team at Geonovum. Read the original post in Dutch, try OpenLint, and join us at office hours on Thursdays.

The quotes are our English translation of the original Dutch post.

Ask people what’s hard about writing API rulesets and JSONPath comes up quickly. It came up again at Office Hours #5. Deciding what a rule should check is usually the easy part. Working out the path that selects every place it applies is the hard part, and then you have to repeat that path in every rule.

OpenLint already has an answer to this, and it doesn’t get much attention. Aliases work today, in the version on npm, with nothing to install or turn on.

Name it once

An alias gives a name to one or more JSONPath expressions. Here are two rules without one:

rules:
  operation-summary:
    given: $.paths[*][get,put,post,delete,options,head,patch,trace]
    then:
      field: summary
      function: truthy
  operation-tags:
    given: $.paths[*][get,put,post,delete,options,head,patch,trace]
    then:
      field: tags
      function: truthy

And here are the same two rules with one, reporting exactly the same problems:

aliases:
  Operation:
    - $.paths[*][get,put,post,delete,options,head,patch,trace]
rules:
  operation-summary:
    given: "#Operation"
    then:
      field: summary
      function: truthy
  operation-tags:
    given: "#Operation"
    then:
      field: tags
      function: truthy

Now the rule reads as what it means: every operation needs a summary. Someone can write or review it without being able to read the path, and the path lives in one place, where the person who knows JSONPath can get it right once.

Change it once

That one place pays off when the format moves. OpenAPI 3.2 added a query method, and the path above doesn’t select it, so an operation using it passes both rules without being checked. With the path copied into every rule, you’d have to find and fix each copy. With an alias, you add query to one line and every rule picks it up. We tried it: the same document went from no problems to two.

Say what you actually mean

A single alias can hold several paths, which is where it gets really useful. Say you want every server URL to use https. You could reach for $..servers, but that also matches any property named servers in a schema or an example. So list the real locations and give them a name:

aliases:
  Servers:
    - $.servers[*]
    - $.paths[*].servers[*]
    - $.paths[*][get,put,post,delete,options,head,patch,trace].servers[*]
    - $..callbacks[*][*].servers[*]
    - $..callbacks[*][*][get,put,post,delete,options,head,patch,trace].servers[*]
rules:
  server-https:
    message: "{{value}} must use https"
    given: "#Servers.url"
    then:
      function: pattern
      functionOptions:
        match: "^https://"

Notice #Servers.url. You can carry on with more path after the name, and aliases can be built from other aliases, so a small set of well-named building blocks can serve a whole ruleset. This rule is also in the registry as server-https.

One name across versions

The same thing often lives in different places in different versions of a format. Reusable parameters are at $.parameters in Swagger 2.0 and $.components.parameters in OpenAPI 3. A scoped alias picks its paths by the format of the document being linted:

aliases:
  ParameterObject:
    targets:
      - formats: [oas2]
        given:
          - $.parameters[*]
      - formats: [oas3]
        given:
          - $.components.parameters[*]

A rule that uses #ParameterObject doesn’t need to know which version it’s looking at, as long as it lists the same formats. The version differences stay inside the alias.

Where they stop

Aliases have limits you should know about. The big one is that an alias belongs to the ruleset that declares it. spectral:oas has a good OperationObject alias, but extending that ruleset doesn’t let your rules use it, so for now you copy what you need. Everyone ends up writing their own Servers, and nothing helps you share them.

That’s an opportunity as much as a limit. Whether aliases should be shareable is an open question in the specification and in discussion #2, and shared, tested aliases for each format could take a lot of JSONPath off the plate of everyone writing rules. If you have opinions, please bring them there.

Try it

Next time you paste a path into a second rule, make it an alias. Our aliases guide covers all of this, including the limits and a YAML gotcha that produces a confusing error, and every example in it was run against OpenLint 1.0.0.

If you’ve already written good aliases for your own rulesets, we’d love to see them. Share them in Discussions or bring them to office hours on Thursdays.

OpenLint now has a home. Open Source Europe has approved our application, and OpenLint is a hosted collective at opencollective.com/openlint.

What a fiscal host does

OpenLint is a community, not a company. A fiscal host is the legal entity that holds and accounts for money on a project’s behalf, so a community can take sponsorships and grants, pay contributors and cover costs without forming an organization of its own. Everything runs through Open Collective, so every contribution and every expense is public.

Why Open Source Europe

We looked at the Linux Foundation and the OpenAPI Initiative as well, and the community favored Open Source Europe, for three reasons:

• The people and the demand are in Europe. Most of the people doing the governance work are based there. Much of the demand comes from European public institutions that use API linting to enforce national API design rules, and they need a standard no single vendor controls.
• A neutral home. We wanted a host that can hold the project’s name and its intellectual property, and act as a neutral fiscal host for everyone who contributes.
• Sovereign infrastructure. It fits the push for open source infrastructure that’s governed in Europe, in the open.

Why this matters for OpenLint

Spectral’s ruleset format became a de facto standard. Governments, banks and companies publish their API design rules as Spectral rulesets, and other tools import them. But the format was never specified, and its future depended on one vendor’s priorities. OpenLint is turning that work into a shared, vendor-neutral standard: a specification with a conformance suite, a toolbox carried over from Spectral under Apache 2.0, and a community that works in the open.

A standard needs a home that isn’t any one vendor. Now it has one.

How the money will be used

Open Collective lets us do what we said we would when we applied:

• Pay maintainers for the work that keeps the toolbox healthy: releases, reviews, security and the supply chain.
• Facilitate the community: the weekly office hours, recordings and transcripts, and the work that moves from discussion to issue to pull request.
• Fund the specification: we’re preparing grant proposals, starting with the Sovereign Tech Fund for the specification and its conformance suite.

API Evangelist is the first sponsor. Everything we receive and spend shows up on the collective’s page, and we post updates there as the work moves.

Support OpenLint

If your organization runs API linting in its pipelines, or publishes its API design rules as rulesets, please consider sponsoring OpenLint on Open Collective. It goes straight to the people doing the work.

You can also help without money: try the migration from Spectral, join us at office hours on Thursdays, or bring your questions to Discussions.

Thank you to Open Source Europe for welcoming us.

OpenLint 1.0.0 is on npm, the specification is published, and the docs are live. The next step is the one that matters most to anyone running Spectral today: moving over. We’re looking for beta testers to help us prove that path.

API Commons has switched

API Commons runs a stack of API governance tools on the linter, including validator.apicommons.org, a governance MCP server and a catalog of more than 700 rules. All of them now run on OpenLint. We checked the results against Spectral 6.16.1 on every fixture we have, and they matched.

The move was mostly a rename. What tripped us up is what we want to hear about from you:

• Custom functions that import Spectral’s core. A function that imports @stoplight/spectral-core won’t load in OpenLint. Import from @openlint/openlint-core instead, and use named imports rather than a default import.
• Extra metadata on rules. Rulesets that carry their own properties, such as a title or a prompt for an AI agent, are rejected, so we strip them from published rulesets for now.
• JSON output on a clean run. With -f json, a run with no problems prints [] plus a line of text, which a script parsing the output has to allow for.

These are in front of the community, and backwards compatibility is the subject of an open discussion.

How to migrate

The Spectral migration guide has the details. For most teams it’s two steps:

1. Install OpenLint: npm install openlint, or run it with npx openlint lint.
2. Change spectral to openlint in your commands and pipelines.

Your existing .spectral.yaml and extends: spectral:oas keep working. If you use the JavaScript API, the guide shows how to alias the old package names so you can try OpenLint without changing any code, and how to rename things properly when you’re ready.

Help us test it

We want companies, organizations, institutions and government agencies of every size to try the migration on their real rulesets and pipelines: custom functions, shared rulesets pulled over the network, CI setups, and editor workflows.

If you’d like to take part:

• Tell us you’re testing. Email info@openlint.org or start a thread in Discussions. Just knowing who’s trying it helps us decide what to fix first.
• Report what breaks. Anything that behaves differently from Spectral, or anything the guide doesn’t cover, goes in an issue on openlint/openlint.
• Come to office hours. We meet every Thursday at 9:00 ET. Agendas are in openlint/community, and recordings and transcripts are on this site.

We’re aiming to make the official launch at API Days Paris, and we’d like to go in with migration stories from more than one organization. If yours could be one of them, we’d love to hear from you.

The first formal draft of the OpenLint Ruleset Specification is published at spec.openlint.org, and we’d like your feedback.

Rulesets are how teams write down their API style guides and governance: thousands of them already exist in the Spectral format. But that format was never specified; it was whatever one tool did. This draft changes that. It describes the ruleset format as it works today, so existing rulesets stay valid, and writes it down as a proper specification that any tool can implement.

What’s in the draft

Joost Farla rewrote the specification as a formal Working Draft, built with Bikeshed, the tool behind many W3C-style specifications:

• 97 numbered requirements, each written as a testable MUST, SHOULD or MAY, and each aimed at either a ruleset or a linter
• Conformance tests listed for each requirement, so any linter can check that it behaves the same way
• Chapters on the ruleset format, documents, linting and functions, plus a security and privacy section
• A machine-readable requirements index and the JSON Schema for tooling
• A version line: the working draft now, with versioned releases to follow

Where we need help

Writing the format down surfaced a lot of behavior that was never documented, only implemented. The draft marks 36 open questions inline, right where they occur. For example, a YAML file with several documents is accepted today, but only the first one is linted. Should it be?

These are exactly the decisions that need more than one voice:

• Read the draft at spec.openlint.org and look for the open questions in your area
• Comment in discussion #13, or open an issue in openlint/spec
• Bring your rulesets: if a ruleset you rely on behaves differently from what the draft says, that’s the most useful report you can send

Under our governance, changes to the specification stay open for at least 14 days, and anything breaking for 30, with known implementers told directly. Nothing here changes what your rulesets do today.

Join us at office hours on Thursdays if you’d rather talk it through.

Drafted with Claude, and edited by me.

We held the third OpenLint office hours on 15 October, with me dialing in from Stockholm after the Nordic APIs Summit. The recording is on YouTube and the agenda is on GitHub.

Our focus hasn’t changed: set the table before adding anything new. This week the table is nearly set.

A first release

Phil Sturgeon plans to publish 0.1.0 within days: the rename from Spectral, with the tests passing. Then 0.2.0 by next week, and a fully backwards-compatible 1.0 in a month or two, with a new core ruleset and an export named Spectral, so JavaScript users can switch packages and nothing else. Breaking changes wait for 2.0. Installing it will be as simple as npm install openlint.

A formal specification

Joost Farla showed a prototype of the specification built with Bikeshed, the tool behind many W3C-style specs. Every rule is written as a testable requirement, each aimed at either a ruleset or a linter, with conformance tests listed alongside, versioned releases and a working draft. We agreed to publish it from the spec repo on its own subdomain. The first version documents the format as it works today; modular rulesets get their own discussion.

Funding

Open Source Europe is now our fiscal host, so we can accept donations. API Evangelist is putting in the first $1,000, and I’m going after European Commission grants. The first things we’d fund are small, well-scoped pieces like the release pipeline and the docs site.

What’s left

• The npm package and its release pipeline
• A docs site built from the Markdown in the code repo
• The specification site
• A migration guide, which Phil has started
• Editor support for VS Code and IntelliJ, ideally through a language server

After that, the first new thing on the list is validating Markdown and agent skills (openlint#11), the most common request I hear.

A few companies have offered to be early adopters and tell us what migrating is like. I’ll be the first, switching my own tooling over as soon as 0.1.0 is out.

Next week’s office hours start an hour earlier, and we’ll alternate times after that so more people can join. Check the roadmap for what’s unclaimed, and come say hello.

Drafted with Claude from the recording, and edited by me.

We held the second OpenLint office hours on 8 October. The recording, summary and full transcript are up, and the agenda is on GitHub.

The theme this week was setting the table. Our goal right now isn’t new features. It’s getting OpenLint open for business: running on par with Spectral, with governance, so the people who depend on it can switch.

The specification

The specification and its JSON Schema are up for review in openlint/spec#2. It documents the ruleset format as it works today, without changing it. If you have feedback, now is the time; we’ll merge in a couple of weeks.

Backwards compatibility took most of the hour. Everyone agrees that every ruleset that works in Spectral today has to keep working. Jakub Rożek pushed us further: compatibility also covers the JavaScript API that editors embed, and the lint results themselves, the same messages and ranges from the same ruleset. Measuring that takes a conformance suite, and that conversation continues in discussion #12. We also need to decide what our first version number is.

The code

Telemetry is gone. Phil Sturgeon’s rename and cleanup merged in openlint#1 and continues in #6. Jakub is upgrading Node in #7, and Miguel Quintero sent his first pull request, upgrading TypeScript, in #8. Next comes supply chain health, cleaning up vendorisms, and a migration path off Spectral.

New discussions

People are bringing real needs to the table:

• Dimitri van Hees asks for case-insensitive matching (#27), so a rule can check for an api-version header without listing every spelling.
• Andrzej Jarzyna raises custom functions and an expression language (#28), so rulesets don’t have to run someone else’s JavaScript.
• Andrzej also proposes comparing two versions of a document (#29) to catch breaking changes.

Running the project

Proposals for governance and a maintainers page are open, and everyone who comes to office hours is listed as a contributor. We’re on Open Collective, waiting on Open Source Europe to accept us as our fiscal host. I’m also drafting a simple way to disclose AI use on issues and pull requests, rated from 1 (none) to 5 (fully automated). This post was drafted with Claude; I’d rate it a 4.

Get involved

The roadmap shows what’s in progress and what’s still unclaimed, and the changelog shows what moved each week. Pick something up, start a discussion, or join us at office hours on Thursday.

On 24 September we held the first office hours under the OpenLint name. We’ve been meeting weekly since the summer, but those calls were mostly about what this project is and what to call it. This was the first one where we got to work.

The agenda is on GitHub, and the recording, summary and full transcript are here on the site.

A name, and a foundation

We have a name, chosen by community vote. It’s literal, and a little boring, but after watching OpenAPI succeed, I think a name that explains itself is worth more than a clever one. The website, the GitHub org, a community repo and info@openlint.org are all in place. SmartBear may still decide to hand Spectral to the group. We’re not waiting on that.

The roadmap, in three areas

We walked through the starter roadmap: the specification, the toolbox, and the administration of the project. The list grew on the call:

• The conformance suite and IDE integration each belong in both the specification and the toolbox.
• The specification should be friendly to AI tools, with prompts and skills.
• Migration, keeping up with Spectral upstream, and the implementation landscape become one item about interoperability with Spectral, Vacuum, Speakeasy and other tools, rather than one-way migration.
• Coverage turns out to be two features: how much of a ruleset its tests exercise, and how much of an API document the rules actually reached.
• A code of conduct, a website item, and a process item went on the administration list.

Phil Sturgeon walked through the first three discussions: aliases, cleaning up Stoplightisms, and rules testing.

How the work will happen

Work starts as a discussion, becomes issues once we know who cares about it, and gets done in pull requests. My proposal for AI is to use it sparingly, agree on it pull request by pull request, and keep it out of our issues. That one is open for discussion too. The first discussions to open are the formal specification, the core libraries, the code of conduct and governance.

If any item on the roadmap matters to you, start a discussion on it, or join us at the next office hours.