The adopters schema for the API Commons — a machine-readable way to publish who implements a standard, and how strongly each claim is evidenced.
It exists because of a specific problem. Some of the most widely implemented API contracts were never ratified by anyone: S3, the OpenAI API, CKAN's Action API, Ethereum JSON-RPC. They became standards by being copied. "Compatible" is then a marketing word until someone writes down who says so, where they said it, and what was actually checked — which is what this schema makes you do.
- adopters-json-schema.yml — JSON Schema 2020-12.
- adopters-example-1.yml — a standalone document. Real CKAN portals, probed read-only on 2026-09-13.
- adopters-example-2.yml — the APIs.json property envelope,
the form a provider publishes inside their own
apis.yml. - fixtures/negative-control.yml — deliberately invalid.
- validate.py — validates the examples and asserts the negative control is caught.
python3 validate.py
A claim is not a verdict. claim_url and source_date are required on every entry —
an undated claim about a named organization is not a fact, and provider pages go stale.
tier_verified may only be set alongside verified_on and an evidence_url, and an entry
graded prose can never carry one at all. The schema rejects it.
Say what the probe actually did. evidence: tested requires a probe_status. This is
not bureaucracy — it comes from probing real portals:
| Response | What it means |
|---|---|
400 Action name not known |
The only proof an operation is absent |
403 Authorization Error |
Implemented, credential-gated |
409 Validation Error |
Implemented, wrong arguments |
302 redirect |
Implemented |
403 with an HTML body |
An edge refused us. Nothing was learned |
And one outcome that is neither: an endpoint that fails its negative control. Ask any
endpoint for an operation that cannot exist. If it does not say so, it cannot distinguish
present from absent, and it misleads in both directions — one that errors on everything
reads as implementing nothing, one that returns success for everything reads as
implementing the lot. Probing 42 public EVM endpoints on 2026-09-13, 7 failed this
control: some returned a valid-looking error, two returned a successful result for a
method that does not exist. All seven are recorded inconclusive and carry no tier.
Probing data.gov.au on 2026-09-13, a naive reader would have marked datastore_search
and user_list unsupported. Both are implemented. That is the defect this field prevents,
and blocked exists so an unreachable host is never silently scored as a failing one.
| Grade | Meaning |
|---|---|
declared |
Publishes a machine-readable spec that lints against the profile |
vendor-matrix |
Publishes their own compatibility table |
prose |
Says "compatible" and nothing more |
tested |
The profile's read-only flows were run against a live endpoint |
reimplementation — independent servers written against someone else's published surface,
where divergence is a design choice. S3, OpenAI, Anthropic, Ethereum.
version-drift — the same software at different releases, where divergence is upgrade lag
and plugin choice. CKAN, whose portals spread across 2.7 to 2.11. These entries carry
software_version, and a matrix built from them answers "which release" rather than
"which operations did you build".
A machine-readable building block from API Commons — open specifications and schemas for the APIs you produce and consume.
Related building blocks
- versioning — how an API is versioned
- features — what an API can do
- integrations — an API's connector catalog
- interface-license — licensing an API's surface
The artifacts in this repository — the schemas and examples — are licensed
CC BY-NC-SA 4.0 (Attribution–NonCommercial–ShareAlike). The code —
validate.py — is licensed Apache-2.0.
API Commons licenses artifacts under CC BY-NC-SA 4.0 and code under Apache-2.0.