Most Popular

View all

Recent articles

The governance layer Europe's API standards are missing

OpenLint’s starting point is OpenAPI. But in getting ready for the EU government track at APIdays Paris this December, I’ve spent a lot of time with the standards Europe’s public sector actually runs on, and OpenAPI is only one of them. Europe runs on many standards When you sample the APIs and services that European governments report for the High-Value Datasets regulation, a picture of sector standards comes out: Standard Where it’s used How it’s checked today OpenAPI general REST APIs, and the OGC API generation rulesets, written agency by agency OGC API (Features, Records…) next-generation geodata OGC TEAM Engine test suites OGC WMS / WFS / WCS geodata under INSPIRE, by far the most common OGC conformance tests, INSPIRE Reference Validator INSPIRE Atom download services INSPIRE Reference Validator SDMX official statistics SDMX validation tools PxWeb / JSON-stat statistics, especially in the Nordics JSON-stat schema NeTEx, SIRI, GTFS public transport, national access points GTFS validators, NeTEx schemas and profiles DATEX II roads and traffic DATEX II schemas DCAT-AP the national data catalogs themselves SHACL shapes NGSI-LD smart cities ETSI conformance tests Each of these standards has a community, a schema, and usually a validator. That’s real, hard-won work. What each validator answers, and what it doesn’t A validator answers one question: does this document or service conform to the standard? It’s necessary, and it isn’t governance. Governance is everything a public body decides on top of the standard. How we name things, which version we use, how we describe errors and authentication, what a developer has to find before they can start, which profile of NeTEx we publish, what our DCAT-AP records must always include. Today those decisions live in PDFs, wikis and people’s heads, and checking them is manual. Where they are machine-checkable, they’re locked inside one tool for one standard. So a government that publishes OpenAPI, OGC services, SDMX and DCAT-AP ends up with four different ways of checking its own rules, or none. What OpenLint can offer beyond OpenAPI The OpenLint ruleset format is about rules over structured documents: JSONPath to select, functions to test, severities and messages for people. That’s not specific to OpenAPI. Spectral rulesets already lint AsyncAPI and arbitrary JSON and YAML, and the specification is being written to describe that format on its own, so any tool can implement it. Here’s where that could go: One way to write down public-sector API rules, whatever standard the document follows, so a government’s design rules can sit in one place and be checked in one pipeline. Shared rulesets per standard, written in the open by the people who run them: a common baseline for OGC API definitions, for DCAT-AP records, for the JSON and YAML around NeTEx and GTFS feeds. Rules that sit next to the existing validators, not instead of them, so conformance stays with each standard’s community and governance gets a common home. None of this is decided. It’s an open question for the community, and it’s the conversation I want to have with government teams in Paris. Bring it to Paris, or to office hours If your team publishes data under one of these standards and checks it by hand, I’d like to hear what you check and how. Find us at APIdays Paris in December, come to office hours on Thursdays, or start a thread in Discussions. Tell us which standard you’d want rulesets for first.
Kin Lane1 week ago

Europe's governments are already writing API rulesets. Separately.

I’m getting ready for APIdays Paris in December, where I’m moderating the EU government track and giving its keynote on what Europe’s government APIs look like from the outside, the way a developer, a business or an AI agent meets them. Part of that work has been reading the public API surfaces of about 170 government agencies, ministries and public platforms across Europe. One thing stood out, and it belongs here first. Governments already govern their APIs with rulesets When a public body takes API governance seriously, it reaches for the same tool. Here are rulesets I found published in public bodies’ own repositories, all in the Spectral format OpenLint carries forward: Logius maintains the Dutch government’s API Design Rules, and ships a Spectral linter with them. As we wrote last week, developer.overheid.nl now runs that tooling on OpenLint. VNG Realisatie, which builds shared services for Dutch municipalities, keeps a ruleset in Haal-Centraal-common for the Haal Centraal APIs. Entur, Norway’s national public transport platform, publishes its API guidelines with a Spectral ruleset alongside. PagoPA, the Italian state company behind pagoPA, the IO app and the PDND interoperability platform, lints contracts in repositories like pn-mandate and interop-be-monorepo. Developers Italia built its OAS checker for the Italian public administration’s interoperability guidelines on the Spectral engine. publiq, which runs Flanders’ culture and leisure data platform, keeps rulesets per API in its API docs. HM Courts & Tribunals Service in the UK lints at least some of its API contracts in the repository, for example this crime hearing results API. That’s seven public bodies in five countries. It’s a floor, not a census, because I only counted what I could trace to the body’s own repository. Each one is on its own Every one of these rulesets is maintained separately. Most of them encode the same handful of decisions: use OpenAPI 3, describe your errors, version consistently, document authentication, name things one way. Each team wrote those rules again, keeps them current again, and carries the risk of a tool it doesn’t control. That last part isn’t theoretical. This summer’s Spectral supply chain incident is why developer.overheid.nl moved. Every team on that list depends on the same format, and until OpenLint none of them had a say in where it went. What OpenLint changes OpenLint gives this work a shared, vendor-neutral home: A specified format. The ruleset specification means a ruleset gives the same result in every tool that implements it, so a national standard doesn’t depend on one linter. Rulesets that work unchanged. The Dutch rulesets ran on OpenLint without changes. Every ruleset in that list should too, and we’d like to hear if one doesn’t. Sharing instead of rewriting. Once the format is stable, the common rules can live in one open place, with each government layering its own on top. A neutral home. OpenLint is hosted by Open Source Europe, so no single vendor holds it. Come find us in Paris If your agency publishes API design rules, or lints contracts in a pipeline, I’d like to talk before or during APIdays Paris. Bring your ruleset. We’ll run it on OpenLint and tell you what happens. Until then, you can try the migration from Spectral, join office hours on Thursdays, or start a thread in Discussions.
Kin Lane1 week ago

The Dutch government's developer portal now runs on OpenLint

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.
Kin Lane2 weeks ago

Aliases: the hidden gem in OpenLint

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.
Kin Lane3 weeks ago

Migrating from Spectral to OpenLint: we're looking for beta testers

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: Install OpenLint: npm install openlint, or run it with npx openlint lint. 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 [email protected] 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.
Kin Lane3 weeks ago

OpenLint has a home: Open Source Europe is our fiscal host

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.
Kin Lane3 weeks ago

The OpenLint specification draft is ready for feedback

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.
Kin Lane1 month ago

Almost ready for business: the third OpenLint office hours

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.
Kin Lane1 month ago

Setting the table: the second OpenLint office hours

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.
Kin Lane1 month ago