APIs.json 0.25 makes the specification agree with itself. Through 0.24, the text, its examples and its JSON Schema described three slightly different formats, and nothing checked one against the others. 0.25 brings them into line, writes down the extension rules that had only ever lived in the schema, registers the property types a scoring pipeline and independent publishers were already reaching for, and adds the check that keeps all of it from drifting again.
Measured against the 153 APIs.json indexes that providers host themselves on the showcase, 87 validated in full under 0.24 and 95 do under 0.25.
The text, the examples and the schema now agree
aidis Recommended, not Mandatory. 72 of 151 live, self-hosted indexes omit the documentaid, and 193 of their APIs omit one. A first version that 40% of real publishers fail is describing a different format from the one in use.networksis the name of the networks collection. The text saidnetworksand the schema saidnetwork.networksmatches every other collection name;networkis still accepted.- The contact fields match. The text listed lowercase vCard spellings (
fn,org,x-twitter), while its own examples and the schema usedFN,organizationNameandX-twitter. Publishers followed the examples, so the text now does too, and the lowercase spellings stay valid. Any other social handle is an extension, such asx-bluesky. - A workflow can carry a
humanURL, as an API can, so an index can link to a page where a person reads or runs an Arazzo workflow.
Extensions are written down
Section 3.9 said "TBD" for several releases while the schema changed the rules underneath it: uppercase keys only, then either case, then no rule at all. 0.25 writes them down. An extension may appear on the document, on an API, on a property and on a contact. Its key starts with x- or X-, lower case preferred. Its value can be anything, so x-tier: enterprise is valid. A key that is neither defined nor prefixed is allowed, and a consumer that does not recognise it must ignore it rather than reject the document.
Nineteen property types, by measured use
The privacy and regulation types are the larger part of this. The APIs.io Kin Score reads every one of them, so a provider publishing exactly the disclosure a regulation asks for was failing validation. That is the same wrong-way-round problem that prompted 0.23: if a consumer is looking for a property type, the specification should have a word for it. Counted across 37,661 indexes in the APIs.io catalog:
- Organisation:
Leadership(1,003 indexes). - Privacy and regulation:
DataSubjectRequest(125),Subprocessors(77),AITransparency(48),DataResidency(42),IncidentNotification(28),ExitAssistance(20),GlobalPrivacyControl(15),NoticeAndAction(15),SupportLifetime(9),AccessibilityConformance(6),TransparencyReport(3),TrainingDataSummary(2),AgeAssurance(1) andBiometricDataPolicy(0). - Agents and security, where independent publishers led:
MCPServerCard(8 self-hosted publishers),X402(4), and the two OAuth discovery documents,ProtectedResourceMetadata(RFC 9728) andAuthorizationServerMetadata(RFC 8414), with 4 each.
Thirteen alternate spellings now validate beside their canonical names, among them MCP for MCPServer, News and Press for Newsroom, Status for StatusPage and Changelog for ChangeLog. Every type and spelling is on the reserved words page, which was also brought up to date: it had stopped at 0.21, and is now checked against the schema.
What 0.25 does not promote matters as much. The largest invalid values in the catalog are Hosts, Vendors and CapabilityMap, each on thousands of indexes. They are pointers written by one catalog's own pipeline, not words the market uses, and they belong in extensions.
A check that runs on every change
Building 0.25 turned up a bug that had been in the published specification all along: the YAML example in section 4 did not parse. Its multi-line description was not indented and the keys after each list item sat a space too deep. It is now generated from the JSON example and round-trips to it exactly.
Nothing had caught that, or the schema drifting from the text, because nothing was checking. 0.25 adds a validation workflow to the specification repository. On every change it confirms each schema is valid, that the examples validate against it, and that every reserved word the text lists is one the schema accepts. It also reports how the live showcase fares, without failing on it, because real publishers are not the specification's to fail.
Thanks to Christian Gördes, whose pull request aligning the 0.24 schema with its text started this release, and to @erwinkramer for the workflow humanURL and the YAML clean-up.
Read the 0.25 specification or the schema, and the discussion in pull request #134.