Office Hours · 12 November 2026
OpenLint Office Hours #7
Summary
The seventh OpenLint office hours agreed to start version 2 of the specification alongside version 1, and asked for the project’s structure to be written down before it gets harder to change.
Status. [email protected] is on npm with everything from Next Release Considerations (#41): the rulesets split into packages (#42, Phil Sturgeon) and the opt-in schema cache from SAP’s Open Resource Discovery team (#39). The next releases stay on housekeeping. conformance.openlint.org now runs the specification’s 240 conformance tests against OpenLint, Spectral, vacuum, the IBM OpenAPI Validator and Insomnia, plus interop cases for Redocly. Miguel Quintero cut the first version of the MCP server (#13) in its own repo; it moves into the org once he has admin access.
Rulesets and versioning. Kin will write a blog post and migration guide section on the new ruleset packages: how they work with npm and Git, and what the default ruleset includes. The split changed the default ruleset but shipped as a minor release, so the project needs clear expectations for ruleset versions, separate from toolbox and spec versions. A process for adding new formats and industry rulesets is also needed.
Project structure. Joost Farla asked for written conventions on how the project is organized: what goes in the monorepo, what gets its own repo or subdomain, and how pull requests, approvals and merge rights work. Kin will draft an ops and governance map, starting small, including which tools are core and which are add-ons (the MCP server and the VS Code extension are the first cases), and a weekly visual of the moving parts.
Specification version 2. Dimitri van Hees and Joost are drafting the next version in discussion #39. Version 1 is what came from Spectral; version 2 can take good ideas from vacuum and others, such as rule categories and howToFix, and new formats such as RDF, which the Dutch government is waiting for. Joost will add version 2 drafts to the specification site and sort open issues into version 1 and version 2: anything breaking goes to version 2. New properties can start as x- extensions. The toolbox will need a matching 2.0 to try them. Kin noted that the spec should still say whether a rule allows deterministic or AI-generated fixes. He’ll add one page showing version 1 and version 2 of the spec and the toolbox, with the roadmap for each.
Conformance. Joost pointed out that the spec’s CI and the conformance dashboard now both run the conformance tests. The tests stay in the spec as the source of truth, and the runner should be consolidated: the spec’s CI checks OpenLint, and the dashboard adds the other tools.
Performance. With #39 merged, the next step is benchmarks on large documents and large rulesets. Kin argued that a ruleset should flag very large OpenAPI documents in favour of modular ones.
Maintainers. Phil leads the toolbox, Joost the spec, and Kin is the administrator. Each tool will get its own lead maintainer, starting with Miguel on the MCP server. Maintainers are expected to communicate when they step away, and every role should have a backup.
API Days Paris (1–3 December) is the official launch. Kin has three talks that include OpenLint and plans three or four press releases: the toolbox, the spec, possibly the MCP server, and European government. Dimitri will give a quote and suggested OpenLint stickers; Kin is considering a modular logo that pairs with each format’s logo. Grant proposals are due in December.
Agenda and discussion on GitHub · Watch on YouTube
Transcript
00:00:00Before the start: Small talk about time zones and daylight saving while people join. Kin starts recording and welcomes some new faces, including Pavel.
00:01:30Kin Lane: It feels like we're building momentum. We've been open for business and ready, but we're lighting up some new conversations, and I have meetings planned for API Days Paris. Anything anybody wants to add to the agenda before I dive in?
00:02:20Miguel Quintero: Thanks, Kin. This morning I cut the first version of the MCP server. I put it on the issue and left the issue open. It's very raw and very new; I'm still testing it. I don't have admin permissions on the OpenLint org, and based on Jakub's feedback, rather than a separate package in the monorepo, it's a separate repo that brings in the OpenLint core packages. So that's what I did, taking your feedback and his into account. I'll share it in the chat. Right now there's no packaging; you just download the release and run it locally. Before people start filing defects and comments, I'll wait until I have admin access, move the repo into the org, and then we can have all the feedback in one place, like the other projects.
00:03:50Kin Lane: You should have admin access; I'll make sure you do as soon as we're done here.
00:04:10Kin Lane: We have some new folks, so I want to be a little more formal about what we're doing and why. This is the OpenLint office hours. We do this every week, and we're sticking with this time for now. We're still thinking about splitting it into separate calls for tooling and for the spec, so if you have strong feelings about times, let me know. Most of our audience is in Europe, so earlier is better.
We have a complete fork of the Spectral CLI, which is now the OpenLint toolbox. And Spectral, which wasn't a spec, just a config file, is now a spec called OpenLint. Some of us have already swapped out the tooling, and it works. We're continuing to stabilize and clean it up, and slowly getting more organized.
00:06:00Kin Lane: A quick recap. You can always find the office hours recordings in the meetings section of the website, and I post the recording at the bottom of each agenda issue before I close it and start the next one. I put up a first draft of the conformance tooling, which we'll get to. I merged a handful of clean-up pull requests on the spec, mostly linking the open questions to their issues on GitHub, with no real changes. We have the rules site, which aggregates the default rulesets in the toolbox, and I'm starting to add rules from other work I'm doing. I added a couple of blog posts this week, preparing for API Days Paris.
00:07:00Kin Lane: And we rolled over to 1.2 on npm. That got in the latest changes: splitting the ruleset packages, and the performance pull request SAP submitted. So everything we had queued in Next Release Considerations is in the latest package, and we can start accumulating the next fixes. We still want to stick to housekeeping: cleaning up Stoplight-isms, making things more modular and reusable. We're going to be really cautious about anything new. We want the spec, the rulesets and conformance aligned before we do anything new. But you're welcome to submit an issue or start a discussion on anything, and we'll slowly get the roadmap in order. Any comments?
00:08:30Kin Lane: Diving in. Phil, who isn't here, did more work on breaking up the rulesets and how the tooling works around them. I don't fully grasp it all yet. I'm working to align it with the rules catalog and the GitHub repos, because I'm really interested in stabilizing what we have. I'll write a blog post about it, and add to the migration guide: how the new modular rulesets work, how they work with npm and with Git, and how the default set works.
We're going to have to get our versioning act in order for rulesets: what are the expectations for ruleset versioning, and how do they line up with the toolbox? That's different from the spec version, which is another beast. I don't have strong opinions, except that we have to communicate. What was just released was breaking, but it shipped as a minor change because it's a ruleset thing, and things are looser around rulesets. It would be nice to be more formal and structured.
00:10:00Kin Lane: I'm also working on the next wave of rulesets. We have OpenAPI, AsyncAPI and Arazzo, and I have a long list of other formats I want in. We need a process for that too: what gets in, what matters, not just formats but industries. Anything on rulesets before I move on?
00:10:40Joost Farla: One general remark. I feel we need some kind of project architecture, where we set policies or conventions for how we organize things: when does something go in the monorepo, what justifies a separate repo, what justifies a separate subdomain on openlint.org. We're creating a lot, which is a good thing, but now that we're stabilizing we should pay attention to this. We can change it easily now; it will get harder and harder afterwards. It also relates to security: how we deal with pull requests, approvals, merge rights and so on. It's basically governance, but also agreement on how we organize and structure our stuff.
00:12:10Kin Lane: Agreed, 100%. I'll commit some cycles to it, because I'm managing it but also contributing to the chaos. Early on I intentionally wanted a little chaos, because I didn't want to stand in people's way. But we don't have many formal processes, so we need ops as well as governance: how do we operate? Miguel can speak to this from the OpenAPI Initiative. When you try to move anything forward there, there are a lot of processes in place, and the people responsible for them left, and you have to work out how it works. So ops and communication are key. How do we create a repo? Which repos are part of the core stack? Thinking of Miguel's work and some of mine: what's core, and what's an add-on tool? The VS Code extension is in someone else's repo; should it be brought in? We need a diagram and some process, even if some areas stay looser.
00:13:30Joost Farla: We can start small and simple. We need to keep some flexibility, but we also need some agreements.
00:13:40Kin Lane: Agreed. And there are external things. We asked the AsyncAPI team to help manage their rulesets and haven't had a response yet; I'll bring it up with Arazzo and OpenAPI as well. Do those repos live in our org, or in the specs' orgs? Miguel's tools, my tools in API Commons: do we want them in here? Our ops and infrastructure should acknowledge that we're a special kind of spec, and we need to be interoperable with other specs. Good call-out, thank you, Joost.
00:14:40Kin Lane: Next, Dimitri posted discussion #39, where he and Joost are looking into the interoperability issues, which I think have to be answered as we move forward with the spec itself. Anything you want to jump in on, Dimitri or Joost?
00:15:10Dimitri van Hees: I'm investigating it as well. I almost missed the time today because I was working on updates on the differences between vacuum and Spectral, or OpenLint. There are definitely features in vacuum that we'd also like to have, like a category: you add a category to a rule and group rules that way. We actually need that in the Dutch government. We have the API Design Rules standard, and some of its rules are a group of OpenLint rules. So there are vacuum-specific features in the syntax that we could use in OpenLint, but then it should be in the next version. Some are really specific, like the auto-fix function. My opinion is that it shouldn't be in the spec, because that's something tooling fixes; we should use an extension for that.
I don't want to get into detail right now, but I think it's good to start drafting the next version of the OpenLint specification. We can say the current version is basically Spectral, and it's backwards compatible with Spectral. But if we want to broaden it, we also need different formats, like RDF, and we're already working on that because the government told us to. They're waiting for it. So apart from our own roadmap, we're already thinking about it. I think it's a good idea to have a draft of the next version in place, where we can discuss it and work on it together, instead of us having a separate repo again.
00:18:00Joost Farla: I think we can work in parallel on the next version of the spec already. It also makes it easier to discuss things like how tooling is expected to recognize the OpenLint format. I can start adding version 2 drafts on the specification site, because the current approach already took that into account. Then I can separate the issues: which stay in version 1 and might need to be addressed there, and which are breaking and have to move to version 2. I can spend some time analyzing that and creating a new version 2 spec. Then we have two major versions in parallel, which is not a bad thing, I guess.
00:19:20Kin Lane: No, I think it's a good thing. It'll be a release valve: is this breaking or not? If it's not, it goes in the current version; if it is, it goes to 2, and we have that discussion there.
00:19:40Joost Farla: We need to make sure we keep them synchronized, for the things we do in version 1.
00:19:50Kin Lane: I think we agree that, because we can use extensions, in 2.0 we could start almost everything as an extension, as new properties like categories. I wish Dave had done that with vacuum, x-category and so on, as part of a spec, but there wasn't that process, so I get why Dave did what he did. We could push the spec forward with x- properties and formalize them, have the next iteration of the tooling use them, and keep conformance in line in parallel.
00:20:30Dimitri van Hees: Yes, but some vacuum-specific syntax could also be a good idea. The fact that it isn't in Spectral doesn't mean it's a bad idea. Take howToFix, which is different from the documentation URL. We've used the documentation URL for our how-to-fix URLs because it isn't in the spec, and I think it's a really good idea for OpenLint to support how-to-fix. We shouldn't make everything an extension just because it wasn't in the original Spectral spec. I'd like a place to discuss that, without waiting for formal next versions. Maybe other tools have extensions too, because OpenLint and Spectral didn't satisfy their needs. A draft version lets us explore what would need to change in current tools. We could even open a pull request on vacuum: if you use this draft version of OpenLint, it's only a minor change in your software and it will be compatible. It's easier to discuss and play around with if a draft version is available. That's my whole point.
00:22:30Kin Lane: Agreed. Get it going, Joost. We're going to need a next iteration, a 2.0 version of the toolbox, to start playing with some of this. And we need a better way of defining the lines between what is the spec, what is our tool and what are other tools. JSONPath Plus versus JSONPath versus XPath is a critical example: is it the spec that's broken, or a tool that supports a different set of libraries? Those are tooling questions.
On fix-it, Dimitri, I agree fixing should be tool-based, but we have an issue and a discussion open on it, and I've done a lot of work on this in my forks of Spectral at different companies. The spec still needs some configuration for that behaviour, like whether a fix should be deterministic or non-deterministic. That should be set as part of the rule or the policy: on this property we allow deterministic fixes only, we don't allow you to use AI, or vice versa.
00:23:50Dimitri van Hees: Sure, as long as there's a place to discuss it. We extracted the spec out of Spectral, and I think Spectral was never intended to be a formal specification. Now we're creating a formal specification. So we have spec 1.0, extracted from Spectral and from code: extensions, for example, were allowed but hidden in the code and undocumented, and now that's in the spec. Just put me and Joost on that issue and we'll come up with a draft. We definitely want to do that, and then we can discuss it.
00:24:50Kin Lane: Are we in agreement, Joost, that what came from Spectral, what we have in the spec repo now, is version 1, and what we're going to talk about now is version 2?
00:25:05Joost Farla: Yes.
00:25:10Kin Lane: OK. As I stabilize the versioning for the rulesets alongside the tool, I want a roadmap that shows it, and I want a single page on the website that says: here's the current, ready-for-business version 1 of the toolbox and version 1 of the spec, with the issues and roadmap for each; here's version 2 of the spec and version 2 of the toolbox. Then I can link to it and clearly tell people where the work is. Playing circus ringmaster here. I'm stoked on this spec. Dimitri and Joost, get to work.
00:26:00Kin Lane: I was starting to feel uneasy about what's what and where things are, so I fired up conformance.openlint.org, linked off the home page. It has OpenLint, Spectral, vacuum, IBM and Insomnia. I've taken all of Joost's conformance tests from the spec and started running them here, and each result links to its test. I'm trying to get more detailed about why things are working or not. If you look at vacuum, we need to keep digging into why it doesn't support certain things. It gives me more awareness of how things work across tools. We'll keep adding tools, and tests as needed.
00:27:20Joost Farla: How do you think about the current way we organize these conformance tests, the separate JSON files with the machine-readable test input?
00:27:50Kin Lane: The spec should be the source. The repo behind conformance has the ones used in the tests.
00:28:20Joost Farla: What you've built for the conformance website is something new, because the specification's CI pipeline also had some minimal conformance testing, against OpenLint at least, and Spectral, I believe. Maybe we have to see how we can consolidate that, so we don't have two separate places doing the same conformance testing.
00:28:50Kin Lane: The purpose of conformance was the visual dashboard, to see tools side by side, which the spec doesn't have. I'd say the spec pipeline should be the source of truth, not the conformance pipeline. Everything the dashboard runs should be generated from the spec.
00:29:20Joost Farla: The point I want to make is that we now have two implementations that interpret the test input files, run the conformance tests and produce a result. Maybe we need to integrate them, so we have one implementation used both in the spec's CI pipeline and for generating the conformance page.
00:29:45Kin Lane: I'm fine with moving the conformance page in there. But this is about the spec itself; is having other tools in there contrary to the spec? That was my only reasoning: a conformance suite is multi-tool, outside the spec and outside our tools.
00:30:10Joost Farla: I agree on that. The only thing is we now have two code bases doing the conformance testing and generating results. If we make it more generic, we can use it in the CI pipeline, where we only test OpenLint and maybe Spectral, and also, with other input parameters, to generate the conformance page. We can take it off this meeting, but I think we have to consolidate somewhere.
00:30:50Kin Lane: I'd say the GitHub Actions YAML should be made modular, so the spec's conformance run covers just OpenLint, because that's conformance with our tool, and the multi-tool dashboard has that baseline plus the add-ons for the other tools. Let's take that offline.
00:31:30Kin Lane: So that's the core of the spec right now: continued ruleset work, the next version of the spec, 2.0, and the conformance suite and dashboard. We'll work on that GitHub Action. And adding what Joost said: an infrastructure and ops strategy, because we can't see the pieces on the chessboard. And on changelog and communication: I can't adequately tell people where to go to make changes and submit things. That needs to happen.
Anything else on trust and compatibility, the theme today? Joost's point about stabilizing our platform and ops is a big piece of trust, and how we communicate is another. The conformance suite, stabilizing the spec, having a version 2.0: that's all trust, so people see active changes to the spec, active changes to the toolbox, and a future vision on the roadmap. Dimitri said last time that having it be an active spec matters, and SAP said responsiveness to their changes matters. Anything else people want to add, so we're building trust the right way?
00:33:40Joost Farla [?]: No, I think it's a good baseline. I think we're doing good.
00:33:50Kin Lane: I think we're doing better than the Stoplight and SmartBear team.
00:34:00Kin Lane: Moving to the toolbox. Building off that last piece, #39 from SAP is merged, which opens up performance. Beyond conformance and quality, I'd like to start getting benchmark numbers: how fast things are, and how it handles large rulesets or large OpenAPI documents. That was one of the catalysts for vacuum existing in Go: Dave was processing very large OpenAPI files.
Along those lines, I have strong opinions that you shouldn't have large OpenAPI files; you should have modular OpenAPI files, and modular rulesets. At Postman we had to increase the OpenAPI import size because Stripe refused to break down their OpenAPI, and it was massive. I think how many operations you have should be a default rule. We'll see if I get my way.
00:35:30[?]: In general I agree that big OpenAPI specs cause more problems than they help with.
00:35:40[?]: I agree with both of you. If you want one module or 10,000 modules, go for it. Let's start with modules.
00:36:00Kin Lane: Agreed. But I'd still like performance benchmarks from day one. Performance was clearly an issue for SAP, so I want benchmarks alongside conformance and quality.
Miguel already talked about the MCP server. We'll get you admin rights, and let's get some feedback on it. We need to think about what's core tooling and what's add-on tooling. Jakub has said an MCP server probably should be part of core, or an add-on. These are really important conversations. In the OpenAPI Initiative, one of the things that broke down, and why AsyncAPI never made it into the OpenAPI Initiative, was that people couldn't agree on what's core and what's tooling. OpenAPI doesn't allow tooling into the charter. So in our ops and infrastructure map we need clear boundaries: what's a tool, what's a core tool. Our goal is to make these really modular, plug-and-play Lego bricks, similar to how OpenAPI works across SIGs, which were created to relieve the technical steering committee and gave us Overlays and Arazzo. Because we're a modular, multi-format, multi-spec tool, we have to put thought into this. I'll start drafting. The MCP server is a good first test, and the VS Code extension is another: are they core or add-ons?
00:38:40Kin Lane: Error messages: there's work going on standardizing and cleaning up some of the wacky stuff; chime in if you have opinions. Ruleset discovery order: which order rulesets execute in, with modular rulesets; there's some wonkiness there. And the VS Code extension: I'll dive back in. Like Miguel's MCP server, I want the maintainer to bring it into the org, but it's a tool, so how do we maintain it?
Another aspect, and Joost bringing this up is timely: what happens when someone goes away or stops maintaining a tool? I don't want to be the person who always takes in the orphans, which is how I feel about Spectral, or OpenLint. I took it in as an orphan because I saw a problem, but now it's a first-class project. How do we make sure the satellites around it don't become a problem?
00:39:50Kin Lane: On the spec: 2.0, let's do it. The conformance tests are in place, and I'll align further with the spec's conformance tests. There are many other open questions and issues on the spec that need conversation. They're all linked from the spec. Please dive in; some I don't fully grasp, and I'll make the time too.
00:40:20Kin Lane: Maintainers. Part of the org, ops and governance Joost mentioned is that I'll slowly formalize who the maintainers are. Phil is really the lead on the toolbox. Jakub and Miguel have been contributing there, and others are sending PRs, but Phil's the core maintainer. Joost is core maintainer on the spec. And I'm the circus ringmaster, lead and administrator. So Phil, Joost and I are the three top-level roles, with maintainers within each group. As we work out the tooling structure, each tool will have its own lead maintainer; Miguel is lead on the MCP server.
We'll come up with a process for checking in with maintainers. If you contribute a tool and you're a maintainer, there's an expectation that you show up, within reason; we all have lives and work. The expectation is that you communicate: I'm away for a month, or I'm burnt out, can you take this. I'll be honest: I've had three high-profile burnouts on specs, and I burnt out twice in leadership at the OpenAPI Initiative. I'll try to be honest as ringmaster, but my goal is to bring other people in: Dimitri and the Dutch government, the European Commission, Open Source Europe, so I'm not the only ringmaster. Same for Phil and for you, Joost: I'd love a plan B for everybody. I'll bring maintainers up as a regular administrative item.
00:43:30Kin Lane: API Days Paris is in three weeks, and it's the official launch. We're already open for business: we've had a blog post, the package is on npm, we have a spec, and we're talking about version 2. Paris is the official coming out. I have three talks, and all three will have an OpenLint portion; one is the opening keynote for the Europe API government track. If you're doing a talk that mentions OpenLint, let me know so I can include it in the storytelling.
I'll have three, maybe four, press releases staggered around the event: the tool, the spec, possibly the MCP server, Miguel, which would be a good signal that we're new and AI-leaning, and one on European government. One of my talks is about the state of European government on APIs and agents, with OpenLint as a centerpiece. This crowd is very Europe-centric, and I'm positioning OpenLint, as part of Open Source Europe, as governance.
00:45:00Kin Lane: Thank you, Dimitri, I'll make sure you're on my list and get a quote from you. I'm still looking for launch partners, and people and companies to weave into the stories.
00:46:40Dimitri van Hees: If we have a logo, we can order stickers, because we're also ordering new laptop stickers for our government developer portal. We could directly order some for OpenLint too.
00:47:10Kin Lane: What if our logo were modular, so you could bundle it with the OpenAPI logo, the Arazzo logo, every format, and have multiple stickers? OpenLint plus Arazzo. I'll work on that. Good idea, Dimitri. Bye, Miguel.
00:47:40Kin Lane: Additional funding. I have several grant proposals, a couple due by December, so I want a standard set of projects to point to. That's why what Joost said about getting our projects and operational infrastructure in order is key for me: I need grant money for this, grant money for that. Dimitri, per your email last week, I'd love to keep checking in with you and your standardization board. There will be interesting conversations at API Days, with the German and Italian governments there, on how to go after grants and European Commission funding, and on how you're using OpenLint in your cornerstone role. Having IBM, SAP and some startups here gives us credibility.
00:49:00Kin Lane: Next Thursday is the next one, closer to API Days. I'll work on the infrastructure and ops visual. To be honest, yesterday I had trouble understanding everything that was happening. Part of what Joost asked for, and what we talked about with version 2 versus version 1: we need a visual that's updated every week, or I'll lose track of the moving parts. I come out of this meeting pumped, do a lot of work Thursday and Friday, come out of the weekend not remembering anything, and on Wednesday morning go, oh, I have to get the agenda together. A visual plus the outline from the previous week will help me keep being ringmaster without burning out.
00:50:40Kin Lane: I'm super stoked on 2.0; I think it's going to be huge. We've got most of the housekeeping done and a baseline with 1.2 on npm. We're open for business. The spec is a spec, even with all its open issues. We have a spec and a tool, and we're in good shape to launch at API Days. The roadmap for the current 1.0 spec and tool, plus opening up the conversation around a 2.0 spec and tool, is where we'll get people excited about what we're building. Enjoy the rest of your week, don't work too hard, and see you next week.