There is a new Rules section on APIs.io, and it exists to answer one question I have been asked for years and could never answer with data: who actually publishes the rules their APIs are designed to? Not who has a style guide in a wiki, and not who lints in CI behind the firewall. Who writes the rules down as a Spectral ruleset, serves it where anyone can read it, and puts their name on it. The section holds 6,192 rulesets across the catalog, and the first thing it does is tell you which of them the provider wrote.
Four kinds of ruleset
Every ruleset on the page is labelled with who made it, and the groups are listed in a fixed order so the real ones come first:
| Group | Rulesets | Providers | What it means |
|---|---|---|---|
| Published by the provider | 108 | 95 | The provider wrote it and serves it, or it was fetched verbatim from where they publish it |
| Derived from the provider’s contracts | 66 | 61 | My pipeline read the conventions a provider’s OpenAPI already follows and wrote them down as rules. The provider never published them |
| Generated by API Evangelist | 4,515 | 3,490 | Written by my tooling as a starting point a provider could adopt. Not something they publish or enforce |
| Authorship not recorded | 1,503 | 1,072 | Built before the provenance field existed. Read as derived, never as the provider’s own |
Ninety-five providers, out of 28,834 in the catalog, publish their design rules. A third of one percent. I expected it to be small, and I still find the number striking, because the Contract Governance facet of the Kin Score has been asking for exactly this artifact since the rubric began, and the companies that run a ruleset internally are a much larger group than the companies willing to show it.
What the ninety-five actually publish
The published group is where the interesting reading is, so here is what is in it.
Almost all of it lives on GitHub. 104 of the 108 carry the URL they were fetched from. One hundred are on github.com, usually a .spectral.yaml in the root of the repository that holds the provider’s OpenAPI. Four are served from the provider’s own domain. The ruleset as a first-class, addressable artifact on a developer portal barely exists yet.
A third of them write no rules of their own. Thirty-seven of the 108 show zero rules in the listing, and that is not a defect in the files. PayPal extends spectral:oas and spectral:asyncapi and turns four checks down to warnings. LINE and the Accord Project extend IBM Cloud’s published ruleset and switch off what does not fit. PagoPA extends the Italian government’s national API profile. That is the better engineering choice, extend a shared standard and tune it rather than copy it, and the facet has counted inherited rules since 0.12 for that reason. The listing shows the rules a provider authored, and I need to make it show the rules a provider enforces too.
The big ones are governments and regulated companies. The largest rulesets a provider publishes under its own name are Spliceforms at 81 rules, Raiffeisenbank and PagoPA at 60, AgID, the Italian digital agency, at 50, Entur, the Norwegian transit authority, at 48, and the Sovereign European Cloud API at 45. CAMARA publishes five, one per working group repository, and Logius, the Dutch government’s digital services body, publishes three. The private companies in the group, Adidas, Camunda, BigChange, Trimble, Docker, BitGo, Fireblocks, Elhub, mostly sit between three and thirty rules.
Most of them can only say no. Of the 71 published rulesets that write rules of their own, 18 use the error severity and nothing else. Seven never use error at all. The facet gives three points for a ruleset that uses warn and info as well as error, because a ruleset where everything is an error can only refuse a change. It cannot guide one. Adidas is the model here: twenty errors for things that must hold, like HTTPS only and camelCase properties, and nine warnings for things that should, like real-looking examples and no verbs in paths.
What the other six thousand are for
The 4,515 generated rulesets are the ones I want to be clearest about, because for a long time the page said “Published by Adidas” on a file Adidas never saw, for every provider in the catalog. A provider caught it before I did. Every generated ruleset now says it was written by API Evangelist tooling for that provider’s APIs, and reads as a starting point, not a claim about the provider. They are small, a median of five rules, and 2,965 of them carry no error-severity rule at all, which is the right posture for a suggestion.
The 66 derived rulesets are almost entirely universities, from the roster of 254 I profiled this summer. Each one is a measurement: I read the OpenAPI a university publishes and wrote down the conventions it already follows, so the rules describe what the contract does rather than what anyone decided. They are useful as a mirror. They are not governance, and they are labelled as the measurement they are.
How it scores
The Contract Governance facet pays ten points for publishing a ruleset, five more for a substantial one of twenty or more enforced rules, and three for balanced severities. Since the London release a generated or derived ruleset earns a quarter of that, and an unmarked one earns 0.90. Stockholm, 0.24.0, is scheduled for October 13th and finishes the job: the rules family is graded by the provider’s primary ruleset, and an unmarked ruleset reads as derived rather than as the provider’s own. That moves 228 providers’ rules provenance, 174 composites fall by a median of 3.8 points, and 45 change band. It also moves our own number. The ruleset for apis.io was generated by a script and then edited by hand, and in 0.24 it is marked as authored using the same markers any provider can put on their own work, so apis.io rises from 90.1 to 95.0. I said in the facet post I would not give myself a category nobody else can use, and I have not. The release note will say our record went up and why.
What to do with it
If you are one of the 95, your ruleset is now the first thing on that page, served from where you publish it, with your name on it. If you run a ruleset in CI and have never published it, the file already exists, and putting it where the catalog can fetch it is worth fifteen points and, more to the point, tells every tool and every agent reading your contract what you hold yourself to. Extend spectral:oas rather than copying it. Use warn as well as error. And if you want to see what the rules the catalog wrote for you look like before you write your own, your generated ruleset is on the page too, labelled as mine until the day it is yours.
