Office Hours · 15 October 2026
OpenLint Office Hours #3
Summary
The third OpenLint office hours focused on setting the table: the npm package, the specification site, the docs site, and the base rulesets, so teams can switch from Spectral before anything new is added.
Meeting format. To include people with clashing meetings, office hours will alternate weekly between an hour earlier and the usual time. Splitting into spec and tooling calls is on the table for later.
Funding. Open Source Europe accepted OpenLint as fiscal host, so Open Collective can take donations. API Evangelist is putting in $1,000 to start, and Kin will chase European Commission grants. Small payments for well-scoped pieces of work, like the npm release pipeline and the docs site, are the first candidates.
Specification. Joost Farla demoed a formal specification prototype built with Bikeshed: testable MUST/MAY requirements, each with a conformance target (a ruleset or a linter) and conformance tests, a machine-readable registry, and versioned releases plus a working draft on a spec subdomain. The group agreed to move it into the spec repo on GitHub Pages. The first version documents Spectral’s behavior as it is; modularization needs its own discussion before the first release.
Toolbox. Phil Sturgeon aims to publish 0.1.0 (the rename) within days and 0.2.0 by next week, then a fully backwards-compatible 1.0 with a new core ruleset in a month or two; breaking changes wait for 2.0. The release pipeline needs an organization npm token. npm install openlint will be the single entry point. Editor support should cover IntelliJ as well as VS Code, ideally through a language server. Miguel Quintero will look at the MCP server and API after the TypeScript 7 work.
Research. Kin shared the 108 provider-published rulesets behind the alias analysis, and research on public GitHub pipelines that run Spectral. Agent skills validation with Markdown is one of the most-requested new features.
Agenda and discussion on GitHub · Watch on YouTube
Transcript
00:00:00Before the start: Hellos while people join. Kin is still in Stockholm after the Nordic APIs Summit, flying home tomorrow, and apologizes for the bouncing calendar invites. Talk turns to how much conference value happens in hallway conversations, Kin's breakfast with Pavel from SAP, and a talk at the conference with no AI in it that people thanked the speaker for.
00:02:07Kin Lane: I was talking this morning over breakfast with Pavel from SAP about how API Evangelist has been a flywheel for me: writing blogs and social media online, but then you've got to reinforce it with in-person events. If you don't, the flywheel slows down, the relationships aren't as strong, and online isn't as effective as it used to be.
00:03:20Kin Lane: I don't think it's about calling people out for AI slop, because I use AI for plenty of things, and I think we all do. It's about finding the root of the value, the meaning. In one keynote, the definition of an agent was "an autonomous LLM-driven task or process", and I said, shouldn't it be LLM-*enabled* rather than driven? Shouldn't it be driven by us? It needs to be human-driven.
00:04:59Kin Lane: Let's dive in. I think everyone who pinged me that they'd be here is here. We're slowly getting more structure into the format.
First: I've talked to several people, including Pavel from SAP this morning, who has another spec meeting at exactly this time, so he's never able to make it, and I've heard that from a few others. Is there any interest, desire or pushback on starting an hour earlier? I don't know if that messes anybody up on the US West Coast. The other idea is splitting this into a spec call and a tooling call. Any thoughts?
00:06:03An attendee: Earlier would be better for me. I have a weekly obligation to pick up my son from daycare, so I always have to leave at 4:30. Another idea could be to alternate every other week: one week at one time, the next week at another. Even if it's not always the same people, there's probably an overlap of two or so who can carry things across. Otherwise some people can never make a certain slot.
00:06:38Kin Lane: I like that, that's a good idea. We'll keep both the spec and the tooling in one call for now, but let's consider splitting as the work continues, or maybe running them back to back.
00:07:01Phil Sturgeon: That makes sense, because some people will want both, but there's going to be a lot of irrelevant stuff. On the tooling side we're getting into the weeds of "we should upgrade to TypeScript 7, but that means changing our module resolution", and spec people don't care about that.
00:07:17An attendee: Nothing more annoying than you TypeScript nerds talking about TypeScript.
00:07:28Kin Lane: I'll start by alternating: next week an hour earlier, and the following week at the usual time. We'll see how the agenda goes, and we can try separate calls, maybe back to back, so people who want both can do both.
We're slowly getting more things up: YouTube, and I haven't got the blog very active, but I'm trying. We got accepted by Open Source Europe as our fiscal host, so we can accept donations now. I'm going to drop $1,000 of API Evangelist money in to prime the pump. Then we have money for technical services, but I also want to figure out how to pay people for their time. If we're doing work, I want a budget, and I want to chase people for more donations. Pavel, this morning: he worked on SAP's Open Resource Discovery (ORD) format, which he put into the Linux Foundation, and he tapped into European Commission money and grants. He said there's a new call that's about to close, and Łukasz from Open Source Europe said they're very good at being an anchor for that kind of money. So I'm going to chase European Commission grants.
As I get the financial foundation set up, put some thought into what would be useful. I want budget for tooling and commercial services, but also project work. I'm looking at you, Phil, and you too, Miguel: if we're doing core work, what little bursts of money would help? $500 here, $250 there, to prime the pump and keep us in the workshop doing the work. Acknowledging we probably can't pay for all projects and all work. So think about it.
00:10:13Phil Sturgeon: There's certain tooling work that's going to take an afternoon. Money helps with things like this: the tool is getting quite close to being done, but getting new versions deployed to npm, with all the right packages released under the right organization, is a fair bit of work. Once it's set up, merging a pull request triggers a new release of every package that changed. Then anyone can send a pull request, we click merge, and a new version comes out. That's the main project for us at the moment. If I'm doing it, I can do that for money; if Jakub's doing it, same. That's the main chunk I can see.
00:11:10Kin Lane: Yeah, that infrastructure work is foundational and needs to be greased well.
00:11:20Phil Sturgeon: The other one is starting the documentation site. Kin, you were talking about a repo where Markdown is taken from the main OpenLint repo and turned into a website. That's another chunk of work, probably an afternoon of concentrated effort.
00:11:46Kin Lane: Scoping these projects, getting the discussion and the issue going: then I can reference it as a budget line item and say we have X for that, or go to Company X and say "this would be a great place to throw some money at us". If we break things into bite-sized chunks, some I won't be able to attach money to, but others I think we can.
I got the starter pages up for the spec: the README, the spec page, and a basic 101 page on the website. They're meant to be temporary, so when people want to come and learn what we're doing, it looks like we have work in progress. But the 101 education page isn't meant to be the docs site; we need a proper docs site. And for the spec: Joost, if you can submit a proposal and start that work formally, a rigorous structure for the spec, the language and everything around it, then we can plan what the site is. Is it the spec repo README? A separate spec site linked from the website? Let's get formal, follow good practices, and I'll let you lead. Just tell me what you need.
00:13:36Joost Farla: Sure. I have some ideas about how I'd shape the formal documentation website for this specification. Let me share my screen.
00:13:57Kin Lane: Oh, and hey, Mike, welcome.
00:14:04Joost Farla: A while back I opened a discussion about principles we need to agree on to make this specification more formal. I didn't attend the last meeting, but I watched it back, and there wasn't really discussion about this, so I'm not sure whether it's agreed or needs a dedicated session. But I took the liberty of sketching out ideas using existing common tooling. It's a prototype, so a lot can be improved, but the idea is a dedicated website on a subdomain of openlint.org, something like spec.openlint.org. I believe OpenAPI has a similar approach, where you can find all versions, including the working drafts.
If we look at a released version (fictional for now), the document looks similar to many specifications, including OpenAPI and Arazzo, which I believe use ReSpec, the W3C tool. I used Bikeshed, which gives a similar result and is very flexible, so you can customize anything. I tried to fit the current specification, which comes from the original Spectral documentation, into a more formal structure.
There's a conformance section that explains how the document is written, what rules apply, what conformance means, and how we do modularization in the specification. One important thing: for a linter, some requirements are about the ruleset (what a ruleset document should look like), and a second part has to specify how a linter should behave. It's interesting to see how we fold that into a single specification.
It explains terminology, and it has a section on the ruleset format. All normative content is written as requirements: concrete "must", "must not" or "may" sentences, which are testable. Every requirement, for example "a ruleset must have at least one of these properties", also has tests. You can expand it and see the conformance tests. It's documentation, so it describes what to test rather than running it; that's a separate conformance suite. The rest is examples and prose, basically the same as the current documentation but combined with the normative parts. There are chapters on documents and on linting, with their own requirements, then the functions, each with a description, an example, requirements and tests. The appendices list all requirements, and all conformance tests grouped by requirement. Each test basically says: if this is the input and I do this, I'd expect this. Like a unit test.
Besides the document, there's the schema, as already published. There's also a registry, a machine-readable version of the specification including the tests, which could be handy for a conformance suite or other tooling that needs to read the spec. And there are conformance test files with input data in JSON and YAML. The working draft is basically the same document with a big "working draft" warning, and it can carry issues inline: open questions about a specific part of the spec, pointing to issues or discussions.
This was purely an experiment, to demonstrate and to have a conversation about whether this is the direction we want to take. So I'm very curious: what do you think?
00:22:00Several attendees: It's amazing. Beautiful.
00:22:04Kin Lane: To your first question, about not much feedback on your discussion: as we're setting the table and getting open for business, I support this: if there's silence and you don't get much feedback, just move forward. Once we're established, we'll want to slow things down and be more thoughtful. But thumbs up. Let's move it into the spec repo, run it on GitHub Pages, link it from the site, and continue the conversation. Miguel, I'll let you chime in, and you too, Andrzej.
00:22:44Miguel Quintero: Thanks, this looks pretty good. I saw your proposal but didn't go too deep. The mechanics of the documentation look good; it's very similar to the OpenAPI spec. My question, taking a step back: if we're going to lint different kinds of documents, say AsyncAPI or Arazzo, are we supposed to extend the rule object, so we can say "I'm linting AsyncAPI"?
00:23:30Joost Farla: There was a separate discussion about document types. Is that what you mean?
00:23:36Miguel Quintero: I'm piggybacking on what you've done here. I saw a ruleset and a rule object, and I'm looking for the mechanism: do we extend the rule object so we can lint A, B, C?
00:23:54Phil Sturgeon: This will be generic, right? We want it entirely generic of document type, I'd expect. This shouldn't even mention OpenAPI. There's a given, which is a JSONPath that operates on whatever JSON document you give it, which could be a Kubernetes manifest.
00:24:32Joost Farla: Exactly. The idea for now is to focus on what it currently is. I think we still have to agree on it, but the first version, whatever number we give it, should be Spectral as it is, as a separate specification. There's a separate discussion, or at least it's on the agenda, about modularizing the specification, and I have a few ideas on that, but I think we should take it up separately. So for now the idea is to document what it currently does, make sure existing rulesets can be tested, and verify that the OpenLint implementation conforms.
00:25:36Miguel Quintero: Basically looks good. To Phil's point, I can see myself using OpenLint for infrastructure work, linting CRDs and the like. Setting the groundwork for that: this is the baseline, the MVP of what works today in Spectral or OpenLint, and here's where you can extend to whatever other documents. Looks good.
00:26:10Joost Farla: Modularization is something I can create a discussion for, if there isn't one already. It's good to have in mind when releasing our first version. If we want to do modules, I think we have to do modules from day one; otherwise we get into trouble in future releases.
00:26:40Kin Lane: Go ahead, Andrzej.
00:26:43Andrzej Jarzyna: Great job, I really like it. I also like that you have the JSON Schema, and what this page shows. I'd go a step further and completely separate the ruleset specification from the tool. I saw there was linting somewhere; I'd keep those totally separate.
00:27:12Joost Farla: There are some rules on how linting should work, and how you deal with parsing a document.
00:27:20An attendee: Or maybe that links over to the documentation for the linter: there's a section, but it's linked from here. But as I understand it, the idea here is to say: if you write a linter that uses these rulesets, this is what you have to comply with. If you want to reuse this ruleset, this is how you need to treat it, how you need to behave when you're using it. That's why I think it's great.
00:28:01Joost Farla: Every requirement has a conformance target, which is either a ruleset, so the document itself, or a linter. It's one or the other.
00:28:15Phil Sturgeon: That's an important distinction, because there will be multiple linters, in theory. If Vacuum wants to become spec-compliant, they'd be implementing it. Currently they implement support for the core ruleset spectral:oas, and we're going to make openlint:openapi and openlint:asyncapi. There'll be some overlap, with each ruleset wanting to be self-documenting, potentially with examples of successes and failures in the ruleset. Regardless of what we do with the core rulesets, there'll be ACME rulesets and whoever else. Hopefully ours will be better specified, because multiple people will be working on them.
00:29:19Kin Lane: This is great. As I said at the beginning, I want to get the table set so we can start having dinner. I propose this gets set up on GitHub Pages in the existing spec repo, and I'll set up the domain. We can continue the conversation once it's published; we don't have to wait, and it'll help people see that we're nearly ready for business. One big question you mentioned: are we 0.1? Are we 1.0? What's our version? For new APIs I always start at 0.1, but this isn't new. It has a lot of maturity behind it, even if it's not our maturity and hardening. What are the thoughts on what version we start with?
00:30:22Phil Sturgeon: On my end, with the code, I'm aiming for 0.1.0, because there are some fundamental missing pieces. The spec and the code don't need to line up, but to explain: 0.1.0 is "I've completely renamed Spectral to OpenLint", mostly a chore. We haven't got the new OpenLint core ruleset yet, so launching OpenLint and requiring you to use spectral:oas would be a bit funny for a version 1. And we're on really old versions of packages, probably with some security issues. So 0.1.0, 0.2.0, 0.3.0 perhaps, then 1.0 within a month or two. I have to jump into the car, so I'll switch to my phone.
00:31:27Kin Lane: Joost, create a pull request for this, and let's have discussions about the subjects on GitHub. Thanks for the work, good stuff.
I love that we're moving forward with that work. We only have 30 minutes left, so I don't want to go too deep; I'm keeping this meeting high level, and there's a lot of good asynchronous conversation. Backwards compatibility: good talk. It sounds like existing rules should work, and there's a certain level of backwards compatibility we won't be able to keep moving forward, because it's much more difficult. There's a good conversation going on about what that means, plus case insensitivity, and a good one on an expression language for custom functions. But some of that goes into the future roadmap. It isn't setting the table, especially document types. We want to get things working as is, and not introduce anything new until the table is set for dinner.
00:33:09Phil Sturgeon: On the code side, I've already made a 2.0 milestone, which holds the bigger changes down the line. The goal is to get 0.1 out within days, then add the building blocks on top of a fully backwards-compatible base, and release version 1 as a fully backwards-compatible thing as soon as possible, with the new core ruleset that has the Stoplight-specific stuff moved out. Version 1 literally exports an object called Spectral, so even if you're using the JavaScript API, you can just switch the package. Then version 2 drops some of the Spectral backwards compatibility. We're not breaking things for no reason; we're making it better as we go, and every change has to bring value, not change for the sake of change.
00:34:08Kin Lane: Mike talked about this in a previous call. Once there's a package, I'm going to swap it into all the tooling I use for my rating systems and so on. I'm a one-person shop, so I'm happy being a guinea pig, and I have quite a few Spectral implementations. I'm happy to swap it in and break my stuff, or ideally it just works. Phil, you should have had an npm invite from me for OpenLint; let me know if not.
00:34:58Phil Sturgeon: I haven't yet.
00:34:59Kin Lane: Let me try again. The npm interface was really wonky. *(Kin re-sends the npm organization invite during the call; the email addresses read out have been removed. Phil updates his npm email, and the invite goes through. Kin also adds Miguel.)*
00:40:39Phil Sturgeon: We've also got the openlint package itself; a very nice Canadian person gave it to us, after a bit of drama. So openlint could be the package you install, a thin layer, with the OpenLint organization holding the other packages and dependencies. Typing less is better: npm install openlint, nice and simple.
00:41:05Kin Lane: That would be sweet. I support that; less is better. Time check: about 19 minutes left. I haven't got my head into the VS Code extension, and it's an important one for me. A lot of the customers I work with are very dependent on distributing rules through VS Code, so it's going to be a big part of the migration package for me and some of my enterprise customers.
00:41:48An attendee: I just want to mention it's not only VS Code; it's IntelliJ as well. Lots of people use IntelliJ, especially in German enterprises.
00:41:56Kin Lane: Agreed. And I think a proper language server (LSP) is where it's at. Anything on the MCP server and API, Miguel? Did you do any work there?
00:42:18Miguel Quintero: Not yet. I grabbed that one, and as soon as I've done the TypeScript 7 work, I'll start thinking about which approach to take: the API first or the MCP first. Phil may have an opinion. I'll get to it soon.
00:42:46Kin Lane: I'm going to jump down to make sure we cover everything. Administration: funding is in place. I'll keep working on the AI enablement and policy; I've done more work there, but it's not ready to publish. I got a GOVERNANCE.md in, at a basic level, based on what I'm used to with AsyncAPI, OpenAPI and others. And we have a list of maintainers and contributors, which I'll actively maintain. Whoever has Git access, which you're all welcome to ask for, is a maintainer, and otherwise you're a contributor if you show up to these calls.
The website: I'm keeping a simple landing page with links. The spec is going to be a separate site now, and we'll link there. The docs, once Phil's ready, will be a separate site too. So it's a simple homepage linking the parts and pieces. I'm not worried about perfect branding out of the gate; I just want all the parts in place and done well.
As I mentioned, I'm breaking things up by baseline of operation: setting the table. What do we need in place to be open for business, with a migration guide? I have quite a few people, some pretty big companies, who don't want to be involved in the spec but are willing to be guinea pigs, use it, and give us feedback on what migrating looks like. So I'm keen on getting the base table set: the website, the spec, the docs, the npm package, making sure it works, and the base rulesets. Then we're off to the races. Then I'll keep organizing what's next, the first new things, and we can start prioritizing in the coming weeks. I'm already organizing some of that based on what people ask me, and skills validation with Markdown is one of the top things people ask about. But getting the npm package and the docs sites up for the spec and the tools is top priority.
Another thing: Mike asked for rules last week. There are some duplicates I have to deal with, but I now have 108 rulesets from actual providers: Adidas and all the ones we know, including the Dutch government. These are rulesets actually set up by the providers. For the aliases work, I pulled the most common JSONPath references, and there's some really interesting stuff. So as we start thinking about how we modularize and work with rulesets, and how we do aliases, if you need other research to inform things, let me know.
00:46:42Mike Kistler: When I look at that page, some of the "view" links can't be found.
00:46:49Kin Lane: There's another build going out tomorrow, so I'll fix the duplicates and a couple of bad links. Give it until Saturday and it'll be in much better health. Something broke while I was at the event. Another piece of research I haven't pulled in yet: I've pulled all the pipelines in public GitHub repos that lint with Spectral, and there are a lot of learnings there, but I don't think we're quite ready for that yet.
That's the high-level recap of where we are: getting the spec stabilized. Thanks Phil, Jakub and Miguel for all the work you're doing. I really feel confident we're going to have something usable here. We can accept donations, and there are lots of other conversations and threads to jump into. Anything else burning that you want to make sure we talk about before next week?
00:48:05Miguel Quintero: Phil, the CI/CD to deploy to npm: is there an issue or a PR for that?
00:48:17Phil Sturgeon: Not currently. I'm looking at it now. It's exactly the same as what it was; the main difference is we don't have an npm token, and I'm making one right now. It'll be interesting to see what the automation does, since I don't think we have any versions tagged, so hopefully it starts at 0.1.0. Once it's going, it's pretty simple.
00:48:50Miguel Quintero: Then I'll piggyback. Once you have it going green, I'll take a look on the side and see if I can help.
00:49:12Phil Sturgeon: Brilliant, thank you, you've been helping with loads of stuff. I want to get 0.1.0 out before we do any more of the TypeScript work, because "rename and fix tests" is literally 0.1.0. Then you'll see a nice changelog come through: new module resolution, TypeScript 7, and so on. But I don't have enough permissions to set up an npm token for the organization. I don't have admin.
00:49:47Miguel Quintero: That was my other point: we should have a service account token, not individual tokens, so we can set up the CD.
00:49:56Kin Lane: Let me know if I can help. Pick me, I'll show up. Is GitHub the best place to talk to you, or the OpenAPI Slack?
00:50:11Phil Sturgeon: The OpenAPI Slack is good for me.
00:50:16Kin Lane: The final things I'm pushing on for setting the table: the npm package is definitely the priority, thanks Phil. I'll wait for your lead on the migration guide, any content or details, and then I can help make it public and clean it up.
00:50:34Phil Sturgeon: I'll give you the Markdown file of it, because it's going to be in whatever docs tool we use, and you can use it however you want.
00:50:44Kin Lane: That's all I need; I'll take it from there. I'm looking forward to the default ruleset, and where we trim things down to. Then I'll start setting out what we need from other rulesets and other formats, both to set the table and for the future roadmap. I want the VS Code extension and the language server in motion to support this. And once the spec pages are up, that's the other key piece. I think that's what we need. Am I missing anything?
00:51:33Phil Sturgeon: No, that's about right. I'm looking for 0.1 to be out today or tomorrow, and 0.2 hopefully by the next meeting, so I can start telling everyone to get rid of all mentions of Spectral, and there's a backwards-compatibility section of a guide somewhere. Also, can I get everyone to agree that we're never going to mention the Petstore? That's my one main requirement for working here.
00:52:02Kin Lane: Well, I want a base set of OpenAPIs and AsyncAPIs, so we need a set of fictional or real businesses: planting trees, train travel, the different ones.
00:52:19Phil Sturgeon: [?] has one. We've also got train travel, and the museum API that Lorna made. There are plenty of good examples around.
00:52:26Kin Lane: We want a nice diverse set, ideally not AI-focused: things that are human, nature and real-world focused. Art, museums, train travel. I want a bicycle one too, because part of my anti-AI rant in Stockholm was that AI is like the automobile. If we'd gone all in on bikes, trolleys and trains early on, we wouldn't be in the mess we're in now with cars. So let's make some good decisions with AI right now.
Anything else? I'm going to call it there and get ready to head home. I love the work Phil and you all are doing; this is awesome. Joost, it's working out. On both the tool and the spec side, I think another week or two and we're off to the races. Thank you, everybody.