Spotlight Spec
The Spectral ruleset format, specified.
Spectral rulesets are how a great many organizations express machine-readable API governance — including national governments, whose mandatory design rules are written as rulesets. The format has never had a specification. It exists as configuration for one linter. This is the work of turning it into something an independent implementation can point at.
Status: draft, and honest about it
What exists today is a good description: a written document covering the whole format, and a single self-contained JSON Schema (draft 2020-12) that validates a ruleset. Both were derived from the reference implementation's own internal meta-schemas and verified against real-world published rulesets.
What does not exist yet is a formal specification — normative wording, a conformance section, and a versioning policy with references that keep working. Those are different things, and the gap between them is the difference between documentation and a standard. That gap is the roadmap, and it is open work.
Versioning
Proposed
Numbered versions, a clear line between what is stable and what can still move, and references that keep working — so a document that cites this format in five years still resolves to what it cited.
The proposal →Conformance
Not written yet
No compatibility claim between any two engines can be adjudicated today, because there is nothing to adjudicate against. A conformance section and a public test suite are how that stops being true.
The plan →Why this is separate from the linter
The rules and the tool that runs them have always shipped as one thing, and that coupling is the failure this repository exists to fix. When the linter stops moving, the format stops moving with it — and an organization's governance rules are usually the most durable thing an API program produces. They outlast the CLI, they outlast the vendor, and they often outlast the APIs they govern.
So the rules stand on their own: specified, independently versioned, portable, and implementable by anyone. The reference implementation — Spotlight, a fork of Spectral — stays aligned with this document rather than the other way around. Other engines are welcome and actively wanted, including vacuum, whose author deliberately refused to fork the format when he rewrote the engine in Go. He was right to. A written specification with a public conformance suite is precisely what lets several engines coexist honestly instead of drifting apart on undocumented behavior.
Who decides
Right now, one person — which is the largest risk to everything above, and not a state of affairs worth defending. A format a national government depends on should not have a bus factor of one. The governance page reads how OpenAPI, AsyncAPI and JSON Schema govern themselves, takes what is worth taking, and proposes something deliberately small — built to grow in stages triggered by facts rather than dates.
Co-maintainers are welcome and actively wanted. The bottleneck is not a shortage of process. It is a shortage of people with the right to say no to me.
This needs standards people
Writing a good description is not the same skill as drafting a specification. If you do normative wording, conformance clauses, versioning policy, or governance for a living — or you depend on this format and want it to be citable — there is real work here.
How to help → Governance Open issues