Open Data

De facto standards for the open-data layer, published by the API Commons.

Nobody ratified CKAN's Action API as the open-data standard. It became one because government after government installed the same software, and a client written against one national portal now works against hundreds of city, state and research catalogues by changing a hostname.

This repository writes that interface down — and it is the only profile in this programme that is AUTHORED rather than derived, because CKAN publishes no machine- readable specification of its own Action API.

The obvious shortcut was to count how often each action appears across the catalog's CKAN entries. That number is worthless. Run it and status_show comes out at 81% and package_search at 14%, which would make a health check the most-supported action in CKAN. It is not: our own harvester fingerprints portals by calling status_show, and four of the 'actions' it turned up came out of error catalogs we generated ourselves. The number measured us.

So the action list is enumerated from ckan/logic/action/*.py in CKAN's own repository — 134 actions, 65 of them reads — and support is established by calling them.

Every other standard in this programme is implemented by independent teams writing their own servers, where divergence is a design choice. CKAN is not. These portals run the SAME SOFTWARE at different releases — 30 distinct ones in this sample, from 2.2b to 3.0.0 — so an absent action usually means an older CKAN rather than a decision. Every registry entry carries its software_version, and the matrix reports support per release rather than as one number.

48 portals were probed read-only, 36 produced usable results. One request at a time, a delay between every call, an identifying user agent, and a hard stop on 429. No write action was ever called: this probe runs anonymously, and an anonymous write attempt against a government server would be both useless and rude.

The status code is never where the answer is. CKAN returns the same envelope whether an action succeeded, was refused for credentials, was given bad arguments, or does not exist — so a client that checks the status rather than success in the body is reading the wrong thing.

Every portal is asked for an action that cannot exist. A portal that does not say so has no working discriminator, and nothing it reports is recorded.

That alone was not enough. catalog.data.gov answers 404 to every action including status_show — so it passes a negative control, because it does say no to an action that cannot exist, and then reads as a CKAN portal with every action missing. A discriminator has to be shown to say yes as well as no, so every portal also gets a positive control: status_show, present in every CKAN release. A portal that cannot serve it is not serving the Action API at that base URL, whatever our catalog recorded.

12 portals were excluded this way — 9 blocked, 1 inconclusive, 2 unreachable.

standard/ckan-action-v3/
  profile.yml        134 actions, each with its tier and the evidence
  openapi.yml        one path per action, x-tier on each, the shared response envelope
  schema/            JSON Schema 2020-12 for the envelope and each core action
  mcp/tools.json     MCP tool definitions for the core tier
  arazzo/            status_show, then package_search, then package_show on the result
  spectral/          generated from the profile, with fixtures and a harness
adopters/
  ckan-action-v3.yml        48 entries, each with its portal, date and CKAN release
  ckan-action-v3-matrix.md  action by portal, and support by release
scripts/             every artifact above is generated; none is hand-maintained

python3 scripts/probe-adopters.py --endpoints endpoints.json --out probe.json

Or lint a document that claims to describe a CKAN-compatible API:

npx @stoplight/spectral-cli lint their-openapi.yaml \
  -r https://raw.githubusercontent.com/api-commons/open-data/main/standard/ckan-action-v3/spectral/ckan-profile.yaml

6 of 36 probed portals serve every core action. 30 serve some of it, which on this cohort usually means an older release rather than a choice. 12 could not be probed and carry no tier, because a portal we could not read is not a portal that failed.

Action names enumerated from ckan/ckan at commit 0731a7a4ab76dd11889eb89a892b3feae4fd69a8.

CKAN the software is AGPL-3.0. That governs the code, not a description of the HTTP surface it serves — and this profile is authored from CKAN's own source and from live observation rather than copied from any document. Nothing here implies endorsement by CKAN, by the Open Knowledge Foundation, or by any portal named in the registry.

Related

• adopters — the schema behind the registry
• models · blockchain

Artifacts are CC BY-NC-SA 4.0. Code in scripts/ is Apache-2.0.