You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Notes from the weekly office hours held Friday 14 August 2026, 10:00 AM Eastern.
Present: Kin Lane, Phil Sturgeon. Regrets: Frank Kilcommins (API Days travel), Jakub Rożek.
1. The thing we keep circling: spec vs. tooling
The question that framed the whole call:
How do we segment between the spec and the tooling? I want to keep it pretty clean and make
sure we're focused on the spec — but the tooling always comes into it.
We did not resolve it. But naming the components out loud got us most of the way to a working
map, and that map is the useful output of this session.
The open question raised on the call and not yet answered in the document: where do the
industry rulesets sit? OWASP, FHIR, FIRE — is "industry" a dimension of the model, or is it
just another custom ruleset that happens to be well known? We have spec, we have format, and
then we have this third thing with no agreed home.
Related, from client-side experience: the two things people actually mean when they say
"governance" are (a) emulate a vendor — "give me the Adidas one, give me the Microsoft one" —
and (b) the experience — this ruleset is for docs, this one is for security, this one is for
mocking, this one is for testing. Whatever layering we land on should be able to express both.
2. Aliases, and getting off JSONPath
The clearest piece of agreement on the call.
Aliases should be elevated out of the core ruleset and into their own namespace — their own
space that any ruleset can point at. That does two things at once: it makes the aliases reusable
across rulesets instead of trapped in one, and it gives us a route to abstract JSONPath away
entirely for people who want that.
JSONPath hating is one of the go-to criticisms of people who are not into using Spectral.
Which makes this a design fix and a positioning fix in the same move. Corresponding roadmap
items in the document:
Move aliases for OpenAPI to the OpenAPI format to enable JSONPath-free rules across more
rulesets.
Switch all examples and documentation over to the alias-based routes.
3. Roadmap
Straight from the working document, lightly annotated.
Bring back auto-detection of OpenAPI in the CLI without a config file.
Move aliases for OpenAPI to the OpenAPI format, to enable JSONPath-free rules for more
rulesets.
Switch all examples and documentation to use these alias-based routes.
Build a new OpenAPI ruleset without the Stoplight-specific rules.
Create a compatibility layer for spectral:oas.
Improve documentation for spectral-core for people who do not want the CLI experience.
Summaries and ratings — how well are you doing, not just what did you get wrong.
That last one is worth pulling out. Every linter in this space tells you what you broke. Almost
none of them tell you where you stand. It is a different product surface, not a nicer error
message, and it is the item on this list most likely to matter to the people who buy governance.
4. The new default OpenAPI ruleset
The design brief is deliberately narrow: a ruleset that focuses entirely on the core purpose,
stripped back to basics rather than to a vendor's product needs.
Two concrete calls captured in the document:
Drop info.contact.
Require tags.
And the migration path: spectral:oas and spectral:aas survive as an optional compatibility
layer carrying the assorted Stoplight-specific rules, so nobody's existing setup breaks — they
just stop being the default.
Also on the list, and not controversial: the telemetry has to come out. It is at the top of
the carry-over pile from the upstream backlog.
5. Investigations
Open questions from the document that need someone to actually go and look:
Simplification. What can be simplified in the tooling now that this is no longer primarily
Stoplight Studio with a CLI tacked on the side? A lot of the shape of the codebase is a
consequence of a product that is not the product any more.
JSON Ref bundlers. Investigate alternatives and use the best appropriate one rather than
a vendor fork.
Fixing. Can this be done with a custom JavaScript callback per rule, or does it want a
DSL? How do Speakeasy and Vacuum do it, and can we align with them? Do they support custom
rulesets doing this, or only their own core rulesets? Auto-fix carries its own vocabulary and
probably needs to be treated as its own thing rather than bolted onto rules.
On (2), a mission-level statement from the call that ought to govern how we answer it:
Let's not fork things unnecessarily. I know it's in our DNA — we're forking Spectral — but as
far as libraries are concerned, let's stabilise them.
6. Not just OpenAPI
A recurring theme, and a gap between what the tool does and what people think it does. It already
runs against APIs.json, GitHub Action YAML, and anything else you point it at — but OpenAPI
remains what everyone assumes it is for. Worth deciding whether we correct that perception
deliberately or let the alias work do it for us.
On Arazzo specifically: people are genuinely starting to build against it, and the read from the
call is that it is right on the cusp. fork:arazzo is already in the component list.
One new input: a request to rename the CLI to tools or toolbox, on the grounds that it is
not always used in a CLI context. Recorded, not decided. It reinforces the existing position that
the specification and the tooling may need separate names rather than one name stretched over
both.
Action: Phil to put some thought into the name before the next session.
8. Funding and home
Mechanism only here; nothing is committed.
Open Collective is the funding vehicle being pursued, and is
recorded in the working document under funding.
API Commons is to be stood up as a nonprofit as an interim home for the specifications and
tooling — explicitly a place for this to live until the community decides what it wants to do
with it, not a claim on it.
Due diligence to be written up on the permanent home: Linux Foundation, OpenAPI Initiative, or
standing on its own for a while. Pros and cons, in writing, rather than vibes. See Where does the specification live permanently? #8.
The immediate goal is unglamorous and load-bearing: the ability to receive money and pay
people. Today there is nothing to send money to, which means every contribution is charity.
9. Cadence
Office hours stay weekly, Fridays, 10:00 AM Eastern, rolling — whoever can make it, makes it.
The point is to keep asynchronous momentum going in the repo between calls, not to gate progress
on attendance. Details and calendar link in #18.
Actions
Phil — name; flag anything missing from the roadmap document.
Kin — flesh out the working document with links; Open Collective; write up the home
due diligence; keep pulling in community and vendors.
Open to anyone — where do industry rulesets (OWASP, FHIR, …) sit in the layer model?
Notes from the weekly office hours held Friday 14 August 2026, 10:00 AM Eastern.
Present: Kin Lane, Phil Sturgeon.
Regrets: Frank Kilcommins (API Days travel), Jakub Rożek.
1. The thing we keep circling: spec vs. tooling
The question that framed the whole call:
We did not resolve it. But naming the components out loud got us most of the way to a working
map, and that map is the useful output of this session.
Components as they stand today
oas2,oas30,oas31), AsyncAPI (asyncapi2)spectral:oas→ compatibility layer,spectral:asyncapi→ compatibility layer,fork:openapi,fork:asyncapi,fork:arazzoThe open question raised on the call and not yet answered in the document: where do the
industry rulesets sit? OWASP, FHIR, FIRE — is "industry" a dimension of the model, or is it
just another custom ruleset that happens to be well known? We have spec, we have format, and
then we have this third thing with no agreed home.
Related, from client-side experience: the two things people actually mean when they say
"governance" are (a) emulate a vendor — "give me the Adidas one, give me the Microsoft one" —
and (b) the experience — this ruleset is for docs, this one is for security, this one is for
mocking, this one is for testing. Whatever layering we land on should be able to express both.
2. Aliases, and getting off JSONPath
The clearest piece of agreement on the call.
Aliases should be elevated out of the core ruleset and into their own namespace — their own
space that any ruleset can point at. That does two things at once: it makes the aliases reusable
across rulesets instead of trapped in one, and it gives us a route to abstract JSONPath away
entirely for people who want that.
Which makes this a design fix and a positioning fix in the same move. Corresponding roadmap
items in the document:
rulesets.
3. Roadmap
Straight from the working document, lightly annotated.
rulesets.
spectral:oas.spectral-corefor people who do not want the CLI experience.That last one is worth pulling out. Every linter in this space tells you what you broke. Almost
none of them tell you where you stand. It is a different product surface, not a nicer error
message, and it is the item on this list most likely to matter to the people who buy governance.
4. The new default OpenAPI ruleset
The design brief is deliberately narrow: a ruleset that focuses entirely on the core purpose,
stripped back to basics rather than to a vendor's product needs.
Two concrete calls captured in the document:
info.contact.And the migration path:
spectral:oasandspectral:aassurvive as an optional compatibilitylayer carrying the assorted Stoplight-specific rules, so nobody's existing setup breaks — they
just stop being the default.
Also on the list, and not controversial: the telemetry has to come out. It is at the top of
the carry-over pile from the upstream backlog.
5. Investigations
Open questions from the document that need someone to actually go and look:
Stoplight Studio with a CLI tacked on the side? A lot of the shape of the codebase is a
consequence of a product that is not the product any more.
a vendor fork.
DSL? How do Speakeasy and Vacuum do it, and can we align with them? Do they support custom
rulesets doing this, or only their own core rulesets? Auto-fix carries its own vocabulary and
probably needs to be treated as its own thing rather than bolted onto rules.
On (2), a mission-level statement from the call that ought to govern how we answer it:
6. Not just OpenAPI
A recurring theme, and a gap between what the tool does and what people think it does. It already
runs against APIs.json, GitHub Action YAML, and anything else you point it at — but OpenAPI
remains what everyone assumes it is for. Worth deciding whether we correct that perception
deliberately or let the alias work do it for us.
On Arazzo specifically: people are genuinely starting to build against it, and the read from the
call is that it is right on the cusp.
fork:arazzois already in the component list.7. Naming
Carried over, still open — see #7.
One new input: a request to rename the CLI to
toolsortoolbox, on the grounds that it isnot always used in a CLI context. Recorded, not decided. It reinforces the existing position that
the specification and the tooling may need separate names rather than one name stretched over
both.
Action: Phil to put some thought into the name before the next session.
8. Funding and home
Mechanism only here; nothing is committed.
recorded in the working document under funding.
tooling — explicitly a place for this to live until the community decides what it wants to do
with it, not a claim on it.
standing on its own for a while. Pros and cons, in writing, rather than vibes. See Where does the specification live permanently? #8.
people. Today there is nothing to send money to, which means every contribution is charity.
9. Cadence
Office hours stay weekly, Fridays, 10:00 AM Eastern, rolling — whoever can make it, makes it.
The point is to keep asynchronous momentum going in the repo between calls, not to gate progress
on attendance. Details and calendar link in #18.
Actions
due diligence; keep pulling in community and vendors.
Related: #1, #2, #7, #8, #18.