# Kin Score — Scoring Rubric (the API Evangelist rating system, licensed by APIs.io) # # Per-artifact checks produce raw points. Points roll up into facet sub-scores # (each normalized to 0–100). Facet sub-scores roll up into a composite # provider score using the facet weights below. # # All weights and point values are tunable. Keep this file the single source # of truth for the rubric — code that scores providers should read from here. schema_version: 0.26.0 last_updated: '2026-10-15' maintainer: kin@apievangelist.com # The public "what changed" note. The apis.io /rating/ page renders this rather than # carrying its own copy, because the copy it carried was v0.6's — and it sat under a # heading that read "What changed in v{{ schema_version }}", so it re-badged itself as # current through ten rubric versions while describing none of them. `version` below is # checked against schema_version by test_rubric_record.py: a rubric cannot reach a # rebuild carrying the previous release's story. release_note: version: 0.26.0 body: | One change, and it touches agent readiness only: MCP Tool Quality becomes a scored dimension (roadmap#994), after one release as an observed signal in 0.25.0. MCP Tool Quality, 6 points, graded: whether an agent can use a server's tools safely and cheaply. Annotations (2: share of tools carrying readOnlyHint or destructiveHint, full credit at 90%), parameter descriptions (2: share of parameters described, full at 90%), hazard hints (1: no state-changing tool without a destructiveHint) and weight (1: a tool list under 20k tokens, and no single tool over 1,200). The credit is rounded to the nearest quarter. Not applicable, and out of the denominator, when the provider's server has no live tools/list capture or is authored by a platform rather than the provider. Measured from 641 live captures refreshed 2026-10-27 (initialize and tools/list only, anonymous, no tool called). 1,627 servers answered that they need authentication and are not graded. 565 providers are graded: 311 full, 143 three-quarters, 67 half, 42 quarter, 2 none. Composite: unchanged for every provider (agent readiness is standalone). Agent readiness: 561 move, 523 up and 38 down, median +2.2, range -1.4 to +4.0; 42 agent-band changes, all upward. Band shares move by at most 0.1 point, so no band is re-cut. aliases: # 0.13 (roadmap#71) — the Examples family. A provider publishing a separate example # corpus wired `Examples` in good faith and it was read by NOTHING; four spellings of # the same idea are in the catalog. Alias-aware here rather than in the lambda, per # the standing rule that a vocabulary in code is where drift starts. Examples: - CodeExamples - Samples - CodeSamples - Demos - Example SDK: - SDKs - Python SDK - JavaScript SDK - Go SDK - Java SDK - Ruby SDK - PHP SDK - Node.js SDK - Connect Python SDK - Connect Node.js SDK - Connect Go SDK SpectralRules: - Spectral - Spectral Rules - SpectralRuleset - OpenLint - OpenLint Rules - OpenLintRules - OpenLintRuleset - Rules GitHubOrganization: - GitHubOrg - GitHub Org - GitHub GitHubRepository: - GitHubRepo - Repository - Source Code - SourceCode ChangeLog: - ReleaseNotes - Releases - Versioning TermsOfService: - TermsOfUse - Terms of Use - Terms of Service PrivacyPolicy: - Privacy JSONLDContext: - JSONLD - JSON-LD Context JSONSchema: - JSON Schema DeveloperPortal: - Developer Portal - Portal APIReference: - API Documentation - APIDocumentation - Reference Postman: - Postman Collection - PostmanCollection - PostmanWorkspace Security: - SecurityPolicy - Security Policy Deprecation: - Deprecations - Deprecation Notice - DeprecationPolicy MailingList: - Mailing List - Mailing Lists - MailingLists HelpCenter: - Help Center KnowledgeBase: - Knowledge Base - KnowledgeCenter - Knowledge Center # 0.9.4 — four silent zeros found by inventorying the common[].type vocabulary # the enrichment pipeline actually writes against the vocabulary the checks # actually read. Each of these was a scored zero caused by a label, not by an # absence. `LlmsText` is the expensive one: 15 of 36 API management providers # carry it and `llms_txt_published` credited 2. SignUp: - Signup - Sign Up - Register - Registration LLMsTxt: - LlmsText - LLMsText - LlmsTxt AgentSkill: - AgentSkills Community: - Forums - Forum - Discord - Discourse - Slack # DELIBERATELY NOT ALIASED, and this is a rubric decision rather than an # oversight: `ModelContextProtocol`, `MCPServers`, `MCPClient`, # `MCPServerRegistry`, `ProxyExistingMCP`, `ExportRESTToMCP` and # `MCPServerOverview` all appear in the catalog and all point at a vendor page # about MCP as a product for the vendor's customers. None of them is a server # the vendor runs for its own API. Folding them into `MCPServer` would credit # the sales page and erase the sell-versus-publish finding the Area Market # Report series is built on. # --------------------------------------------------------------------------- # thresholds (schema 0.10.0+) — WHICH CHECKS ARE COUNTS, NOT BITS. # # These checks pass on a COUNT crossing a bar, not on the presence of one thing. # Nothing in the rubric said so, so every consumer of `--explain` treated them # as "close the evidence gap and earn the points". For a count check that is # false: a probe finds an SDK page, wiring one `SDKs` pointer earns # `sdk_count_1` and leaves `sdk_count_3` exactly where it was. # # Measured on the API management cohort: three providers had a verified SDK page # and the naive remediation math credited both checks — 12.2 composite points # across the cohort that no amount of wiring can deliver. # # This matters most in the Personalized Checklist, where the points column IS # the pitch. A checklist that promises points a provider cannot earn by doing # what it says is worse than one that under-promises. roadmap#30. # --------------------------------------------------------------------------- thresholds: multiple_apis: 3 tags_present: 5 description_substantive: 200 # characters, not items sdk_count_1: 1 sdk_count_3: 3 rules_present: 1 rules_substantial: 20 plans_present: 1 plans_multiple: 3 rate_limits_documented: 1 rate_limits_rich: 3 json_schema_per_resource: 2 json_ld_class_depth: 5 json_ld_property_depth: 10 graphql_type_depth: 20 fhir_resource_coverage: 20 # --------------------------------------------------------------------------- # attribution (schema 0.9.4+) — WHO CAN MOVE THIS CHECK. # # The provenance block above answers "who wrote the artifact we are reading". # This block answers a different question, and a Market Report cannot be # written honestly without it: if a provider does NOT earn this check, whose # work closes the gap? # # The Kin Score measures a provider AS IT EXISTS IN THE API EVANGELIST INDEX, # and API Evangelist is a party to that index. That is deliberate (see the # provenance notes above) — but it means an unearned check has two possible # authors, and a report that assigns every unearned check to the vendor is # reporting our own collection backlog as a market finding. # # Measured on the API Management cohort (36 providers, 2026-08-11): the # correlation between the number of pointers WE recorded in a provider's # apis.yml and its composite score is r = 0.77. The bottom pointer-quartile # averages 37.7 and the top averages 71.8. Some of that is real — a better # provider has more to point at — but it is not all real, and the rubric could # not tell the difference because nothing in it recorded which side of the # index a check reads from. # # catalog API Evangelist can satisfy it alone. -> our backlog # index their surface, our apis.yml pointer. -> PROBE, then assign # harvest their contract, our tree. -> our harvest queue # spec quality inside a contract we already hold. -> theirs, mostly # frontier only the provider can produce it. -> theirs, entirely # # The `index` class is the one that matters editorially. An index-class zero is # NOT a finding until a live probe says the provider does not publish it. The # first cohort probed this way turned "llms.txt: 2 of 36" into "21 of 36 serve # a real llms.txt; the rubric was reading a type alias it did not have". # # Only `frontier` and `spec` zeros are safe to report as market findings # without a probe. That is the operating rule this block exists to enforce. # --------------------------------------------------------------------------- attribution: # CATALOG — API Evangelist can satisfy this alone. No provider action is # required, and an unearned check here is our backlog, not their gap. apis_yml_present: catalog balanced_severities: catalog base_url_per_api: catalog created_modified_dates: catalog description_substantive: catalog finops_mapped: catalog human_url_per_api: catalog image_present: catalog json_ld_class_depth: catalog json_ld_present: catalog json_ld_property_depth: catalog json_schema_per_resource: catalog json_schema_present: catalog maintainer_present: catalog multiple_apis: catalog overlay_published: catalog plans_multiple: catalog plans_present: catalog rate_limits_documented: catalog rate_limits_rich: catalog rules_present: catalog rules_substantial: catalog tags_present: catalog vocabulary_published: catalog # INDEX — the evidence lives on the provider's public surface and the score # reads OUR apis.yml pointer. Unearned means EITHER we never indexed it OR # they never published it, and the two are indistinguishable without a probe. # Never report an index-class zero as a market finding until it is probed. agent_skill_present: index api_reference_present: index auth_clarity: index authentication_documented: index blog_present: index change_log_present: index cli_present: index compliance_published: index console_or_sandbox: index deprecation_policy: index documentation_present: index getting_started_present: index github_org_present: index mcp_server_present: index portal_present: index postman_present: index pricing_link: index privacy_policy: index reg_authentication_documented: index reg_compliance_published: index reg_consent_model: index reg_entitlement_terms: index reg_oauth_scopes: index reg_privacy_policy: index reg_security_disclosure: index reg_standards_conformance: index reg_terms_of_service: index reg_vulnerability_disclosure: index roadmap_present: index sdk_count_1: index sdk_count_3: index security_disclosure: index sign_up_present: index status_page_present: index support_channel: index terms_of_service: index trust_center: index webhooks_advertised: index # HARVEST — a provider-published machine-readable contract, read from the # copy we hold. Unearned means we never harvested it, or we hold the wrong one. # # 0.11 EXCEPTION — the four os_* checks are `harvest`, but their zeros ARE # reportable as market findings without a further probe, unlike every other # harvest check. The rule exists because a harvest zero normally cannot # distinguish "they never published it" from "we never fetched it". For these # the harvest IS the live probe: a direct read of the GitHub API across the # full set in one pass. And the read-success gate means a repository we could # not reach drops out of the facet entirely rather than scoring zero — so a # zero here can only mean we looked and it was not there. os_security_policy: harvest os_contribution_guide: harvest os_releases: harvest os_code_of_conduct: harvest agentic_access: harvest asyncapi_3_x: harvest asyncapi_present: harvest channels_defined: harvest conformance_declared: harvest contract_present: harvest fhir_capability_statement: harvest fhir_resource_coverage: harvest graphql_descriptions: harvest graphql_sdl_present: harvest graphql_type_depth: harvest messages_with_schema: harvest security_schemes: harvest server_bindings: harvest spec_presence: harvest # CONTRACT — quality INSIDE a document we already hold. Provider-authored; # our only lever is holding their current first-party contract rather than a # stale or derived stand-in. components_reuse: spec credentials_not_in_query: spec error_responses_documented: spec error_semantics: spec event_surface_described: spec examples_present: spec idempotency: spec info_complete: spec oauth_flows_current: spec oauth_scopes_enumerated: spec openapi_3_0: spec openapi_3_1: spec openapi_examples: spec operations_description_coverage: spec operations_operation_ids: spec operations_summary_coverage: spec operations_tagged: spec response_coverage: spec security_applied: spec security_schemes_defined: spec servers_defined: spec servers_resolvable: spec webhooks_or_callbacks: spec # FRONTIER — only the provider can produce the evidence. No amount of # indexing moves these, which is exactly why the reports lean on them. agent_card: frontier agent_skills: frontier apis_json_self_hosted: frontier consent_identity: frontier dry_run_mode: frontier llms_txt_published: frontier mcp_server: frontier rate_limit_signal: frontier reg_camara_conformance: frontier reg_certification_signal: frontier reg_fapi_profile: frontier reg_mandate_verified: frontier reg_named_standard_conformance: frontier reg_pci_sca: frontier reg_smart_configuration: frontier reg_write_surface: frontier well_known_catalog: frontier well_known_published: frontier # --------------------------------------------------------------------------- # provenance (schema 0.6+) — WHO PUBLISHED THE ARTIFACT. # # The rubric's core claim is that it measures what a provider actually ships. # Through 0.5.1 it could not: a spec, an MCP server or an agent skill authored # by API Evangelist on a provider's behalf satisfied exactly the same check as # one the provider published itself. In sectors where few providers publish # anything, that stopped being noise and started deciding the standings. # # Three authorship states, and the third is the one energy forced into the # model — an artifact can be genuinely provider-hosted and still not be the # provider's own design: # # first-party the provider wrote it and serves it credit 1.00 # conformance the provider serves a standards body's document credit 0.75 # derived API Evangelist authored it on their behalf credit 0.25 # unknown no marker either way credit 1.00 # # `derived` keeps a floor rather than scoring zero because a groundable derived # candidate is not worthless — it is a real, fetchable artifact one adapter away # from working, and an agent shopping the catalog can use it. It is simply not # evidence about the provider, so it must never outrank the real thing. # # `unknown` is credited IN FULL, deliberately. Only artifacts this pipeline # authored carry a marker, so an unmarked artifact is far more likely to be a # harvested provider-published one than an unlabelled derivation. Scoring # `unknown` as derived would punish providers for a gap in our own metadata. # The honest cost of that choice: OpenAPI marker coverage is 2.6% (2,274 of # 87,612 specs), so contract provenance is a FLOOR, not a census, and the # `provenance_coverage` figure is published beside the score rather than hidden. # Backfilling x-provenance across the OpenAPI corpus is collection work, and it # is the single highest-value thing that would sharpen this release. # # Source of truth: signals/_data/provenance.json, rebuilt by # `python3 signals/build_provenance.py` before every scoring pass. # --------------------------------------------------------------------------- provenance: # FUTURE (captured 2026-08-01, not scheduled) — two things scoring a # self-optimizing provider exposed about this block. Neither is a bug today; # both are the dials that turn when certification tightens. See the # discovery-now / certify-later note above `planned_dimensions`. # # (1) THE VOCABULARY IS OURS, NOT THEIRS. build_provenance.py recognizes # method: derived|generated|modeled|reconstructed|inferred -> derived, and # searched|probed|harvested|fetched|researched -> first-party. A PROVIDER # writing their own artifact reaches for none of those — Xquik wrote # `method: declared` across their set and every file resolved `unknown` # except the one that also carried `status: published`. The vocabulary was # designed for our pipeline describing how IT found something, and now # providers are authoring artifacts directly. Options: accept `declared` # (and `authored`, `published`, `self-reported`) as first-party when paired # with a `publisher:` and a resolvable `source:`, or stop inferring from # `method:` for provider-authored files and read only `x-provenance`. # Publishing the accepted vocabulary on /rating/ matters either way — right # now a provider cannot know the token exists. # # (2) `unknown: 1.00` IS THE LOOSEST DIAL HERE, ON PURPOSE. Crediting an # unmarked artifact in full is correct while marker coverage is 2.6% — # the alternative punishes providers for a gap in OUR metadata. But it # also means a provider-authored artifact carrying no recognized marker is # worth exactly as much as a verified first-party one, so nothing in the # score currently rewards a provider for making their authorship legible. # That inverts once (1) is fixed and coverage rises: the moment `unknown` # reliably means "nobody said," it should cost something. Do not lower it # before then, and re-cut bands when it moves — this multiplies awards # across seven checks. # 0.23.0 (roadmap#285) — THE PROVIDER VOCABULARY, accepted. Kin's ruling 2026-09-17 on # item (1) above: `build_provenance.py`'s two method sets both describe how OUR pipeline # obtained something, so a provider authoring their own artifact reaches for neither and # falls through to `unknown`. Xquik stamped `method: declared` across their whole set and # every file resolved `unknown` except the one that also carried `status: published`. # # WHAT THIS DOES AND DOES NOT DO. `unknown` is credited 1.00, the same as `first-party`, # so recognising these tokens moves NO composite — not Xquik's, not anyone's. What it moves # is the DISCLOSURE: `catalog_earned_first_party` and `provenance_coverage` stop understating # every provider who marks their own work. Item (2) above is the dial that makes it pay, and # it stays shut until coverage is real. # # THE GUARD IS THE WHOLE POINT. A bare `method: authored` is a provider asserting authorship # of their own artifact, for free, about themselves. It is accepted only when the artifact # also names a `publisher:` and carries a `source:` that resolves — an absolute http(s) URL # or a path present in the repo. Liveness is NOT probed here: this pass reads 27k artifact # heads and a probe belongs in the well-known sweep. The guard is about legibility, not # verification, and the published wording should say so. # # A PROVIDER CANNOT USE A TOKEN NOBODY PUBLISHED. This list is the rubric's copy precisely # so /rating/ can render it; build_provenance.py reads it from here rather than carrying its # own. Absent from a rubric (as it is from 0.22.0), the classifier keeps its old behaviour — # which is what keeps this inert until this release ships. # 0.24.0 — the parent keys under which a nested `method:` counts as an authorship marker # (build_provenance.py nested_method, roadmap#794). METHOD_RE only reads column 0, so an # artifact stamped `x-provenance.method: derived` resolved `unknown` at 0.90 instead of derived # at 0.25 -- 89 providers, mostly JSON Schema sets; OpenAPI already reads x-provenance through # OA_DERIVED_RE and does not move. Matched by parent NAME, so an AsyncAPI HTTP # binding's `method: get` is never read. `x-evidence` is deliberately NOT listed: its `method` # mixes HTTP verbs with prose (`derived-from-published-docs`), so it does not say who authored # the file. Absent from 0.23.0, so the reader is inert until this ships. nested_method_containers: [x-provenance, x-apievangelist, x-apievangelist-provenance, x-apievangelist-derivation, info] # 0.24.0 (roadmap#795) — grade the rules family by the ruleset the rules checks credit (the one # with the most rules), and read an unmarked ruleset as derived: the enrichment pipeline writes # these, providers do not, and a provider who wrote theirs marks it (author_markers below) and # gets full credit. Kin's call 2026-09-26. The two ship together: the first alone would lift 798 # providers from 0.25 to 0.90 on rulesets we wrote. family_primary: [rules] unmarked_as_derived: [rules] author_markers: methods: [declared, authored, published, self-reported] requires: [publisher, source] credit: first-party: 1.00 conformance: 0.75 derived: 0.25 # 0.18.3 (roadmap#251) — Kin's ruling 2026-09-03: a self-confessed scaffold is # unenriched BY DEFINITION, so it counts as zero coverage rather than as a weak # derivation. `derived` means we built it from something the provider published; # `scaffold` means the document itself says nobody exercised the API. scaffold: 0.00 # 0.23.0 (roadmap#285 item 2). Kin's call 2026-09-17: lower it, in London. # # 1.00 was right while nothing in the score rewarded a provider for making authorship legible # — the block's own item (2) says so, and says the dial should turn once item (1) lands. It # landed in this release: `author_markers` accepts the provider's own vocabulary and # /rating/#provenance publishes the tokens. # # 0.90 AND NOT LOWER, measured rather than chosen: at 0.90, 9,617 of 26,484 composites move, # median -1.30, and 895 change band. At 0.75 it is 9,648 moving, median -3.30, 2,155 band # changes, and the exemplar band HALVES (1.3% -> 0.7%). A 10% haircut is the smallest step # that inverts the incentive; 25% is a different release with a different argument. # # NO BAND RE-CUT. Measured on the 0.90 snapshot the shares drift by at most 0.6pp — exemplar # 1.1 -> 1.0, strong 4.3 -> 4.0, developing 14.4 -> 13.8, minimal 39.0 -> 38.6 — and the # documented rule is to re-cut only when a band empties or swells. Moving the cuts to absorb # a uniform haircut would change what `strong` MEANS in order to keep its population, which is # the opposite of calibration. # # WHAT IT COSTS, SAID PLAINLY: 895 providers drop a band for a gap in OUR metadata. Marker # coverage is 7.6%; the other 92.4% are unmarked because until this release nothing asked them # to mark anything. The release note must say that, and must point at /rating/#provenance as # the remedy — a provider who marks their work gets the credit back, and that is the entire # point of moving this dial rather than leaving it. unknown: 0.90 # 0.23.0 (roadmap#485) — REAL, AND SOMEBODY ELSE'S. Two classes that used to land on the # first-party path, priced at `derived` because the rubric already has one number for "real, # callable, not this provider's design": mcp_server `platform` 0.25, agentic_commerce # `platform` 0.25. build_provenance.py reads these two keys to decide whether to emit the # classes at all, so a rubric without them (0.22.0) classifies exactly as before. # # site-plugin the graded MCP endpoint is the WordPress MCP Adapter's REST namespace, # `/wp-json/mcp/...`, recognised by PATH whether or not tools/list answers. # 108 providers; before this, all 108 read first-party. 4 more carry the # plugin URL somewhere in their record but are graded on a real product server # (skai-kenshoo, dailypay, debounce, aptera-motors) and are untouched. # third-party the manifest's own `status:` is third-party / platform / platform-default / # community — a community npm server, a Zapier bridge. 17 providers (an 18th, # resynergi's `platform-default`, IS the plugin and reads site-plugin). # # In agent readiness both are graded `platform` by mcp_server, and the multiplier below is NOT # applied on top: the grade already carries the authorship discount, and stacking the two # (0.25 x 0.25) would price a WordPress plugin below a server we derived ourselves. site-plugin: 0.25 third-party: 0.25 # 0.23.0 (roadmap#676, #680) — ONE CLASS FOR EVERY PLATFORM-GENERATED SURFACE. `site-plugin` # named the WordPress MCP Adapter; the same fact holds for every surface a website or store # platform generates for each tenant: WordPress core REST (/wp-json), Wix's site MCP # (/_api/mcp), Shopify's Storefront GraphQL, Storefront MCP, UCP and Customer Account endpoints. # The data marks them (`x-surface: platform-generated` + `x-platform`, collapse-platform- # surfaces.py, from response-header evidence, never the path alone); build_provenance.py reads # the mark and emits the class for three artifact kinds: # mcp the graded MCP endpoint is a platform surface (mcp_server_present, mcp_server) # openapi >= 75% of the OpenAPI corpus describes one (contract_present, openapi checks) # graphql every SDL is a store's Storefront API schema (graphql_sdl_present/_type_depth/ # _descriptions; read in score.rb, # not via applies_to, so no other # SDL is graded as `unknown`) # contract_present pays this class when EVERY contract the provider has is platform-generated. # In agent readiness mcp_server grades `platform`, not stacked, exactly as site-plugin. platform-generated: 0.25 # Checks and dimensions whose award is multiplied by the authorship credit of # the artifact class named here. Everything else is unaffected. applies_to: mcp_server_present: mcp # developer_ergonomics, 4 pts agent_skill_present: skills # developer_ergonomics, 3 pts postman_present: collections # developer_ergonomics, 2 pts (0.18.3, roadmap#208) contract_present: openapi # contract_quality, 20 pts mcp_server: mcp # agent readiness, 12 pts agent_skills: skills # agent readiness, 5 pts event_surface_described: asyncapi # agent readiness, 6 pts agentic_access: agentic_access # agent readiness, 10 pts conformance_declared: conformance # governance, 6 pts # PREPARED, INERT UNTIL THE REFRESH PASS — the heaviest catalog-authored # surface in the rubric. Stamp a version when the refresh runs and this bites. These four # checks are 24 points: 12 of commercial_clarity's 38 and 12 of operational # transparency's 38, which weights out at roughly 10.4% of every composite. # 7,172 of 7,317 plans artifacts and 7,117 of 7,748 rate-limits carry no # `method:` — most written in one 2026-05-04 sweep, by a pipeline that had no # step for either artifact until one was added alongside this. Until that refresh runs and # stamps them, `unknown` credits 1.00 and this mapping changes nothing; the # moment it does, the score stops calling our sweep the provider's evidence. plans_present: plans # commercial_clarity, 8 pts plans_multiple: plans # commercial_clarity, 4 pts rate_limits_documented: rate_limits # operational_transparency, 8 pts rate_limits_rich: rate_limits # operational_transparency, 4 pts # PREPARED 0.10.3, INERT UNTIL STAMPED — the derived tier, and it is larger # than the plans/rate-limits surface that preceded it. GOVERNANCE rests 42 of # its 48 points on artifacts API Evangelist authors: the Spectral ruleset # (rules_present, rules_substantial, balanced_severities = 18 pts after 0.12 # dropped low_error_density and zero_errors), the vocabulary, and the overlay. At weight # 0.12 that is roughly 10.5% of every composite asserting "this provider # governs its contracts" where the true statement is "API Evangelist wrote a # ruleset for them". CONTRACT_QUALITY carries another 21 points of # json-schema and json-ld derived the same way. # # Measured 2026-08-11: 5,785 rules artifacts across 3,585 providers, of which # 4,516 carry a named generator in their own header — strengthen_jsonschema.py, # strengthen_ruleset.py, strengthen_asyncapi.py. Exactly ONE carries a # `method:`. 120,553 json-schema files across 3,341 providers, ten carry one. # # Inert on arrival, same as plans/rate-limits were: `unknown` credits 1.00 and # unmarked is what these are. It costs nothing until a stamping pass runs and # is correct the moment it does. rules_present: rules # governance, 10 pts rules_substantial: rules # governance, 5 pts balanced_severities: rules # governance, 3 pts vocabulary_published: vocabulary # governance, 5 pts json_schema_present: json_schema # contract_quality, 6 pts json_schema_per_resource: json_schema # contract_quality, 4 pts # 0.9: a dimension satisfiable from MORE THAN ONE artifact class must grade # against whichever class actually satisfied it. `event_surface_described` is # satisfied by an AsyncAPI document (graded `asyncapi` above, and 0 providers # publish one) OR by a `webhooks`/`callbacks` object inside the provider's # as-published OpenAPI. The latter is first-party BY CONSTRUCTION: it is read # from openapi/_original/, the verbatim harvest archive, so the provider wrote # it and we only stored it. Grading that through the `asyncapi` class would # discount a provider for our authorship of an artifact they did not use. first_party_when: event_surface_described: openapi_events # 0.8: every check in these artifact blocks is provenance-graded, not just the # presence check. Grading only `contract_present` was a half-measure — 20 of # the 132 points in contract_quality — so a provider whose entire spec corpus # API Evangelist wrote still earned full credit for info_complete, # operations_summary_coverage, operationIds, response_coverage and the rest: # spec craftsmanship it had no part in. An explicit per-check entry above wins # over the class rule here. # # This grades DOWN to the derived floor (0.25), not to zero, and deliberately # so: a thoroughly modeled OpenAPI with real descriptions and stable # operationIds genuinely helps a consumer whatever its provenance. The credit # table is a multiplier, not a gate. applies_to_artifact: openapi: openapi # --------------------------------------------------------------------------- # Facet weights for the composite provider score. # Must sum to 1.0. Tune to dial in what "good" means for apis.io search. # --------------------------------------------------------------------------- facets: discoverability: weight: 0.10 label: Discoverability description: > Can the API be found and understood from machine-readable metadata alone? Driven by apis.yml completeness, tagging, and identity signals. contract_quality: weight: 0.25 label: Contract Quality description: > Technical depth and richness of the API contract artifacts — OpenAPI, AsyncAPI, JSON Schema, JSON-LD. contract_governance: weight: 0.12 label: Contract Governance description: > Artifacts that describe and constrain the CONTRACT — rulesets, vocabulary, declared conformance, overlays. Renamed in 0.12 from "Governance": it never measured how the organisation governs itself, and the standalone `accountability` layer now does, so one word could not carry both. NOTE ON WHAT THIS SCORES (0.12, roadmap#62): these checks read what a ruleset DECLARES, not the result of running it. Spectral is never executed against the provider's own spec. The facet text through 0.11 described lint outcomes, which was the source of a reported and confirmed defect. Outcome-based linting is a separate artifact class and is not in this release. operational_transparency: weight: 0.13 label: Operational Transparency description: > Does the provider expose how the API behaves operationally? Rate limits, status, change log, deprecation, security disclosure. developer_ergonomics: weight: 0.20 label: Developer Ergonomics description: > How easy is it to get started? SDKs, CLI, portal, getting-started, documentation, sandbox/console, MCP server, and authentication clarity. access_clarity: weight: 0.20 label: Access Clarity description: > What it costs, what you are permitted to do, and how you get in — plans, pricing, sign-up, terms of service, privacy, finops mapping, compliance/trust. Renamed in 0.12 from "Commercial Clarity". For a free statutory interface, a public-interest open-data API, or a provider whose own OpenAPI states "No authentication, no registration, no rate limit, no quota", there is no commercial surface to measure and only the permission and access questions apply. The word described a subset of the catalog and was read as a deficiency by the rest. regulatory: weight: 0.15 conditional: true # only applies to regulated industries (see industry_regulatory) label: Regulatory Posture description: > For providers in a regulated industry ONLY: does the API publish the consent, security, legal, and standards-conformance posture its regime demands? Consent-scoped authorization (OAuth/OIDC scopes), a published security + vulnerability-disclosure posture, terms/privacy as legal basis, and evidence of conformance to the industry's data standard. Not applied to unregulated industries — see the composite math note below. open_source: weight: 0.10 conditional: true # only applies where we hold a LIVE repository read # 0.18.2 (roadmap#219) — AND only where the published delivery model says the product # itself is open source (delivery_model.open_source true, the roadmap#41 deriver's # stricter answer). A live read of SOME repository was the whole gate before, so # Apigee scored 85.0 on a CLI for a closed platform and Azure APIM 100.0 on a gateway # component of a closed SaaS — four adjacent-repo providers moved the API Management # cohort's facet average 44.7 -> 47.0 and reversed roadmap#39's sign. The description # below always said "open source ONLY"; the gate now enforces it. ~698 providers keep # the facet, ~446 go N/A (excluded from their denominator, never zeroed). requires_open_source_delivery: true label: Open Source Surface description: > For providers whose product is itself open source ONLY: does the repository publish the maintainership surface a consumer needs in order to depend on it? A vulnerability-disclosure path, a documented contribution route, a published release history, and a stated code of conduct. Not applied to closed-source products — a company with no CONTRIBUTING.md is not deficient, it is differently shaped. Not applied where the repository could not be read, either: unreadable is not missing. upsert: weight: 0.10 conditional: true # only applies where the provider ACCEPTS WRITES label: Create-or-Update Ergonomics # 0.20.0 (roadmap#270) — WRITE ERGONOMICS, which no other facet reaches. The # contract facets ask whether an API is described and callable, never whether it # is safe to call twice. # # WHY CONDITIONAL, and this is the whole design. 82.7% of providers that accept # writes offer no create-or-update, and 1,125 providers with a parseable contract # accept no writes at all. A weather or reference API cannot upsert; scoring it 0 # would dock it for a capability it has no business having. So the facet applies # ONLY where we parsed a contract AND found write operations in it. Absent # evidence is N/A, never zero — the same distinction open_source draws between # `unreachable` and a provider that failed to publish, and the one this catalog # gets wrong most often (roadmap#199, #216, #217, #171). # # RE-CENTRED, for the reason 0.12 re-centred `regulatory`. Uncentred at w=0.10 a # provider with no upsert loses a tenth of its composite — 5,635 providers docked # ~6 points each for lacking something 0.3% of the catalog has. That is not a # measurement, it is a rubric picking a fight. Scored against the observed mean # instead: a provider AT the mean is unchanged, above it gains, below it loses a # little. See `recentre_mean`. # Measured 2026-09-07 by the SCORER, over the 6,775 providers it actually applies the # facet to — not the 6,803 the evidence file marks scorable. 28 carry a contract but no # catalog page, so re-centring never touches them and averaging them in would describe a # population the number is not used on. recentre_mean: 7.06 description: > For providers that ACCEPT WRITES only: can a caller create-or-update in one call, keyed on an identifier the caller already holds, and does the response say which branch ran? Without it every write needs a hand-rolled search-and-branch in front of it, and the first time that check is skipped the customer's records grow a duplicate. A provider that ships it has made a checkable commitment about who owns identity resolution — them, not the integrator. Not applied to read-only APIs, and not applied where no contract could be parsed: a reference API is not deficient for being unable to upsert. # --------------------------------------------------------------------------- # Conditional composite math (schema 0.5+) # # The six base facets above have weights that sum to 1.0. TWO facets are # CONDITIONAL and fold into the composite only when they apply: # # regulatory (0.15) the provider's tags match a regime in industry_regulatory # open_source (0.10) we hold a LIVE read of the provider's product repository # # Generalised in 0.11 to N conditional facets. Each applicable one takes a fixed # slice; the base facets scale to whatever remains: # # base = Σ(base_weight[f] × facet[f]) # 6 facets, weights sum to 1.0 # W = Σ(weight[c]) over APPLICABLE conditional facets # composite = (1 − W) × base + Σ(weight[c] × facet[c]) # # This reduces exactly to the 0.5 single-conditional form, so no provider that # is neither regulated nor open source moves at all. A provider that is BOTH # carries 0.25 of conditional weight and 0.75 of base. # # A regulated provider that publishes no regulatory posture takes a real hit # (0.15 × 0) and one with a strong posture is rewarded; the same holds for # open source at 0.10. Both are always computed and stored so their panels # render, but only enter the composite when they apply. # # WHY open_source IS ADDITIVE AND NOT AN EXEMPTION (roadmap#39). The obvious fix # for open-source providers scoring thin on commercial_clarity — no pricing page, # no SLA — is to exempt them from it. That is wrong and it was measured: exemption # shrinks the denominator and strips a provider of points it DOES earn, costing # WSO2 a band. Exemption treats a difference as an absence. So nothing is removed; # a facet is added, scoring the surface an open-source provider actually publishes # on the same standard as everyone else. # --------------------------------------------------------------------------- # --------------------------------------------------------------------------- # industry_regulatory — the applicability map. A provider is "regulated" when # any of its (case-insensitive) tags match a regime's `tags`. This map is the # knob to iterate as new sectors are scored — add a regime or widen its tags # here, never in code. Tags are matched against the provider's top-level `tags`. # # MATCHING CHANGED IN 0.6 — MOST SPECIFIC WINS, NOT FIRST DECLARED. # 0.5 took the first regime in declaration order that matched any tag, and that # produced a confirmed, measured bug: `securities_market_data` claimed the bare # tags `broker`, `brokerage` and `exchange`, which insurance brokers, broker # networks and brokerage-technology vendors match cleanly. Sixteen of 35 UK, ten # of 20 Canadian and seven of 20 Australian insurance organizations were scored # against MiFID II — Beazley, a Lloyd's syndicate, among them. The `insurance` # regime existed and was well drawn; it was simply losing a race it should # never have been in. # # 0.6 scores EVERY matching regime and keeps the one with the most tag hits, # breaking ties by `specificity` (higher wins) and then declaration order. A # Lloyd's syndicate tagged `insurance, broker, underwriting, claims` now returns # three hits for insurance against one for securities and lands correctly. # The ambiguous tags are additionally demoted out of `tags` into `weak_tags`, # which count toward a match only when no strong tag matched anywhere. # --------------------------------------------------------------------------- # --------------------------------------------------------------------------- # 0.12 (roadmap#34 pt 4) — REGIME-RELATIVE REGULATORY SCORING. # # THE DEFECT. The composite folds a conditional facet in as # composite = base + 0.15 * (reg - base) # so the facet ADDS when reg > base and SUBTRACTS when reg < base. Catalog-wide # the regulatory facet means 23.8 against a much higher base, so it dragged every # correctly-identified regulated provider DOWN. Measured on the US payments # cohort: it lowered the composite for 38 of 57 regulated providers, mean -1.06, # Plaid -4.9. Braintree, Fireblocks, Socure and WEX carry NO TAGS and kept their # full score. Being described well was a penalty; being described poorly was a # reward. That inverts what the facet is for. # # THE FIX, decided 2026-08-17: regulated providers are compared ONLY TO EACH # OTHER. The reference point becomes the regime, not the catalog: # composite = base + 0.15 * (reg - regime_mean) # A provider AT its regime mean contributes zero delta and scores exactly `base`. # Above its peers it gains; below its peers it loses. The systematic drag goes to # ZERO BY CONSTRUCTION, because the mean of (reg - regime_mean) within a regime is # zero by definition. # # WHY A FROZEN CONSTANT AND NOT A LIVE PERCENTILE. A live within-cohort ranking # would destroy absolute meaning (if no bank implements FAPI the top bank still # scores well, so the facet would CONCEAL the gap it exists to expose), make # regimes non-comparable, and — worst — move a provider's score when someone else # joins the catalog. That breaks the contract that makes this legitimate rather # than an accusation: publish an artifact, get rescored. These means are measured # once per rubric version, published here, and snapshotted with the rubric. # # THE GUARD. Calibration stops at the FACET. Check-level pass rates stay RAW and # are never normalised — that is where a whole market failing has to stay visible, # and it is what the Market Reports publish. # # Measured 2026-08-17 over 8,327 providers holding a 0.11.0 artifact with a regime. # THE HORIZONTAL QUESTION, settled 2026-09-19 (roadmap#443). # # roadmap#443 argued that this re-centering cannot work for a HORIZONTAL regime — one whose cohort # is effectively the whole catalog — because "the re-centred delta sums to zero across the whole # population", so the facet "would cost compute and move nothing". # # THE ARITHMETIC IS RIGHT AND THE CONCLUSION IS WRONG, and the difference is worth writing down # because the same argument will be made again. Measured 2026-09-19 across all nine regimes, the # mean of (reg - regime_mean) is 0.0000000000 in every one — exactly as designed, and the property # the 2026-08-17 note above exists to create. # # But that is a LOCATION SHIFT. It removes the average effect and leaves the spread and the ranking # whole. Pooling the 821 scored regulated providers as one cohort — the closest thing this catalog # has to a horizontal population: # # stdev of the delta ................ 8.03 # range ............................. -13.7 .. +41.0 # composite shift at p5 / p95 ....... -2.06 / +1.83 # providers moving >= 0.5 points .... 652 of 821 (79%) # # Four providers in five move by half a composite point or more. A horizontal regime re-centred on # its own mean says "this provider's regulatory posture against the average provider's", which is a # real comparison and arguably a better one than comparing a health provider only to other health # providers. Nor is it a copy of `base`: base measures contract quality and ergonomics, this # measures regulatory posture, and re-centring one does not turn it into the other. # # SO NO SPECIAL HANDLING IS ADOPTED FOR HORIZONTAL REGIMES. The three options roadmap#443 offered — # absolute undamped, re-centre on jurisdiction, or a standalone axis — were all answers to a # degeneracy that does not occur. If a standalone axis is wanted later it should be argued on its # own merits ("regulatory posture is a different question from contract quality", the Agent # Readiness precedent), NOT on the maths. # # WHAT WOULD ACTUALLY MAKE THE FACET INERT is a collapsed SPREAD, not a zero mean: a cohort whose # members all score the same contributes nothing, silently and plausibly, which is the roadmap#43 # shape. test_release_023.rb pins that, and separately refuses a horizontal regime being added to # `industry_regulatory` while this note stands, so the question cannot be reopened by accident. regime_means: _default: 16.0 # all-SECTORAL mean; a sectoral regime with no cohort yet. Never the fallback. _measured_at: '2026-10-15' _rubric: 0.24.0 # RE-MEASURED on build day: #797 adds a regime and a check (reg_biometric_retention_policy) _n: 27830 # 0.24.0 -- measured 2026-10-15 on the full candidate snapshot (28,952 rows), regulatory facet value # per member, zeroed/defunct excluded (1,122 rows). 0.23.0 values: horizontal 15.6 (n=16589), # health 12.4, payments 19.7, energy_utilities 13.3, education 18.6, government 13.1, insurance 16.7, # banking_open_finance 20.6, securities_market_data 20.9, employment_payroll 18.8, telecommunications # 20.2; ai_biometrics 17.9 (2026-10-08). Horizontal falls because #797 took 759 above-mean members. # 0.23.0 — measured 2026-09-25 on a full candidate snapshot (27,448 rows), final 0.23 code, the # regulatory facet's own value per member, DEFUNCT EXCLUDED (1,096 rows, exactly the set # defunct_lifecycle? names: zero_defunct! blanks their facets, so counting them would drag every # mean toward 0 for companies that are not scored). The means fall by about a third against 0.12.0, # which is the arithmetic of #444, not a change in providers: the facet went 108 -> 164 points and # the 56 new points are almost unearned, so a 0.12 mean of 32.5 lands near 32.5 x 108/164 = 21.4 # before anything else moves. Re-centring against the stale means would have docked every # regulated provider about 0.15 x (old - new) composite for checks nobody can satisfy yet. # # The previous values, kept for the record: health 18.7 (n=2783), payments 32.5 (1335), # energy_utilities 19.4 (920), government 21.7 (836), education 27.6 (834), insurance 27.2 (719), # banking_open_finance 31.1 (641), securities_market_data 35.2 (475), telecommunications 29.5 (448), # employment_payroll 35.3 (430, candidate 2026-09-17); _default 24.9, n=8991, rubric 0.12.0. horizontal: 15.1 # n=16991 median 12.7 health: 12.1 # n=3209 median 10.9 payments: 19.5 # n=1392 median 17.9 energy_utilities: 13.2 # n=1035 median 10.8 education: 18.4 # n=880 median 16.7 government: 13.3 # n=852 median 10.8 insurance: 16.6 # n=691 median 12.3 banking_open_finance: 20.4 # n=644 median 15.7 securities_market_data: 20.6 # n=515 median 20.4 employment_payroll: 18.8 # n=429 median 16.7 telecommunications: 20.4 # n=433 median 16.7 ai_biometrics: 17.9 # n=759 median 16.4 # --------------------------------------------------------------------------------------------- # DOES JURISDICTION GATE ANYTHING? NO — DECIDED 2026-09-19 (roadmap#445, roadmap#85). # # `regime_jurisdictions` below has carried the note "NOTHING READS THIS YET" since roadmap#85. # That stays true in 0.23.0, and this is the written decision roadmap#445 asked for rather than # another deferral. # # THE COVERAGE, RE-MEASURED TODAY. `network/_data/provider_countries.json` resolves a country for # 3,451 of 28,564 providers — 12.08%. Its own `note` field states the basis: # # "a FIRST APPROXIMATION derived from provider tags, not a legal determination of where a # company operates" # # Both halves matter and the second matters more. A tag is an establishment guess; territorial # scope is about where you SELL. GDPR, the AI Act, the CRA and the EAA all reach a provider who # merely places a product on the EU market, so a provider with no `Germany` tag is very often in # scope of EU law anyway. The signal we have is the wrong KIND of signal for the question, and # improving its coverage would not fix that. # # SO: the fourteen regulatory-posture checks added in this release (roadmap#444) apply to every # provider, unconditionally. No check reads `regime_jurisdictions`, and none may. # # THE ALTERNATIVE WAS WORSE, WHICH IS THE ACTUAL ARGUMENT. Conditioning on a 12%-coverage # tag-derived approximation produces a regulatory layer that applies to a twelfth of the catalog # while presenting as universal: 88% of providers would be silently skipped, and a skip reads as # compliance. That is the `kin-score-silent-zero-paths` shape — a near-miss scoring identically # to publishing nothing — and it is the failure this rubric has paid for most often. # # Scoring everybody is also defensible on the merits, not merely as the lesser evil: a provider # that publishes an accessibility conformance report or a vulnerability disclosure policy is # better off for it in every jurisdiction, so there is no jurisdiction in which the horizontal # checks measure the wrong thing. # # MEASURED 2026-09-19, and it is four times the tag signal (roadmap#451). A stratified sample of # 180 providers across six jurisdictions, probing the surfaces providers actually publish — trust, # compliance, privacy and pricing pages: # # resolve to at least one market 93/180 51.7% # ...at least one STATED by them 88/180 48.9% # # europe 52 stated | united-kingdom 32 | canada 29 | united-states 12 | australia 11 # # against the 12.08% this tag-derived map resolves. `stated` means the provider NAMES the regime — # UK GDPR, PIPEDA, Privacy Act 1988 — rather than it being inferred from a currency or a region # code, and the two are never collapsed. # # THIS IS NOT YET A GATE AND MUST NOT BECOME ONE WITHOUT A DECISION. It is the reviewable number # roadmap#445 asked for: the next release can weigh 48.9% stated market access against 12.08% # tag-derived establishment and decide deliberately. No check reads it, and the guard in # test_release_023.rb still refuses any check that reads `regime_jurisdictions`. # # WHAT WOULD REOPEN THIS. Not a higher percentage of the same signal. A market-access signal — # marketplace listings, data-residency pages, subprocessor lists (roadmap#451, roadmap#453) — # which says where a provider SELLS rather than where it is guessed to sit. If that lands, the # gate becomes arguable and the floor question becomes real: below what coverage does it not # apply, and does an unresolved provider skip, default in, or score `na`. Until then there is no # gate, so there is no unstated skip. # # test_release_023.rb pins this: no check may name `regime_jurisdictions` while this note stands. industry_regulatory: # THE HORIZONTAL REGIME (roadmap#442). Kin's call, 2026-09-19: ship it. # # FIRST IN THE MAP AND LAST TO MATCH. It declares no `tags`, so it can never win the strong or # weak tag contest — `fallback: true` is the only way a provider reaches it, and only after every # sectoral regime has failed to match. It is written first purely so a reader meets it before the # nine sectoral regimes it sits underneath. # # WHY IT EXISTS. 19,151 of 28,564 provider pages (67.0%) carried no regulatory facet at all, and # the silence read as a pass. That was never because no law reached them — it was because every # law that reaches them is horizontal: it binds a company for what it does with data, software or # customers, not for the sector it files itself under. # # AN UNTAGGED PROVIDER REACHES THIS TOO, which is a deliberate reversal of the 0.12 behaviour # directly above in `regulatory_regime_for`. roadmap#34 made an untagged provider `undetermined` # rather than unregulated, because inventing a SECTOR from no evidence would be worse than # admitting ignorance. A horizontal regime needs no such evidence: GDPR does not ask what industry # you are in. So "we do not know your sector" stops being a reason to score no regulatory posture # at all. The `undetermined` state survives for the SECTOR question, which is what it was for. # # WHAT SHIPPING THIS COSTS, MEASURED AND ACCEPTED RATHER THAN DISCOVERED LATER. Of the 68 points # the roadmap#444 checks add, 8 are reachable today — TermsOfService on 12,513 repos (43.8%) and # PrivacyPolicy on 13,911 (48.7%). The other 56 points across 10 checks are satisfiable by NO # provider in the catalog: SBOM, SupportLifetime, AccessibilityConformance, TrainingDataSummary, # GlobalPrivacyControl, DataSubjectRequest, AgeAssurance, NoticeAndAction, TransparencyReport and # ExitAssistance are all on zero repos; Subprocessors is on 10, AITransparency, DataResidency and # IncidentNotification on 1 each. # # So this facet is close to two-valued for the newly-scored population on day one, and that is # the point rather than an objection to it: a rubric that never asks can never drive adoption, # and the published rubric is what tells a provider the artifact exists. The 0% rows are the # work list. # # THIS DELIBERATELY REOPENS THE roadmap#443 GUARD. That guard refused a horizontal regime in # `industry_regulatory` so the question could not be reopened BY ACCIDENT — not because the # answer was no. It has now been reopened on purpose, with the numbers above, and the guard in # test_release_023.rb is updated to permit exactly this one fallback regime and nothing else. # # REGIME MEANS ARE NOT OPTIONAL HERE, THEY ARE LOAD-BEARING. `regime_mean_for` falls back to # `_default` (24.9, the all-regulated mean) for any regime with no recorded mean. Subtracting # 24.9 from a cohort that scores single digits is roughly -3.0 composite points on 19,151 # providers, applied silently. test_release_023.rb fails until `regime_means.horizontal` is # measured against this facet. Do not paper that over with a guess. horizontal: label: Horizontal (data, software, accessibility, platform) specificity: 0 fallback: true regimes: [GDPR (EU/UK), EU AI Act, Cyber Resilience Act (EU), European Accessibility Act (EU), Digital Services Act (EU), Online Safety Act (UK), US state privacy laws, BIPA (Illinois), DOJ bulk sensitive data rule (US), CASL (Canada)] # Declared, and read by NOTHING — see the jurisdiction decision above. A horizontal regime is # the case that makes the point: a provider with no country resolved is still reached by most # of this list, because territorial scope follows the market, not the head office. regime_jurisdictions: "GDPR (EU/UK)": [europe, united-kingdom] "EU AI Act": [europe] "Cyber Resilience Act (EU)": [europe] "European Accessibility Act (EU)": [europe] "Digital Services Act (EU)": [europe] "Online Safety Act (UK)": [united-kingdom] "US state privacy laws": [united-states] "BIPA (Illinois)": [united-states] "DOJ bulk sensitive data rule (US)": [united-states] "CASL (Canada)": [canada] basis: > Obligations that attach to what a company does with data, software and customers rather than to the sector it operates in: privacy and data-subject rights, AI transparency, software supply chain and support lifetime, accessibility conformance, incident notification, and platform duties. # NO `tags` AND NO `weak_tags`, ON PURPOSE. A tag list here would make this regime compete with # the sectoral ones in the matcher, and specificity 0 would lose every contest anyway. Reached # only via `fallback: true`, after every sectoral regime has been tried and missed. tags: [] standards: [] banking_open_finance: label: Banking & Open Finance specificity: 3 regimes: [CDR (Australia), UK Open Banking, PSD2/PSD3 (EU), 1033 (US), FDX] # roadmap#85 — THE JURISDICTION, AS A FIELD. `regimes` above is display prose with the # jurisdiction buried in the label text, where nothing can read it: extracting a trailing # parenthetical finds 20 of 42, misses the prefix forms (`UK Open Banking`, `Green Button # / ESPI`) and false-positives on `CPNI`, which is not a jurisdiction. # # Slugs, in the SAME vocabulary as provider_countries.json / provider_regions.json, so the # two can be joined. ISO codes would join nothing. # # An EMPTY list is a STATED fact, not a gap: FDX and ISO 20022 are industry bodies, PCI-DSS # and card-network rules are contractual, ITU is a treaty organisation. 32 of 42 name a # jurisdiction; 10 genuinely do not. # # NOTHING READS THIS YET — it does not choose the regime set. That moves scores for 3,210 # providers and belongs to a later version. This makes the join possible. regime_jurisdictions: "CDR (Australia)": [australia] "UK Open Banking": [united-kingdom] "PSD2/PSD3 (EU)": [europe] "1033 (US)": [united-states] "FDX": [] basis: > Consumer-permissioned data sharing and payment access, mandated or standardized: consent-scoped OAuth/OIDC (often FAPI), a named data standard, and a security + disclosure posture. tags: [banks, banking, open banking, open finance, cdr, consumer data right, psd2, psd3, 1033, fdx, consumer banking, neobank, building society, credit union, mutual bank, digital bank] standards: [obie, uk-open-banking, cdr-banking, consumer-data-standards, fdx, berlin-group-nextgenpsd2, fapi, fapi-2] securities_market_data: label: Securities & Market Data specificity: 2 regimes: [MiFID II (EU), SEC/FINRA (US), exchange data licensing, market-data redistribution] # roadmap#85 — THE JURISDICTION, AS A FIELD. `regimes` above is display prose with the # jurisdiction buried in the label text, where nothing can read it: extracting a trailing # parenthetical finds 20 of 42, misses the prefix forms (`UK Open Banking`, `Green Button # / ESPI`) and false-positives on `CPNI`, which is not a jurisdiction. # # Slugs, in the SAME vocabulary as provider_countries.json / provider_regions.json, so the # two can be joined. ISO codes would join nothing. # # An EMPTY list is a STATED fact, not a gap: FDX and ISO 20022 are industry bodies, PCI-DSS # and card-network rules are contractual, ITU is a treaty organisation. 32 of 42 name a # jurisdiction; 10 genuinely do not. # # NOTHING READS THIS YET — it does not choose the regime set. That moves scores for 3,210 # providers and belongs to a later version. This makes the join possible. regime_jurisdictions: "MiFID II (EU)": [europe] "SEC/FINRA (US)": [united-states] "exchange data licensing": [] "market-data redistribution": [] basis: > Licensed market data and securities activity: entitlement and redistribution terms, licensing/compliance disclosure, and auditability. # 0.10.4 — the securities-specific COMPOUNDS are promoted to the strong tier # so the weak tier can stop matching word fragments (roadmap#42). Each one is # a whole tag carried by real securities firms in the catalog: broker-dealer # 12 providers, prime brokerage 11, algorithmic trading 11, spot trading 8, # crypto exchange 8, stock trading 6, social trading 6, copy trading 6, # electronic trading 4, fx trading 4. Without these, phrase-only matching # would un-regulate Citadel Securities, Tradeweb, Trumid and Alpaca. tags: [market data, securities, stock exchange, order execution, mifid, mifid ii, finra, sec, otc, derivatives, equities, market-data, broker-dealer, broker dealer, prime brokerage, algorithmic trading, electronic trading, proprietary trading, stock trading, spot trading, fx trading, forex trading, copy trading, social trading, options trading, futures trading, exchange-traded fund, exchange traded fund, etf, decentralized exchange, cryptocurrency exchange, crypto exchange, securities lending, market maker, market making, order book, trading platform, trading api, brokerage account] # `broker`, `brokerage` and `exchange` are shared with insurance, freight, # energy and crypto. They match ONLY when nothing else matched — see the # note on most-specific matching above. weak_tags: [exchange, brokerage, broker, trading] standards: [fix-protocol, mifid-ii, iso-20022] health: label: Health specificity: 3 regimes: [HIPAA (US), FHIR / US Core, 21st Century Cures Act, EHDS (EU)] # roadmap#85 — THE JURISDICTION, AS A FIELD. `regimes` above is display prose with the # jurisdiction buried in the label text, where nothing can read it: extracting a trailing # parenthetical finds 20 of 42, misses the prefix forms (`UK Open Banking`, `Green Button # / ESPI`) and false-positives on `CPNI`, which is not a jurisdiction. # # Slugs, in the SAME vocabulary as provider_countries.json / provider_regions.json, so the # two can be joined. ISO codes would join nothing. # # An EMPTY list is a STATED fact, not a gap: FDX and ISO 20022 are industry bodies, PCI-DSS # and card-network rules are contractual, ITU is a treaty organisation. 32 of 42 name a # jurisdiction; 10 genuinely do not. # # NOTHING READS THIS YET — it does not choose the regime set. That moves scores for 3,210 # providers and belongs to a later version. This makes the join possible. regime_jurisdictions: "HIPAA (US)": [united-states] "FHIR / US Core": [united-states] "21st Century Cures Act": [united-states] "EHDS (EU)": [europe] basis: > Protected health information and interoperability mandates: FHIR conformance, consent, HIPAA-grade security, and info-blocking posture. tags: [health, healthcare, clinical, ehr, emr, fhir, medical, patient, health data, life sciences, pharma, telehealth, payer, provider network] standards: [fhir, smart-on-fhir, us-core, uscdi, da-vinci, carin-blue-button, fhir-bulk-data, cds-hooks, c-cda, hl7-v2, dicom] payments: label: Payments specificity: 3 regimes: [PCI-DSS, card-network rules, SCA/PSD2, ISO 20022] # roadmap#85 — THE JURISDICTION, AS A FIELD. `regimes` above is display prose with the # jurisdiction buried in the label text, where nothing can read it: extracting a trailing # parenthetical finds 20 of 42, misses the prefix forms (`UK Open Banking`, `Green Button # / ESPI`) and false-positives on `CPNI`, which is not a jurisdiction. # # Slugs, in the SAME vocabulary as provider_countries.json / provider_regions.json, so the # two can be joined. ISO codes would join nothing. # # An EMPTY list is a STATED fact, not a gap: FDX and ISO 20022 are industry bodies, PCI-DSS # and card-network rules are contractual, ITU is a treaty organisation. 32 of 42 name a # jurisdiction; 10 genuinely do not. # # NOTHING READS THIS YET — it does not choose the regime set. That moves scores for 3,210 # providers and belongs to a later version. This makes the join possible. regime_jurisdictions: "PCI-DSS": [] "card-network rules": [] "SCA/PSD2": [europe] "ISO 20022": [] basis: > Cardholder and payment data: PCI-DSS scope, strong customer authentication, and a security + disclosure posture. tags: [payments, payment, card, cards, acquiring, issuing, pci, pci-dss, merchant, checkout, wallet, payment gateway] standards: [pci-dss, 3-d-secure, iso-20022, confirmation-of-payee, emv, psd2-sca, open-payments] insurance: label: Insurance specificity: 4 regimes: [NAIC/solvency, open insurance, IDD (EU), state DOI rules] # roadmap#85 — THE JURISDICTION, AS A FIELD. `regimes` above is display prose with the # jurisdiction buried in the label text, where nothing can read it: extracting a trailing # parenthetical finds 20 of 42, misses the prefix forms (`UK Open Banking`, `Green Button # / ESPI`) and false-positives on `CPNI`, which is not a jurisdiction. # # Slugs, in the SAME vocabulary as provider_countries.json / provider_regions.json, so the # two can be joined. ISO codes would join nothing. # # An EMPTY list is a STATED fact, not a gap: FDX and ISO 20022 are industry bodies, PCI-DSS # and card-network rules are contractual, ITU is a treaty organisation. 32 of 42 name a # jurisdiction; 10 genuinely do not. # # NOTHING READS THIS YET — it does not choose the regime set. That moves scores for 3,210 # providers and belongs to a later version. This makes the join possible. regime_jurisdictions: "NAIC/solvency": [united-states] "open insurance": [] "IDD (EU)": [europe] "state DOI rules": [united-states] basis: > Policyholder data and market conduct: consent, disclosure, and standards conformance where an open-insurance regime exists. # 0.23 (roadmap#431): `policy` is removed. Word-expanded as a strong tag it put 48 # policy-as-code, authorization and network-policy companies (Calico, Kyverno, Cerbos, Azure # Policy...) in this regime, and even as a whole tag it is ambiguous: Azure Policy is tagged # `Policy` and is not an insurer. Modelled as a weak tag first, it still held Azure Policy. # Insurance-specific compounds carry the real carriers. `policy management` is NOT one: it # is the policy-as-code category (Kyverno). tags: [insurance, insurtech, underwriting, claims, actuarial, reinsurance, broker network, lloyds, syndicate, p&c, life insurance, health insurance, general insurance, insurance policy, policy administration, policyholder] standards: [acord, acord-al3, acord-xml, ngds, grlc, cieca-bms, csio, market-reform-contract] telecommunications: label: Telecommunications specificity: 4 regimes: [FCC / Communications Act (CPNI), Ofcom / Communications Act 2003, ACMA / Telecommunications Act, ITU Constitution, ePrivacy Directive] # roadmap#85 — THE JURISDICTION, AS A FIELD. `regimes` above is display prose with the # jurisdiction buried in the label text, where nothing can read it: extracting a trailing # parenthetical finds 20 of 42, misses the prefix forms and false-positives on `CPNI`. # # Slugs, in the SAME vocabulary as provider_countries.json / provider_regions.json, so the # two can be joined. An EMPTY list is a STATED fact, not a gap — ITU is a treaty body. # # NOTHING READS THIS YET; it does not choose the regime set. regime_jurisdictions: "FCC / Communications Act (CPNI)": [united-states] "Ofcom / Communications Act 2003": [united-kingdom] "ACMA / Telecommunications Act": [australia] "ITU Constitution": [] "ePrivacy Directive": [europe] basis: > Network capability exposed as an API, over exactly the subscriber data the CPNI and ePrivacy regimes restrict: number verification, SIM swap, device location, and the consent surface each requires. Added in 0.6 — scoring 83 telecom organizations under 0.5 fired the conditional facet for only seven of them, via Government, Payments and Health, leaving a sector supervised by four national regulators with no regulatory layer at all. 0.10.1 REMOVED `voice` and `messaging` from this list. Both are product words that mean something else almost everywhere they appear, and this regime is drawn around CARRIER NETWORK CAPABILITY — the basis above says so. `messaging` in this catalog overwhelmingly means a message queue, not a telephone network: it was matching Apache ActiveMQ, Apache RocketMQ, AMQP and Apache ServiceMix into the FCC's CPNI rules. `voice` was matching `amazon` on Alexa. Measured over all 26,598 catalog apis.yml, the regime goes from 639 matches to 303; 315 providers become unregulated and 21 move to a regime that fits them better. Reported by rtcStats, a WebRTC observability tool matched to four national telecom regulators on the single tag `voice` (api-evangelist/rtcstats#1). Nothing real is lost: every genuine CPaaS and carrier carries a strong tag independently — Twilio `SMS`, Vonage `Telecommunications`, Bandwidth and Sinch `CPaaS`, Infobip all of them. `sms` is KEPT as a strong tag because it names telephone numbering rather than a generic product category. This is the same defect class as the `broker`/`exchange` over-match fixed for securities_market_data in 0.6, which was closed with `weak_tags`. weak_tags is NOT the right instrument here: a weak tag still matches when no other regime does, and these providers match no other regime, so ActiveMQ and rtcStats would have stayed telecom by a different route. Removal is the fix. tags: [telecom, telecommunications, telco, carrier, mobile network operator, mno, mvno, cpaas, sms, network api, camara, open gateway, sim, roaming, number verification, subscriber] standards: [camara, tm-forum-open-api, gsma-open-gateway, ciba, 3gpp, mef, etsi] energy_utilities: label: Energy & Utilities specificity: 4 regimes: [CDR Energy (Australia), Green Button / ESPI (North America), Smart Energy Code + DCC (GB), Ofgem Data Best Practice, FERC Order 889 / OASIS (US)] # roadmap#85 — THE JURISDICTION, AS A FIELD. `regimes` above is display prose with the # jurisdiction buried in the label text, where nothing can read it: extracting a trailing # parenthetical finds 20 of 42, misses the prefix forms and false-positives on `CPNI`. # # Slugs, in the SAME vocabulary as provider_countries.json / provider_regions.json, so the # two can be joined. An EMPTY list is a STATED fact, not a gap — ITU is a treaty body. # # NOTHING READS THIS YET; it does not choose the regime set. regime_jurisdictions: "CDR Energy (Australia)": [australia] "Green Button / ESPI (North America)": [united-states, canada] "Smart Energy Code + DCC (GB)": [united-kingdom] "Ofgem Data Best Practice": [united-kingdom] "FERC Order 889 / OASIS (US)": [united-states] basis: > Customer energy data and network open data, both increasingly compelled: a consumer data right over usage and billing, and "presumed open" network data published under licence conditions. Added in 0.6 — the energy quartet measured a verified mandate as worth about twelve points of composite, the largest single effect in the series, against a regime that did not exist in the map. tags: [energy, utilities, utility, electricity, gas, power, grid, smart meter, smart metering, distribution network, dso, dno, energy retailer, green button, renewables, ev charging, water utility] standards: [green-button, espi, cds-energy, cds-common, smart-energy-code, ieee-2030-5, openadr] # 0.12 (roadmap#34, and the university research). 119 of 300 university # providers were being scored against GOVERNMENT because a tag brushed it, and # the regimes their own profiles found binding -- FERPA, UK GDPR in an education # setting, UGC, PIPA -- were in this map nowhere at all. # # specificity 3 so it beats `government` (2) on a multi-tag match, following the # most-specific-wins rule that fixed the insurance-broker collision in 0.6. A # public university genuinely carrying public-sector obligations still matches # `government` on its government tags; the tie-break does the work. # # DELIBERATELY NOT HERE: a check for scoping institutional AI use against a # named regulation. It was proposed for this regime and it belongs in the # standalone `accountability` layer instead -- that is organisational posture, # not a property of the API surface, and carrying it twice was the same # collision the governance rename exists to fix. # # OPEN, and recorded rather than papered over: FERPA, UK GDPR + the Equality # Act, the EU AI Act, UGC and PIPA are not one posture. A single regime may # repeat the `government` mistake at smaller scale, and per-jurisdiction # sub-regimes may be the right shape once a cohort is scored. education: label: Education & Research specificity: 3 regimes: ['FERPA (US)', 'Title IV / IPEDS (US)', 'UK GDPR + Equality Act 2010', 'GDPR (EU)', 'UGC (India)', 'PIPA (Korea)', 'QAA (UK)'] # roadmap#85 — THE JURISDICTION, AS A FIELD. `regimes` above is display prose with the # jurisdiction buried in the label text, where nothing can read it: extracting a trailing # parenthetical finds 20 of 42, misses the prefix forms and false-positives on `CPNI`. # # Slugs, in the SAME vocabulary as provider_countries.json / provider_regions.json, so the # two can be joined. An EMPTY list is a STATED fact, not a gap — ITU is a treaty body. # # NOTHING READS THIS YET; it does not choose the regime set. regime_jurisdictions: "FERPA (US)": [united-states] "Title IV / IPEDS (US)": [united-states] "UK GDPR + Equality Act 2010": [united-kingdom] "GDPR (EU)": [europe] "UGC (India)": [india] "PIPA (Korea)": [south-korea] "QAA (UK)": [united-kingdom] basis: > Student records, research data and institutional accountability: student-data protection, accessibility obligations, provisioning between institutional systems, and identity federation. tags: ['university', 'universities', 'higher education', 'college', 'campus', 'student', 'student information system', 'sis', 'academic', 'research information', 'institutional repository', 'scholarly', 'learning management', 'edtech', 'education', 'school', 'registrar', 'admissions', 'courseware', 'library'] # 0.23 (roadmap#427): `lms` alone is weak. Bindbee's LMS is one namespace of an HR integration # product, and it put an HRIS/payroll API in this regime. weak_tags: ['lms'] standards: ['scim', 'lti', 'oneroster', 'ed-fi', 'caliper', 'qti', 'oai-pmh', 'shibboleth', 'saml', 'orcid', 'datacite', 'crossref'] # 0.23 (roadmap#427) — EMPLOYMENT & PAYROLL. Global payroll and EOR are among the most regulated API # surfaces in the catalog and the rubric could not see them: Deel and Remote matched nothing, Papaya # matched Payments, and Bindbee matched Education on its LMS namespace. employment_payroll: label: Employment & Payroll specificity: 3 regimes: ["GDPR Art. 88 (EU)", "FLSA / IRS payroll (US)", "HMRC RTI (UK)", "AML/KYC on contractor payouts"] regime_jurisdictions: "GDPR Art. 88 (EU)": [europe] "FLSA / IRS payroll (US)": [united-states] "HMRC RTI (UK)": [united-kingdom] "AML/KYC on contractor payouts": [] basis: > Employee data and payroll: worker consent and data minimisation, statutory tax and reporting, and screening on cross-border contractor payouts. tags: [payroll, global payroll, employer of record, eor, peo, contractor of record, hris, hcm, human capital management, employment verification] # bare `employment` word-expands onto `Employee Engagement` / `Employee Experience`; phrase-only. weak_tags: [human resources, employment] standards: [hr-open, scim, saml, soc2] # 0.24 (roadmap#797) — AI & BIOMETRICS. Kin's call, 2026-10-03: a specific regime above the fallback. # # WHY. 18,324 providers sat on `horizontal`, which names the EU AI Act and BIPA in a list of ten. # A voice-cloning or face-recognition company was held to them only as one horizontal company # among eighteen thousand, compared against that cohort's mean. ElevenLabs (roadmap#797) was the # case that surfaced it. # # WHERE IT SITS. `yields_to_sectoral: true` — tried only after every sectoral regime, strong AND # weak, has missed, and before the fallback (score.rb `residual_regime_for`). It therefore moves # providers OFF the fallback and nowhere else: 176 providers that carry these tags AND a sector # (health, payments, banking...) keep their sector and its sharper checks. The AI and biometric # laws still reach them; the biometric retention-policy check below follows the data, not the # regime, so it asks of the sectoral biometric providers too. # # SCOPE: NOT "AI GENERALLY", AND NOT "HIGH-RISK ONLY". Membership is AI whose product is the # regulated capability: # - biometric processing — face, voice, fingerprint, iris, liveness, emotion recognition and # deepfakes. EU AI Act Art. 5 (prohibited: untargeted face scraping, emotion recognition at work # and school, sensitive biometric categorisation) and Annex III point 1 (high-risk: remote # biometric identification, biometric categorisation, emotion recognition), GDPR Art. 9, and # the three US state biometric statutes. # - generative and person-facing AI — models, LLMs, synthetic voice/image/video, chatbots. EU AI # Act Art. 50 (disclose AI interaction, machine-readable marking of synthetic content — in # application since 2 August 2026) and Art. 53-55 (general-purpose AI model duties, since # 2 August 2025). These are not high-risk duties: they apply whatever the risk tier. # Generic tags — `Artificial Intelligence`, `Machine Learning`, `AI Agents`, `Computer Vision` — # do NOT place a provider here. They say a company uses AI, not what its AI does, and including # them takes the regime from 765 providers to 3,947. Those stay on `horizontal`, which # already names the EU AI Act. # # NOR DOES A BARE `LLM` TAG (Kin, 2026-10-03). It is carried by gateways, observability, eval, # frameworks and inference infrastructure (Kong, vLLM, Langfuse, Pydantic AI) as much as by model # makers, and 206 providers would qualify on it alone. A model maker qualifies through # `foundation models`, `generative ai`, `large language models` and the rest; on 2026-10-03/05 the # model makers that carried only `LLM` were tagged `Foundation Models` in their own apis.yml # (roadmap#797, #813). That is the route for any model maker still missing: a tagging fix, not a # reason to put `llm` back. # # `Identity Verification` and `KYC` alone are not biometric either (KYB, e-signature and credit # bureaus carry them); biometric IDV vendors carry explicit biometric tags and match on those. # # DELIBERATELY NOT HERE: the Colorado AI Act. SB 24-205 never took effect (enforcement enjoined # 27 April 2026, D. Colo.) and was repealed and replaced by SB 26-189 (signed 14 May 2026, in # force 1 January 2027), which governs automated decision-making in CONSEQUENTIAL decisions — # lending, insurance, employment, housing, health, education. Those are sectoral regimes here, and # the companies that make such decisions are matched to them. It is a candidate for those regimes' # `regimes` lists once it is in force, not for this one. # # Sources: Regulation (EU) 2024/1689 (AI Act) as amended by the Digital Omnibus on AI (in force # 27 July 2026: Annex III high-risk moved to 2 December 2027, Art. 50 unchanged at 2 August 2026, # Art. 50(2) marking grace for existing systems to 2 December 2026); 740 ILCS 14 (BIPA) ss.15(a) # retention policy, 15(b) written consent, as amended by P.A. 103-0769 (2024); Tex. Bus. & Com. # Code s.503.001 (CUBI), as amended by HB 149 (TRAIGA, effective 1 January 2026); RCW 19.375 # (Washington biometric identifiers) and RCW 19.373 (My Health My Data Act, biometric data as # consumer health data, private right of action). ai_biometrics: label: AI & Biometrics specificity: 1 yields_to_sectoral: true regimes: ["EU AI Act Art. 5 + Annex III (biometrics)", "EU AI Act Art. 50 (transparency)", "EU AI Act Art. 53-55 (GPAI models)", "GDPR Art. 9 (biometric data)", "BIPA (Illinois)", "CUBI (Texas)", "TRAIGA (Texas)", "RCW 19.375 + My Health My Data Act (Washington)"] regime_jurisdictions: "EU AI Act Art. 5 + Annex III (biometrics)": [europe] "EU AI Act Art. 50 (transparency)": [europe] "EU AI Act Art. 53-55 (GPAI models)": [europe] "GDPR Art. 9 (biometric data)": [europe, united-kingdom] "BIPA (Illinois)": [united-states] "CUBI (Texas)": [united-states] "TRAIGA (Texas)": [united-states] "RCW 19.375 + My Health My Data Act (Washington)": [united-states] basis: > Biometric identifiers and AI systems that act on people: notice and written consent before biometric capture, a public retention and destruction schedule, no sale of biometric data, disclosure that a person is dealing with an AI system, machine-readable marking of synthetic content, and model documentation and a training-data summary for general-purpose models. # PHRASE-ONLY (whole normalised tags). The first block is the biometric surface and is repeated, # exactly, as `applies_when_tags` on reg_biometric_retention_policy. No bare `llm` (Kin, 2026-10-03). tags: [biometrics, biometric authentication, biometric identification, biometric verification, facial recognition, face recognition, face verification, face matching, face match, face authentication, face biometrics, face swap, voice biometrics, voice cloning, voice clone, speaker recognition, speaker verification, behavioral biometrics, liveness detection, liveness, liveness check, fingerprint recognition, iris recognition, palm recognition, emotion recognition, emotion ai, deepfake, deepfake detection, generative ai, genai, foundation models, large language models, language models, frontier ai, multimodal ai, multi-modal, ai models, text-to-speech, tts, speech synthesis, speech to speech, voice ai, voice agents, conversational ai, chatbots, ai assistant, ai companion, ai avatars, ai video, ai music, music generation, generative media, synthetic media, ai characters, ai voice, image generation, video generation, text-to-image, text-to-video] standards: [iso-42001, iso42001, iso-iec-42001, iso-iec-42001-2023, nist-ai-rmf, eu-ai-act, c2pa, iso-iec-30107-3, iso-30107-3] government: label: Government & Public Sector specificity: 2 regimes: [FedRAMP, eIDAS (EU), open-data standards, national gov API policy] # roadmap#85 — THE JURISDICTION, AS A FIELD. `regimes` above is display prose with the # jurisdiction buried in the label text, where nothing can read it: extracting a trailing # parenthetical finds 20 of 42, misses the prefix forms (`UK Open Banking`, `Green Button # / ESPI`) and false-positives on `CPNI`, which is not a jurisdiction. # # Slugs, in the SAME vocabulary as provider_countries.json / provider_regions.json, so the # two can be joined. ISO codes would join nothing. # # An EMPTY list is a STATED fact, not a gap: FDX and ISO 20022 are industry bodies, PCI-DSS # and card-network rules are contractual, ITU is a treaty organisation. 32 of 42 name a # jurisdiction; 10 genuinely do not. # # NOTHING READS THIS YET — it does not choose the regime set. That moves scores for 3,210 # providers and belongs to a later version. This makes the join possible. regime_jurisdictions: "FedRAMP": [united-states] "eIDAS (EU)": [europe] "open-data standards": [] "national gov API policy": [] basis: > Public-sector data and identity: security authorization, accessibility, open-data standards, and identity/eIDAS conformance. tags: [government, public sector, gov, govtech, civic, municipal, federal, state government, open data, public data] standards: [dcat, ckan, eidas, fedramp, open-data-charter] # --------------------------------------------------------------------------- # Artifact-driven checks. # Each check awards `points` toward `facet`. The facet's raw score is the sum # of awarded points; it is then normalized against `max_raw_points` for that # facet (computed at run time) to yield a 0–100 sub-score. # # All `rule` values are quoted free-text descriptions of the predicate the # scorer should implement. The scorer is the source of truth for evaluation; # this rubric is the source of truth for what counts and how much. # --------------------------------------------------------------------------- artifacts: # ------------------------------------------------------------------------- # apis.yml (provider index) # ------------------------------------------------------------------------- apis_yml: label: apis.yml spec: https://apisjson.org/ description: > The provider's APIs.json index — the root document that makes everything else findable. Every other artifact in this rubric is discovered through it. checks: - id: apis_yml_present label: Publishes an apis.yml index facet: discoverability points: 10 rule: 'source_filename == "apis.yml"' description: > The provider maintains a real APIs.json index rather than being catalogued from the outside. The single highest-value discoverability signal: it is the difference between a provider describing itself and being described. - id: description_substantive label: Substantive description facet: discoverability points: 5 rule: 'len(description) >= 200' description: > At least 200 characters of description. Enough for a human or an agent to decide whether the API is relevant without opening the site. - id: tags_present label: Tagged for discovery facet: discoverability points: 5 rule: 'len(tags) >= 5' description: > Five or more tags. Tags are how the API surfaces in topical search and how it gets placed into industries and areas rather than sitting unclassified. - id: image_present label: Provider image facet: discoverability points: 2 rule: 'image is set' description: > A logo or image is referenced, so the provider renders as a recognizable card in search results and listings instead of a bare line of text. - id: maintainer_present label: Named maintainer facet: discoverability points: 3 rule: 'maintainers[0].email is set' description: > A contactable maintainer email. Establishes that someone owns the index and gives consumers a route to reach them. - id: created_modified_dates label: Created and modified dates facet: discoverability points: 2 rule: 'created and modified both ISO dates' description: > Both timestamps present as ISO dates, so freshness is machine-readable and a consumer can tell a maintained index from an abandoned one. - id: newsroom_present label: Newsroom facet: discoverability points: 1 rule: 'common[].type includes Newsroom, PressReleases, Press or News' description: > The provider's own announcements surface, declared as a pointer. A publishing act in the same class as a Blog pointer: it makes the company's own announcements discoverable at a stable URL rather than only through a search engine. Worth exactly what a Blog pointer is worth and no more (roadmap#452). - id: leadership_present label: Leadership page facet: discoverability points: 1 rule: 'common[].type includes Leadership, LeadershipTeam, Management or ExecutiveTeam' description: > The provider's own leadership page, declared as a pointer. Scored for being published and discoverable and for nothing else — no person, no name, and no inference about any individual is read, recorded or scored (roadmap#452). - id: multiple_apis label: Indexes three or more APIs facet: discoverability points: 3 rule: 'api_count >= 3, where api_count counts the OpenAPI documents the provider publishes (openapi/_original/), not index entries split from them' description: > The provider publishes three or more distinct API contracts — a real surface rather than one document. Entries we split from a single contract (one per tag) do not count; see 0.17.0 / roadmap#146. - id: human_url_per_api label: Human URL on every API facet: discoverability points: 5 rule: 'every api has humanURL' description: > Each indexed API points at documentation a person can read. Without it, an entry is a name with nowhere to go. - id: base_url_per_api label: Base URL on every API facet: discoverability points: 5 rule: 'every api has baseURL and no baseURL contains "localhost"' description: > Each indexed API declares a real, callable base URL. A localhost base URL fails this check — it signals a spec that was published without ever being pointed at production. # --- 0.6: raise the bar from HUMAN findability to MACHINE discoverability # Measured across two quartets, 252 organizations: discoverability averages 84.6 # and NOT ONE PROVIDER SCORES ZERO in any of eight markets — including thirteen US # utilities that publish no contract at all and score 0.0 on every one of the # agent-readiness dimensions. A facet a completely absent developer surface still # scores in the eighties is not carrying information. Its bar — a findable website, # documentation, support, terms — is met by any company with a marketing # department, which in a 25,000-provider catalog is nearly all of them. # # These three raise the bar rather than cutting the weight, which is the choice # more in keeping with the agentic thesis: for an agent, a beautifully designed # marketing site is not discoverability at all. Cloudflare's top-200k scan supplies # the adoption baseline these are cut against — 4% Content Signals, 3.9% markdown # negotiation, fewer than 15 sites in 200,000 carrying an MCP Server Card or API # catalog — which is the strongest external evidence yet that machine # discoverability discriminates exactly where human findability does not. - id: well_known_published label: Serves a .well-known surface facet: discoverability points: 6 rule: 'well-known/ carries an api-catalog, security.txt, a protected-resource doc, or an AAuth resource doc' description: > The provider serves machine entrypoints at RFC 8615 well-known paths — an api-catalog linkset (RFC 9727), a security.txt, an OAuth protected-resource document. This is the address an agent tries FIRST, before it has read anything, and it is the discoverability signal a marketing site cannot fake. - id: llms_txt_published label: Publishes llms.txt facet: discoverability points: 4 rule: 'llms/ carries an llms.txt THE PROVIDER wrote, or a declared LLMsTxt pointer' description: > An llms.txt — the provider stating, in a machine-readable file at a conventional path, what a language model should read to understand the product. Young, unratified, and adopted by 6,012 providers in this catalog, which makes it the fastest-moving machine-discoverability signal there is. # 0.23 (roadmap#318) — the MCP endpoint is a machine entry point exactly like well-known # and llms.txt, and this facet could not see it. - id: mcp_endpoint_discoverable label: MCP endpoint is addressable from public information facet: discoverability points: 4 graded: true credit: addressable: 1.00 documented: 0.50 templated: 0.00 rule: 'the provider runs an MCP server; graded on whether an agent can construct its endpoint unaided' signal: '`addressable` when a concrete endpoint URL is published (probed or not; probing is agent readiness''s question), `documented` when a real server has no endpoint to construct (stdio, unclear, or a first-party pointer), `templated` when the published endpoint carries a placeholder ({tenant}, ) nothing public resolves' description: > An MCP server an agent cannot address is not discoverable, however real it is. Not applicable to a provider that runs no MCP server, so the points leave the denominator instead of marking anyone down. - id: apis_json_self_hosted label: Self-hosts the APIs.json index facet: discoverability points: 4 rule: 'apis.yml url points at a host the provider controls, not the catalog' description: > The provider serves its own APIs.json index from its own domain rather than being catalogued from the outside. `apis_yml_present` above rewards the index existing; this rewards the provider OWNING it — the difference between describing yourself and being described. # 0.18.0 — WHOSE CONTRACT IS IT. The generalisation of the 0.13 agentic-commerce rule # from one `.well-known` document to the whole registered API surface. # # THE MEASURED FAILURE. 25 universities were credited for ONE Figshare contract, saved # under their own slugs and titled " articles API". The eight highest-scoring # universities in the catalog were all scoring that same document, and all eight returned # an identical agent readiness of 38.9 because it literally was the same document. The # shape is everywhere once the question is asked: 193 Shopify merchants, 11 Elsevier Pure # deployments, 23 Instructure tenancies. A rating that cannot tell "this organisation # built an API" from "this organisation bought a product that has one" is not rating the # organisation. # # WHAT SETTLES IT. `x-operator` on each apis[] entry, established from evidence the # pipeline already gathers: IP ownership, DNS CNAME chains, and the contract's own # info.title / info.contact. institution and federation surfaces are the organisation's # own; tenant and vendor surfaces are real, are KEPT, and belong to someone else. # # GRADED DOWN, NOT ZEROED — the 0.13 posture. A university running Figshare genuinely # gives its community a research repository with an API; it did not engineer the # contract. `tenant` keeps a quarter of the credit for the same reason `platform` does. # # REGISTRY MEMBERSHIPS ARE EXCLUDED from both sides. A DataCite or Crossref account is a # true fact about the organisation but it is not a contract it operates, so counting it # either way would be wrong. # # N/A WHEN UNDECLARED, and this is the load-bearing safety property. A provider whose # apis.yml carries no x-operator scores this :skipped and its composite DOES NOT MOVE. # The axis is currently populated on the 254-institution university cohort (2,569 # entries) and nowhere else, so this ships as a no-op for the rest of the catalog and # sharpens as the field spreads. It must never dock a provider for annotation work WE # have not done — the rule the open_source facet already states. - id: contract_self_operated label: The registered APIs are the provider's own to operate facet: contract_quality points: 6 graded: true credit: self: 1.00 mixed: 0.60 tenant: 0.25 rule: 'apis[] declare x-operator; graded on whether the operated surfaces are the provider''s own' signal: '`self` when every operated surface is institution- or federation-run, `mixed` when the provider runs some of its own alongside vendor tenancies, `tenant` when every registered surface is somebody else''s platform' description: > Settles WHO OPERATES the thing each contract describes before awarding contract credit, instead of counting documents. Skipped entirely for a provider whose apis.yml does not declare the axis, so it cannot depress anyone for catalog work we have not reached. # ------------------------------------------------------------------------- # OpenAPI specifications # ------------------------------------------------------------------------- openapi: label: OpenAPI spec: https://www.openapis.org/ description: > The HTTP contract itself. These checks parse every OpenAPI document the provider publishes, so they measure what the spec actually contains rather than whether one exists. A provider with several specs earns credit proportional to how many pass. checks: - id: contract_present label: Publishes a machine-readable contract facet: contract_quality points: 20 provenance: openapi rule: 'at least one OpenAPI, AsyncAPI, GraphQL SDL or FHIR CapabilityStatement' description: > At least one machine-readable contract exists, in ANY format the ecosystem actually uses. The largest single award in the rubric, because nearly every downstream capability — SDK generation, mocking, linting, agent tool-calling — is unlocked by having a contract at all. CONTRACT-TYPE-AGNOSTIC IN 0.6, and renamed from `openapi_present` to say so. Through 0.5.1 this check read OpenAPI and AsyncAPI only, which meant entire FHIR-native, GraphQL-native and EDI-native markets were recorded as having no contract for a format the rubric simply declined to read. Epic served a 59-resource FHIR R4 CapabilityStatement — plus STU3, DSTU2 and a smart-configuration — and read `spec_presence: false`, `contract_quality: 22.6`. That was a measurement artifact, not a judgment about Epic. PROVENANCE-GRADED IN 0.6. An API-Evangelist-modeled spec credits at 0.25. A provider-served contract you can download should outrank one written on the provider's behalf, and until 0.6 they were indistinguishable. - id: openapi_3_2 label: OpenAPI 3.2 facet: contract_quality points: 5 rule: 'declared version >= 3.2, read from the provider''s published document' description: > The provider publishes OpenAPI 3.2. Scored from the version they published, not from the version our refinement produced: 275 of the 339 providers holding a 3.2 document in the catalog hold it only because refine-openapis upgraded theirs, and exactly three publish 3.2 themselves. Worth the same as 3.1 rather than more — shipping the newest version is good practice, not a different kind of contract. - id: openapi_3_1 label: OpenAPI 3.1 facet: contract_quality points: 5 rule: 'openapi version is 3.1.x' description: > Published against 3.1, which aligns with modern JSON Schema and supports webhooks natively. Scored above 3.0 rather than instead of it. - id: openapi_3_0 label: OpenAPI 3.0 facet: contract_quality points: 3 rule: 'openapi version is 3.0.x' description: > Published against 3.0. Still widely tooled and a long way ahead of Swagger 2.0, but no longer where the specification is moving. - id: info_complete label: Complete info block facet: contract_quality points: 4 rule: 'info has title, description (>= 50 chars), version, contact' description: > Title, a description of real length, a version, and a contact. The metadata a consumer needs to identify and reach the API's owner. - id: servers_defined label: Real servers declared facet: contract_quality points: 3 rule: 'servers[] non-empty and not localhost' description: > The spec points at a callable host. A localhost server fails — a contract you cannot call is documentation, not an interface. - id: servers_resolvable label: Servers resolve to a real host facet: contract_quality points: 5 graded: true rule: 'share of specs whose servers[].url carries a registrable domain that is not a placeholder host, a bare template variable, or a host an actual DNS resolve found to have no address' description: > NEW IN 0.6. A specification can be genuinely provider-published, verbatim, and still be uncallable. Every CAMARA server declaration in the entire telecom stack is the template variable `{apiRoot}` and every openIdConnectUrl is a CAMARA placeholder pointing at example.com — across 19 standards and exposure repositories there was exactly one absolute base URL. Insurance produced the same defect from the other direction: Majesco declares api.majesco.example.com and ACORD api.insurer-internal.example.com. The rubric scored all of it as full contract quality. 0.15.0 MAKES THE LABEL TRUE. Until then this check never resolved anything: a denylist of obvious placeholders, then "has a dot and an alphabetic TLD" — so any host an author invented that missed the denylist counted as callable. `oracle.api.com` was Oracle Hospitality's ENTIRE callable score (1 of 59) and returns no DNS answer. Resolving all 14,061 literal hosts the classifier graded `real` found 829 (5.9%) with no address and 12 cluster-internal, across 392 providers. No lexical rule could have found most of them: a host that was live when harvested and is dead today is indistinguishable from a working one by pattern matching, and that population only grows. Templated hosts are never resolved — `https://{region}.api.acme.com` is callable by a consumer who fills the variable in, and resolving the residue would ask a different question. Only an authoritative negative answer removes credit; timeouts stay unknown and keep it. Graded on the SHARE of a provider's specs that carry a resolvable host, so a provider with one placeholder spec among twenty is not treated like one whose entire surface is uncallable. Catalog-wide at 0.6: 10,950 of 87,612 specs are uncallable as published, and 834 providers hold no spec with a resolvable host at all. The distinction that took care to get right: a TEMPLATED host that still carries a real domain — `https://{region}.api.acme.com`, or Yardi's `https://{server}.yardi.com/{clientUrl}/webservices` — passes. A consumer with the variable filled in reaches a host that exists. Only a host that is nothing but substitution variables, or a known placeholder domain, fails. A naive "contains a brace" test would have failed a large share of perfectly callable multi-region specs, and a naive full-text grep for example.com over the catalog returned 4,320 false positives, because real specs mention example.com in their EXAMPLES. This check parses the `servers` block specifically. - id: operations_summary_coverage label: Operations have summaries facet: contract_quality points: 6 rule: '>= 80% of operations have summary' description: > At least 80% of operations carry a summary. Summaries are what render in reference docs and what an agent reads to pick the right operation. - id: operations_description_coverage label: Operations have descriptions facet: contract_quality points: 6 rule: '>= 80% of operations have description' description: > At least 80% of operations carry a description. The difference between knowing an operation's name and knowing what it does. - id: operations_tagged label: Operations are tagged facet: contract_quality points: 4 rule: '>= 80% of operations have tags' description: > At least 80% of operations are tagged, which is what groups a reference into navigable sections instead of one flat list of endpoints. - id: operations_operation_ids label: Unique operationIds facet: contract_quality points: 4 rule: '100% of operations have unique operationId' description: > Every operation has a unique operationId. Required for clean SDK method names and stable agent tool names; duplicates silently break both. - id: response_coverage label: Success responses defined facet: contract_quality points: 5 rule: 'every operation defines >= one 2xx response' description: > Every operation documents at least one success response, so a consumer knows the shape of what they get back. - id: error_responses_documented label: Error responses documented facet: contract_quality points: 4 rule: '>= 50% of operations define a 4xx response schema' description: > At least half of operations document a 4xx response schema. The most commonly skipped part of a contract, and the part integrators need most when things go wrong. - id: examples_present label: Examples present facet: contract_quality points: 4 graded: true rule: 'share of operations carrying a request or response example' description: > GRADED IN 0.6, previously a bit. As a boolean this check fired on a single token example anywhere in the document, which meant it ran near-universally across payments and healthcare and carried almost no information. It now grades on the SHARE of operations that actually carry a request or response example, so a provider who documents every operation outscores one who documented a single one. Examples are the cheapest way an agent learns a payload shape before it ever makes a call, and "the spec contains the string example:" was never evidence of that. - id: components_reuse label: Reusable components facet: contract_quality points: 3 rule: 'components.schemas count >= 5 and used via $ref' description: > Five or more component schemas, actually referenced via $ref. Evidence the spec is modelled rather than copy-pasted per endpoint. - id: security_schemes_defined label: Security schemes defined facet: contract_quality points: 4 rule: 'components.securitySchemes non-empty' description: > The spec declares how authentication works, so a consumer can authenticate from the contract without hunting through prose docs. - id: security_applied label: Security applied to operations facet: contract_quality points: 3 rule: 'security applied globally or per-operation' description: > Declared schemes are actually bound to operations, globally or individually. A scheme defined but never applied tells a consumer nothing about what a given call requires. - id: oauth_flows_current label: Declares no deprecated OAuth grant facet: contract_quality points: 4 rule: 'no securityScheme declares the implicit or resource-owner-password OAuth grant' description: > NEW IN 0.7. The implicit grant returns an access token in the browser redirect fragment; the password grant has the client handle the user's credentials directly. Both are recommended against by the OAuth 2.0 Security BCP (RFC 9700) and removed outright in OAuth 2.1. Measured across 14,195 published contracts, 775 still declare implicit and 72 declare password - 28.9% of every OAuth-using contract. Vacuously satisfied by a contract declaring no OAuth: this scores the PRESENCE of a deprecated flow, not the absence of OAuth. - id: credentials_not_in_query label: Keeps credentials out of the query string facet: contract_quality points: 3 rule: 'no apiKey securityScheme declares in: query' description: > NEW IN 0.7. An API key in the query string lands in server logs, proxy logs, browser history and referrer headers. 815 of 14,195 published contracts place the credential there. Vacuously satisfied where no apiKey scheme is declared. - id: oauth_scopes_enumerated label: Enumerates OAuth scopes facet: contract_quality points: 4 rule: 'every declared oauth2 flow enumerates at least one scope' description: > NEW IN 0.7. Scope is how OAuth expresses least privilege - the difference between a token that can read a calendar and one that can delete an account. Only 15.3% of published contracts enumerate any scope, so roughly four in five OAuth-declaring contracts describe how to obtain a credential and never what it permits. This is the mechanism behind the missing least-privilege models found in every market report. Distinct from reg_oauth_scopes, which applies only where a regulatory regime does; this one applies to every provider. Vacuously satisfied without OAuth. - id: webhooks_or_callbacks label: Webhooks or callbacks facet: contract_quality points: 2 rule: 'webhooks or callbacks defined (3.1) or callbacks (3.0)' description: > The spec describes what the API sends back out, not only what it receives — the event surface most providers document only in prose, if at all. - id: inbound_contract_published label: Inbound event contract published facet: contract_quality points: 2 rule: 'at least one OpenAPI document classified `inbound` in the provenance index' description: > The provider publishes a standalone machine-readable contract for the events it SENDS, not only for the calls it receives. LINE's is the clean example: a document defining the whole CallbackRequest schema tree, whose servers[] reads https://example.com because the consumer is the server. Until roadmap#175 that document was scored as an uncallable API and cost LINE a ninth of its callable share — a penalty for doing the thing this check now credits, while a provider who published nothing paid nothing. Distinct from webhooks_or_callbacks, which asks whether an OUTBOUND spec declares a webhooks/callbacks block. This asks whether the inbound surface has a contract of its own. LINE's has no webhooks: key at all — it is a paths-based envelope, which is why the older check never saw it. A provider doing both has done two things. N/A for a provider with no event surface. Asking a company with no webhooks whether it documented them would score 19,000 records down on a question that does not apply. # ------------------------------------------------------------------------- # AsyncAPI specifications # ------------------------------------------------------------------------- asyncapi: label: AsyncAPI spec: https://www.asyncapi.com/ description: > The event-driven contract. Only 213 AsyncAPI documents exist across the entire catalog, so these checks are N/A for most providers — a provider with no event surface is not penalized for the absence, and these points are excluded from their denominator entirely. checks: - id: asyncapi_present label: Publishes an AsyncAPI spec facet: contract_quality points: 12 rule: 'at least one api has spec_type == "AsyncAPI"' description: > At least one AsyncAPI document exists, describing the messaging or streaming surface with the same rigor the OpenAPI applies to the request/response one. - id: asyncapi_3_x label: AsyncAPI 3.x facet: contract_quality points: 4 rule: 'asyncapi version is 3.x' description: > Published against 3.x, which separates channels from operations and is where the specification's tooling is consolidating. - id: channels_defined label: Channels defined facet: contract_quality points: 4 rule: 'channels[] non-empty' description: > The spec declares the channels messages flow over — the event equivalent of declaring paths. - id: messages_with_schema label: Messages carry payload schemas facet: contract_quality points: 5 rule: '>= 80% of messages reference a payload schema' description: > At least 80% of messages reference a payload schema, so a subscriber knows the shape of what arrives rather than discovering it at runtime. - id: server_bindings label: Protocol bindings on servers facet: contract_quality points: 3 rule: 'servers define protocol bindings' description: > Servers declare their protocol bindings — Kafka, AMQP, WebSocket, MQTT — which is what makes the contract actually connectable. - id: security_schemes label: Server security schemes facet: contract_quality points: 3 rule: 'securitySchemes defined for at least one server' description: > At least one server declares how to authenticate against it. # ------------------------------------------------------------------------- # GraphQL — a first-class contract type as of 0.6 # # 1,089 providers publish a GraphQL SDL and the rubric could not read a line of # it, so a GraphQL-native company registered as having no contract at all. Like # AsyncAPI, these checks are N/A for providers with no GraphQL surface — nobody # is penalized for not being a GraphQL shop. # ------------------------------------------------------------------------- graphql: label: GraphQL spec: https://spec.graphql.org/ description: > The GraphQL schema definition. A published SDL is a machine-readable contract in exactly the sense the contract facet means: introspectable, codegen-ready, and sufficient for an agent to construct a valid query without reading prose. checks: - id: graphql_sdl_present label: Publishes a GraphQL schema facet: contract_quality points: 10 rule: 'a .graphql / .gql SDL is published' description: > A schema definition file is published rather than only an interactive playground. An endpoint with introspection disabled and no published SDL is, to a consumer building against it, an undocumented API. - id: graphql_type_depth label: Schema defines a real type system facet: contract_quality points: 5 rule: 'SDL declares >= 20 type definitions' description: > Twenty or more type definitions — a modelled domain rather than a handful of wrapper types around a REST passthrough. - id: graphql_descriptions label: Schema is documented facet: contract_quality points: 4 rule: '>= 50% of type definitions carry a description string' description: > Half or more of the declared types carry description strings. In GraphQL the docstring IS the reference documentation — it is what renders in every explorer and what an agent reads to pick a field. # ------------------------------------------------------------------------- # FHIR — a first-class contract type as of 0.6 # # A FHIR CapabilityStatement is the health sector's OpenAPI: a machine-readable # declaration of every resource and interaction a server supports. Scoring US # healthcare made the omission concrete — Epic read spec_presence: false and # contract_quality 22.6 while serving a 59-resource R4 CapabilityStatement, and # 1upHealth read the same 22.6 on a 144-resource statement. # # HONEST LIMITATION AT 0.6: only 22 CapabilityStatements are held across 11 # providers, so this check corrects the rubric but cannot yet correct the # sector — harvesting statements from the FHIR-native cohort is collection work # that has to follow. The check ships now so the collection has somewhere to land. # ------------------------------------------------------------------------- fhir: label: FHIR spec: https://hl7.org/fhir/capabilitystatement.html description: > The FHIR conformance surface — a CapabilityStatement declaring the resources, interactions, search parameters and profiles a server actually supports. checks: - id: fhir_capability_statement label: Publishes a FHIR CapabilityStatement facet: contract_quality points: 12 rule: 'a CapabilityStatement / Conformance resource is published' description: > The server publishes its conformance statement. This is the FHIR equivalent of shipping an OpenAPI, and it is served at a well-known path by every conformant server, which makes its absence a deliberate omission rather than an oversight. - id: fhir_resource_coverage label: Broad resource coverage facet: contract_quality points: 6 rule: 'CapabilityStatement declares >= 20 resources' description: > Twenty or more resources declared — the difference between a server that supports Patient and Observation and one that supports a working clinical record. # ------------------------------------------------------------------------- # JSON Schema artifacts # ------------------------------------------------------------------------- json_schema: label: JSON Schema spec: https://json-schema.org/ description: > Schemas published as standalone, addressable artifacts rather than only inlined in a spec — reusable across specs, validators, and codegen. checks: - id: json_schema_present label: Publishes JSON Schema facet: contract_quality points: 6 rule: 'at least one api property has type == "JSONSchema"' description: > At least one JSON Schema is published as its own artifact, so the data model can be validated against and reused independently of any single API. - id: json_schema_per_resource label: Schema per resource facet: contract_quality points: 4 rule: 'schemas extracted per primary resource (>= 2)' description: > Two or more schemas, broken out per primary resource rather than one catch-all document — evidence the data model is decomposed. # ------------------------------------------------------------------------- # JSON-LD / semantic context # ------------------------------------------------------------------------- json_ld: label: JSON-LD spec: https://json-ld.org/ description: > Semantic context — what the API's terms actually mean, linked to shared vocabularies. The thinnest-populated artifact in the catalog, and the one that most separates an API a machine can call from one a machine can reason about. checks: - id: json_ld_present label: Publishes a JSON-LD context facet: contract_quality points: 5 rule: 'at least one jsonld context defined' description: > At least one JSON-LD context is defined, binding the API's terms to shared semantics instead of leaving field names to be guessed from spelling. - id: json_ld_class_depth label: Context defines classes facet: contract_quality points: 3 rule: 'any jsonld context has class_count >= 5' description: > Five or more classes in a context — a modelled domain rather than a token gesture at semantics. - id: json_ld_property_depth label: Context defines properties facet: contract_quality points: 3 rule: 'any jsonld context has property_count >= 10' description: > Ten or more properties, giving the classes enough detail to be useful to a consumer mapping the API onto their own model. # ------------------------------------------------------------------------- # Spectral rules / governance # ------------------------------------------------------------------------- spectral: label: Spectral Rules spec: https://stoplight.io/open-source/spectral description: > Published governance — the rules a provider holds their own API to, and the outcome of running them. This facet rewards publishing a ruleset AND passing it; a large ruleset that throws errors on the provider's own spec scores below a modest one that passes clean. checks: - id: lifecycle_documented facet: contract_quality label: Documented resource lifecycle points: 5 graded: true rule: 'share of creatable resources that also document read, update and delete, capped at 0.33' description: > Of the resources a provider lets you CREATE, the share that also document how to read the thing back, change it, and remove it. Grouped by RESOURCE, not by path -- REST splits one resource across `POST /things` and `GET|PUT|DELETE /things/{id}`, and a path-level view would score that as two incomplete resources. WHY IT IS A CONTRACT SIGNAL. An agent that creates something and cannot read it back has no way to confirm the write landed, no way to correct it, and no way to clean up after itself. That is a property of the contract, visible in the contract, and orthogonal to everything else this facet measures -- a provider can document one endpoint impeccably, score full marks on tagging, schemas and examples, and tell an agent nothing about what happens next. REWARD-ONLY AND CAPPED. Absence of a documented DELETE is not absence of DELETE: a resource can be genuinely append-only (an event, a log line, an audit record), the capability can exist and be undocumented, or the resource can be managed elsewhere. Only the middle case is a provider deficiency and none of the three is distinguishable by reading the spec, so incompleteness is never penalised. The 0.33 cap means a provider clears this on a healthy third rather than needing 100%, and it stops the check rewarding CRUD-for-its-own-sake -- an API that deliberately exposes no DELETE must not score below a worse one that ships a dangerous one. MEASURED 2026-08-18 over 5,884 providers with a creatable resource: 96,704 creatable resources, 15.5% fully round-trippable, mean provider share 15.6%, MEDIAN 0.0%, and 59.1% documenting not one. This check reads near-zero across the catalog on day one, which IS the finding, and the band re-cut is part of the change rather than a follow-up. TWO CONVENTION BUGS WERE FOUND AND FIXED BEFORE THIS SHIPPED, both by spot-checking providers whose answer could be reasoned about independently rather than by trusting the aggregate. (1) Requiring PUT or PATCH for the update leg scored STRIPE 0.000 on 189 creatable resources -- Stripe uses POST on the instance path and does not use PUT or PATCH anywhere. (2) Not stripping file extensions scored SHOPIFY 0.000 on 166 -- `/customers.json` and `/customers/{id}.json` folded to two different resources. Corrected: Stripe 0.583, Shopify 1.000. KNOWN CAVEAT, recorded rather than hidden: an RPC-style API inflates the denominator. Slack publishes 636 paths and NOT ONE parameter segment (`/calls.add`, `/calls.end`) -- it is not resource-oriented, so 121 of its POST endpoints are counted as creatable resources that can never round-trip. Because this check is reward-only, no such provider is penalised; the effect is that the catalog-wide percentages above UNDERSTATE round-trip coverage among genuinely RESTful APIs. Quote them with that caveat. - id: domain_standard_conformance label: Implements a domain standard facet: contract_quality points: 4 rule: 'contract carries a recognised domain-standard signature' description: > The contract itself declares conformance to an interoperability standard for its market -- a SCIM schema URN, an OData metadata surface, an OpenRTB bid endpoint, a Sparkplug topic namespace, an ActivityPub actor. A customer who already speaks the standard can integrate with no bespoke connector; one who does not needs a bilateral one, and until 0.12 both scored identically. REWARD-ONLY, and that is deliberate. Absence earns nothing and costs nothing, because most markets in this catalog have no domain standard to implement and penalising their providers would measure the market rather than the provider. EVIDENCE, NOT CLAIM -- inherited from reg_mandate_verified, whose own finding was that a claimed-but-unverifiable mandate scored BELOW organizations under no obligation at all. Naming SCIM in marketing copy earns nothing here; declaring `urn:ietf:params:scim:schemas:...` in the contract earns. Measured 2026-08-17: 164 of 7,579 providers with a contract (2.2%) -- OData 89, SCIM 60, ActivityPub 10, OpenRTB 4, Sparkplug 2. Web of Things, oneM2M and HR Open have ZERO detectable adoption. That thinness is why this is a check and not the conditional facet originally proposed. - id: rules_present label: Publishes a ruleset facet: contract_governance points: 10 rule: 'rules[0].rule_count >= 1' description: > A Spectral ruleset exists. The provider has written down what "good" means for their API surface instead of leaving it to reviewer taste. - id: rules_substantial label: Substantial ruleset facet: contract_governance points: 5 rule: 'rules[0].effective_rule_count >= 20' description: > Twenty or more rules ENFORCED — authored plus whatever an `extends:` brings in. 0.12 (roadmap#62): this counted authored rules only, so a ruleset extending spectral:oas and adding a focused handful was measured on the handful. As the provider who reported it put it, the alternative was "inlining 41 rules I didn't write in order to be measured on the 9 I did". Extending a maintained base is the better engineering choice and the threshold was punishing it. - id: balanced_severities label: Balanced severities facet: contract_governance points: 3 rule: 'warn and info both > 0' description: > The ruleset uses warn and info, not only error. A ruleset where everything is an error cannot express guidance — only refusal. - id: vocabulary_published label: Publishes a vocabulary facet: contract_governance points: 5 rule: 'common[].type includes "Vocabulary"' description: > A controlled vocabulary is published, so the provider's naming is a documented decision rather than an accident of whoever wrote each endpoint. # --- 0.6: broaden the facet beyond "did you ship a Spectral file" # governance (0.12) was effectively a single check and scored ~0 across all six # sectors measured — 63 of 79 US insurance organizations at zero, 34 of 35 UK, 19 # of 20 Canadian, 66 of 83 in telecom. That is honest (almost nobody publishes a # public ruleset) but it wastes the facet. These credit the OTHER ways a provider # demonstrates it has internalized a standard. - id: conformance_declared label: Declared conformance profile facet: contract_governance points: 6 provenance: conformance rule: 'a conformance/ artifact declares conformance to named standards' description: > The provider declares which standards it conforms to — FHIR, FAPI, PCI, ISO 20022, CAMARA — as a machine-readable artifact resolving against the standards catalog, rather than as a logo on a marketing page. PROVENANCE-GRADED, and the grading is the whole point. Half the conformance artifacts in the catalog (1,881 of 3,784) are API-Evangelist-derived readings of a provider's specs, not claims the provider made. Only a first-party declaration earns full credit here. THE BOUNDARY THIS CHECK HOLDS: adopting someone else's standard is not governance. Telecom is full of organizations that joined CAMARA, TM Forum or GSMA Open Gateway and govern nothing; governance is what you do to yourself. This credits evidence of INTERNALIZATION — a declared profile, an overlay, a published lint posture — never bare membership in a programme. - id: overlay_published label: Publishes an OpenAPI Overlay facet: contract_governance points: 4 rule: 'apis.yml carries an Overlay pointer to an http(s) URL the provider hosts; a local overlays/ file (generated by our enrichment) does not count' description: > An OpenAPI Overlay — the provider expressing a repeatable, versioned transformation of its own contract rather than hand-editing it. Evidence of a spec pipeline, which is what governance looks like in practice. # ------------------------------------------------------------------------- # Operational transparency — common links + extracted data # ------------------------------------------------------------------------- operational: label: Operational Transparency description: > Does the provider expose how the API behaves in production — what it limits, when it breaks, what changed, and what is going away? These are the artifacts a team needs to depend on an API, as opposed to merely call it. checks: - id: change_log_present label: Change log facet: operational_transparency points: 6 rule: 'common[].type includes "ChangeLog" (alias-aware)' description: > A published change log. The single most useful operational artifact: it lets a consumer see what moved without diffing the spec themselves. - id: status_page_present label: Status page facet: operational_transparency points: 6 rule: 'common[].type includes "StatusPage"' description: > A status page exists, so an integrator debugging a failure can tell "the API is down" from "my code is broken" without filing a ticket. - id: rate_limits_documented label: Rate limits documented facet: operational_transparency points: 8 rule: 'rate_limits[0].limit_count >= 1' description: > Rate limits are published as machine-readable data. The heaviest award in this facet — undocumented limits are the most common cause of an integration that works in development and fails under load. - id: rate_limits_rich label: Rate limits detailed facet: operational_transparency points: 4 rule: 'rate_limits[0].limit_count >= 3' description: > Three or more distinct limits, reflecting how the API actually tiers and throttles rather than a single blanket number. - id: deprecation_policy label: Deprecation policy facet: operational_transparency points: 3 rule: 'common[].type includes "Deprecation" (alias-aware)' description: > A stated deprecation policy — how much notice a consumer gets before something they depend on is removed. - id: security_disclosure label: Security disclosure facet: operational_transparency points: 4 rule: 'common[].type includes "Security" (alias-aware)' description: > A route for reporting vulnerabilities. Its absence tells a security researcher to go public instead. - id: webhooks_advertised label: Webhooks advertised facet: operational_transparency points: 3 rule: 'common[].type includes "Webhooks"' description: > The provider advertises a webhook surface, so consumers can react to events rather than poll for them. - id: github_org_present label: GitHub organization facet: operational_transparency points: 2 rule: 'common[].type includes "GitHubOrganization" or "GitHubRepository" (alias-aware)' description: > A public GitHub organization or repository — where SDKs, specs, and issues live in the open. WIDENED IN 0.13 (roadmap#71): `GitHubRepository` was read by no check while 600 providers declared it, so a provider pointing at their actual code repository scored below one pointing at an org page. A repository is not an organization, but for the question this check asks — is the code findable — it is the same answer, and often the more precise one. - id: roadmap_present label: Public roadmap facet: operational_transparency points: 2 rule: 'common[].type includes "RoadMap" or "Roadmap"' description: > A public roadmap, letting consumers plan against where the API is going rather than only where it is. # ------------------------------------------------------------------------- # Developer ergonomics — how easy is it to start using the API? # ------------------------------------------------------------------------- ergonomics: label: Developer Ergonomics description: > How far is a newcomer from their first successful call? These checks track the on-ramp — portal, quickstart, auth docs, SDKs, sandbox — plus the newer agent-facing entry points (MCP servers and Agent Skills) that increasingly serve the same purpose for a non-human consumer. checks: - id: examples_published facet: contract_quality label: Published example corpus points: 4 rule: 'common[].type includes "Examples" (alias-aware: CodeExamples, Samples, CodeSamples, Demos)' description: > A published corpus of worked examples, separate from the contract. DISTINCT FROM `examples_present`, which reads examples INSIDE the OpenAPI document: a provider can reasonably have either or both, and 595 providers declare this pointer while it was read by no check at all. Found by Ahmet Soormally at WunderGraph, who wired nine pointers to his own record unprompted and got nothing for two of them — with nothing in the build that would ever have told him, or us. The catalog already treats examples as first-class: there is an `examples/` artifact class and an api-search/examples site. The rubric was the only part that could not see them. - id: portal_present label: Developer portal facet: developer_ergonomics points: 4 rule: 'common[].type includes "DeveloperPortal" (alias-aware)' description: > A dedicated developer portal — one front door, rather than API information scattered through a marketing site. - id: documentation_present label: Documentation facet: developer_ergonomics points: 4 rule: 'common[].type includes "Documentation"' description: > Narrative documentation explaining how the API works and how to use it. - id: api_reference_present label: API reference facet: developer_ergonomics points: 3 rule: 'common[].type includes "APIReference" (alias-aware)' description: > A complete endpoint-level reference — distinct from narrative docs, and what a developer returns to after their first call. - id: getting_started_present label: Getting started guide facet: developer_ergonomics points: 5 rule: 'common[].type includes "GettingStarted" or "Quickstart"' description: > An explicit quickstart. The artifact most correlated with a developer reaching a first successful call, which is why it outscores the reference itself. - id: authentication_documented label: Authentication documented facet: developer_ergonomics points: 5 rule: 'common[].type includes "Authentication"' description: > Authentication is documented as its own topic. Auth is where most integrations stall, and burying it inside a general guide is where most developers give up. - id: sdk_count_1 label: At least one SDK facet: developer_ergonomics points: 3 rule: 'count(common[].type == "SDK" alias-aware) >= 1' description: > At least one client library, so a consumer is not writing HTTP plumbing before writing anything of their own. - id: sdk_count_3 label: Three or more SDKs facet: developer_ergonomics points: 4 rule: 'count(common[].type == "SDK" alias-aware) >= 3' description: > Three or more languages covered — evidence of investment in a real developer audience rather than one favored stack. Awarded on top of the first SDK. - id: cli_present label: Command-line interface facet: developer_ergonomics points: 3 rule: 'common[].type includes "CLI"' description: > A CLI, which is how the API gets used in scripts, CI, and exploration. - id: console_or_sandbox label: Console or sandbox facet: developer_ergonomics points: 3 rule: 'common[].type includes "Console" or "Sandbox" or "Playground"' description: > Somewhere to try the API without wiring up credentials and a project first. - id: postman_present label: Postman collection facet: developer_ergonomics points: 2 provenance: collections rule: 'common[].type includes "Postman" (alias-aware), graded by who authored it' description: > A runnable collection — the fastest path from reading about the API to calling it. PROVENANCE-GRADED IN 0.18.3: 610 of the 729 providers registering a Postman pointer at a file in their own repo point at one API Evangelist GENERATED from their OpenAPI — our own provenance manifest calls it `derived`. The check's description is a claim about what the provider published, and those 610 were satisfying it with our work. Same treatment agent_skill_present has had since 0.6, for the same reason. Authorship is read from the per-repo provenance manifest, not from the file: a Postman collection is JSON an importer validates, so a marker cannot go inside it. A pointer at a REMOTE url the provider hosts is unaffected — 1,622 of the 2,351 are exactly that, and they are the providers this check is for. - id: agent_skill_present label: Agent Skill facet: developer_ergonomics points: 3 provenance: skills rule: 'common[].type includes "AgentSkill", graded by who authored it' description: > A published Agent Skill — packaged instructions for an agent to use the API correctly, rather than leaving it to infer usage from the spec. PROVENANCE-GRADED IN 0.6: 2,018 of 2,274 skill sets in the catalog were generated by API Evangelist from the provider's own specs. Provider-published agent skills exist, but they are rare — across the whole telecom sector, three. - id: support_channel label: Support channel facet: developer_ergonomics points: 2 rule: 'common[].type includes "Support" or "HelpCenter" or "Community"' description: > A route to a human or a community when the documentation runs out. - id: blog_present label: Blog facet: developer_ergonomics points: 1 rule: 'common[].type includes "Blog"' description: > A blog. The lightest signal in the rubric, but a live one — it shows the API is still being talked about by the people who build it. # ------------------------------------------------------------------------- # Commercial clarity — can a buyer evaluate the API without sales contact? # ------------------------------------------------------------------------- commercial: label: Commercial Clarity description: > Can a team evaluate, adopt, and pay for this API without booking a sales call? This facet measures whether the commercial surface is as machine-readable as the technical one — the questions procurement and legal ask, answered in public. checks: - id: plans_present label: Plans published facet: access_clarity points: 8 rule: 'plans[0].plan_count >= 1' description: > Access plans exist as structured, machine-readable data rather than a pricing page a human has to interpret. The heaviest award in this facet. - id: plans_multiple label: Multiple plans facet: access_clarity points: 4 rule: 'plans[0].plan_count >= 3' description: > Three or more plans, describing a real tiering model — typically a free or trial tier through to production volume. - id: pricing_link label: Pricing published facet: access_clarity points: 4 rule: 'common[].type includes "Pricing"' description: > Pricing is public. "Contact us" is an answer, but it is not this one. - id: sign_up_present label: Self-service sign-up facet: access_clarity points: 5 rule: 'common[].type includes "SignUp" or "Login"' description: > A developer can get credentials themselves. Self-service sign-up is the line between an API you can try this afternoon and one you can try next quarter. - id: terms_of_service label: Terms of service facet: access_clarity points: 4 rule: 'common[].type includes "TermsOfService" (alias-aware)' description: > Published terms — what a consumer is actually agreeing to when they call the API. - id: privacy_policy label: Privacy policy facet: access_clarity points: 4 rule: 'common[].type includes "PrivacyPolicy" (alias-aware)' description: > A published privacy policy covering what happens to data passing through the API. - id: finops_mapped label: FinOps mapping facet: access_clarity points: 3 # 0.24.0 (roadmap#942). Through 0.23.0 the rule was `len(finops) >= 1`, which awarded # ~6,500 providers for a file: 5,934 of the 6,803 finops artifacts claim FOCUS alignment # and 104 state what the provider bills by — the rest restate the FinOps framework with # the provider's name pasted in (the 2026-05-04 sweep). A mapping that names no unit # maps nothing. Expect ~100 awards at the swap, climbing as the economics harvest runs. rule: 'finops[].primary_unit present AND finops[].sources >= 1 AND NOT finops[].template' description: > Cost is mapped to usage in a machine-readable way — the artifact states the unit the provider bills by and cites the page it was read from — so consumption can be modelled and attributed rather than discovered on an invoice. - id: compliance_published label: Compliance published facet: access_clarity points: 3 rule: 'common[].type includes "Compliance"' description: > Certifications and compliance posture are stated in public — SOC 2, ISO, HIPAA, GDPR — where a reviewer can find them without asking. - id: trust_center label: Trust center facet: access_clarity points: 3 rule: 'common[].type includes "TrustCenter" or "Trust"' description: > A trust center consolidating security, compliance, and privacy posture into one place built for the person evaluating whether to depend on you. # ------------------------------------------------------------------------- # regulatory — CONDITIONAL. These checks award to the `regulatory` facet, # which only enters the composite for providers matched by industry_regulatory # (see above). The checks are regime-agnostic in 0.5 — they measure the common # posture every regulated regime expects (consent-scoped auth, published # security + disclosure, legal basis, standards conformance). Regime-SPECIFIC # checks (e.g. FAPI for open banking, a FHIR capability statement for health) # are the intended next iteration; add them here with a `regime:` qualifier. # ------------------------------------------------------------------------- regulatory: label: Regulatory Posture description: > The consent, security, legal, and standards-conformance posture a regulated-industry API is expected to publish. Scored only where a regime applies; sourced from signals already in the catalog. checks: - id: reg_oauth_scopes label: Consent-scoped authorization facet: regulatory points: 10 rule: 'common[].type includes "OAuthScopes" OR a scopes artifact is present' description: > Published OAuth/OIDC scopes — the machine-readable expression of least-privilege, consented access every data-sharing regime is built on. The single strongest regulatory signal. - id: reg_authentication_documented label: Authentication model documented facet: regulatory points: 6 rule: 'common[].type includes "Authentication" or "OpenIDConnect"' description: > A documented authentication/authorization model (OIDC, mTLS, PAR). A regulated API that will not say how it authenticates cannot be trusted to hold the line the regime draws. - id: reg_security_disclosure label: Security posture published facet: regulatory points: 6 rule: 'common[].type includes "Security" or "DomainSecurity"' description: > A published security policy or domain-security posture. Regulated data demands a stated, verifiable security stance, not an assumed one. - id: reg_vulnerability_disclosure label: Vulnerability disclosure program facet: regulatory points: 6 rule: 'common[].type includes "VulnerabilityDisclosure"' description: > A VDP / responsible-disclosure channel. For a regulated provider this is table stakes, and its absence is a conspicuous gap. - id: reg_terms_of_service label: Terms of service (legal basis) facet: regulatory points: 4 rule: 'common[].type includes "TermsOfService"' description: > Machine-findable terms establishing the legal basis for access — the contract a regulator expects to exist and be discoverable. - id: reg_privacy_policy label: Privacy policy (data handling) facet: regulatory points: 4 rule: 'common[].type includes "PrivacyPolicy"' description: > A published privacy policy stating how personal/consumer data is handled — the disclosure most regulated regimes require. - id: reg_compliance_published label: Compliance / certification disclosure facet: regulatory points: 5 rule: 'common[].type includes "Compliance" or "TrustCenter" or "Trust"' description: > Published compliance, certification, or trust-center content (SOC 2, ISO 27001, PCI, regime attestations) — evidence the provider holds itself to an external standard, not just its own word. - id: reg_standards_conformance label: Data-standard conformance facet: regulatory points: 5 rule: 'implements a recognized data standard — common[].type includes "Standard"/"Conformance", or a Vocabulary/JSON-LD context is published' description: > Evidence the API conforms to the industry's data standard (a named standard, conformance artifact, or a published vocabulary/JSON-LD context). In a regulated space, speaking the mandated shape is the difference between interoperable and merely present. # --------------------------------------------------------------------- # REGIME-SPECIFIC CHECKS (new in 0.6) # # Everything above is regime-AGNOSTIC — the common posture every regulated # regime expects. These award ONLY to providers matched to the named # regime, and are N/A (excluded from the denominator) for everyone else, # exactly as an absent artifact type is. A payments company is never # measured against FHIR, and a hospital is never measured against PCI. # # Each resolves against the provider's conformance/ artifact, matched to # the `standards:` list declared on its regime in industry_regulatory # above. That turns the Standards catalog into a scoring input and closes # the loop between the papers, the standards and the score. # --------------------------------------------------------------------- - id: reg_named_standard_conformance label: Conforms to the standard named for its regime facet: regulatory points: 8 regime: any rule: 'conformance/ declares conformance to a standard listed under the matched regime`s `standards:` — not merely a generic Standard tag' description: > The provider conforms to the standard RECOGNIZED FOR ITS REGIME, resolved against the standards catalog: OBIE, the DSB Consumer Data Standards, FDX or Berlin Group for open banking; US Core / USCDI for health; ACORD, CIECA or CSIO for insurance; CAMARA or TM Forum for telecom; Green Button / ESPI or cds-energy for energy. This supersedes the generic check above in strength for a reason the banking quartet made plain: a `Standard` tag credits an intention, while naming the instrument credits a fact. It is also the check the insurance quartet needed to state its emptiest finding honestly — ACORD is live inside a machine-readable contract at exactly one company worldwide. - id: reg_fapi_profile label: FAPI / hardened authorization profile facet: regulatory points: 6 regime: banking_open_finance rule: 'conformance declares FAPI or FAPI 2.0, or auth artifacts document PAR, private_key_jwt or mTLS-bound tokens' description: > The security profile CDR, UK Open Banking and PSD2 actually mandate, beyond generic OAuth: the FAPI profile, pushed authorization requests, private_key_jwt client authentication, mTLS-bound tokens. Generic OAuth is table stakes; this is the stack the regime specifies. - id: reg_consent_model label: Published consent model facet: regulatory points: 7 regime: [banking_open_finance, health, insurance, telecommunications, energy_utilities] rule: 'a machine-readable consent surface — consent scopes, a FHIR Consent resource, a CDR consent artifact, or a documented consent/authorization model' description: > A consent surface a machine can read. This is the structural gap the whole series found and the reason it is weighted where it is: in market after market whose entire premise is consumer consent, machine-readable consent ran in the single digits. A FHIR Consent resource is exposed by essentially nobody; insurance ran at 2.5% in the US and zero among every market's leaders, in the most personally-invasive data business in the economy. Weighted heaviest in insurance and telecom precisely BECAUSE no rule compels it there — where consent is unmandated its presence is a genuine differentiator rather than a compliance artifact. - id: reg_write_surface label: Action / write surface facet: regulatory points: 4 regime: [banking_open_finance, payments] rule: 'the contract exposes payment initiation, VRP, or another mutating regulated operation' description: > The regime is actionable, not read-only. An agent that can move money on an account is a different animal from one that can only read it, and the score should say so: the UK — which mandated payment initiation — scored 87% on idempotency, where read-only Australia scored 0%. - id: reg_smart_configuration label: SMART-on-FHIR configuration served facet: regulatory points: 6 regime: health rule: 'a .well-known/smart-configuration is served, or SMART scopes are published' description: > A served `.well-known/smart-configuration` with published SMART-on-FHIR scopes. The structural finding across all four healthcare markets: the security scopes often exist, but the smart-configuration is served almost nowhere — so the check has to weight a DISCOVERABLE, consent-legible surface rather than the mere presence of scopes somewhere in prose. - id: reg_pci_sca label: PCI scope and strong customer authentication facet: regulatory points: 6 regime: payments rule: 'PCI-DSS attestation or scope disclosure, plus 3-D Secure / SCA support' description: > PCI-DSS attestation or scope disclosure together with strong customer authentication (3-D Secure, PSD2 SCA). The two disclosures every payments regime is built on, and the ones a merchant's own auditor will ask for first. - id: reg_entitlement_terms label: Machine-readable entitlement and redistribution terms facet: regulatory points: 6 regime: securities_market_data rule: 'redistribution / entitlement / data-licensing terms published as machine-readable data' description: > Entitlement and redistribution terms in machine-readable form, plus MiFID II or exchange data-licensing disclosure. In market data the licence IS the product boundary, and a consumer who cannot read it programmatically cannot build against it safely. - id: reg_certification_signal label: Third-party certification facet: regulatory points: 5 regime: [insurance, health, energy_utilities, telecommunications] rule: 'a public, independently-issued certification is held and discoverable' description: > A certification issued and published by somebody other than the provider. Canada runs the only public, tiered insurance API certification programme in the world (CSIO) and it was invisible to the score — its own table lists the country's largest P&C insurer as Not Yet Rated while smaller competitors hold higher tiers, which is exactly the published signal a rubric should read. THE CAUTION THIS CHECK CARRIES, learned from real estate: RESO certification is real, independently tested and industry-mandated, and it is worth 2.0 points of measured difference — because all three certified organizations return 401 on the very contract they are certified against. A certification claim is credited here only alongside `servers_resolvable`; a badge for a document the consumer cannot fetch is not conformance. - id: reg_camara_conformance label: CAMARA / network-API conformance facet: regulatory points: 6 regime: telecommunications rule: 'an x-camara-commonalities version, /camara/ paths, CIBA support, or TM Forum Open API conformance' description: > Conformance to the network-API standards the sector actually built: CAMARA commonalities, the canonical API definitions, CIBA (the backchannel authentication flow CAMARA specifies for network authorization, found in 3 of 19 standards repositories and absent from both specs of the one exposure platform with a callable endpoint), and TM Forum Open API conformance — held widely by carriers who publish no network API at all. - id: reg_sbom label: Software bill of materials facet: regulatory points: 4 rule: 'common[].type includes "SBOM"' description: > An SBOM. The CRA makes it a condition of placing a product on the EU market, and US federal procurement already asks for it. Machine-readable, cheap to publish, and almost absent across the catalog. Asked for by: EU Cyber Resilience Act; EO 14028 procurement. (roadmap#444) - id: reg_support_lifetime label: Declared support lifetime facet: regulatory points: 4 rule: 'common[].type includes "SupportLifetime"' description: > A published support or security-update period. UK PSTI made this a condition of sale alongside a vulnerability-disclosure policy — mandated, cheap, machine-readable, and mostly missing, which is what a scored check should be aimed at. Asked for by: UK PSTI; CRA; Australia Cyber Security Act. (roadmap#444) - id: reg_accessibility_conformance label: Accessibility conformance report facet: regulatory points: 4 rule: 'common[].type includes "AccessibilityConformance"' description: > A conformance report (VPAT/ACR or equivalent). A provider shipping an embedded widget, hosted page or SDK component puts that artifact inside a customer's EAA/AODA compliance boundary; the report is standardised in form and almost never in developer documentation. Asked for by: European Accessibility Act; ADA Title III; AODA; Section 508. (roadmap#444) - id: reg_training_data_summary label: Training-data summary facet: regulatory points: 4 rule: 'common[].type includes "TrainingDataSummary"' description: > A public summary of training data. AB 2013 and the AI Act's GPAI duties both ask for one; it applies only where the provider declares an AI surface. Asked for by: California AB 2013; EU AI Act GPAI. (roadmap#444) - id: reg_ai_transparency label: AI interaction disclosure facet: regulatory points: 4 rule: 'common[].type includes "AITransparency"' description: > A disclosure that the user is interacting with an AI system. Applies only where the provider declares an AI surface. Asked for by: EU AI Act Art. 50; Utah AI Policy Act. (roadmap#444) - id: reg_biometric_retention_policy label: Biometric retention and destruction policy facet: regulatory points: 4 rule: 'common[].type includes "BiometricDataPolicy"' description: > A public, written policy giving the retention schedule and destruction guidelines for biometric identifiers, and how consent is obtained before capture. Applies only where the provider declares a biometric surface (`applies_when_tags`), in whatever regime it sits: the obligation follows the data, not the sector. Asked for by: BIPA 740 ILCS 14/15(a)-(b); Texas CUBI s.503.001(c); RCW 19.375.020; GDPR Art. 9. (roadmap#797) applies_when_tags: [biometrics, biometric authentication, biometric identification, biometric verification, facial recognition, face recognition, face verification, face matching, face match, face authentication, face biometrics, face swap, voice biometrics, voice cloning, voice clone, speaker recognition, speaker verification, behavioral biometrics, liveness detection, liveness, liveness check, fingerprint recognition, iris recognition, palm recognition, emotion recognition, emotion ai, deepfake, deepfake detection] - id: reg_global_privacy_control label: Global Privacy Control honoured facet: regulatory points: 4 rule: 'common[].type includes "GlobalPrivacyControl"' description: > A statement that the GPC signal is honoured. Four US states now require a universal opt-out to be respected, and the signal is machine-readable by design. Asked for by: Colorado, California, Connecticut, Texas universal opt-out. (roadmap#444) - id: reg_data_subject_request label: Data-subject request route facet: regulatory points: 4 rule: 'common[].type includes "DataSubjectRequest"' description: > A documented route for access, deletion and portability requests. Required by GDPR and by twenty US state laws, and a route nobody can find is a route that does not exist. Asked for by: GDPR; UK GDPR; 20 US state privacy laws. (roadmap#444) - id: reg_subprocessors label: Subprocessor list facet: regulatory points: 4 rule: 'common[].type includes "Subprocessors"' description: > A current subprocessor list. Art. 28 makes it a contractual duty and DORA and NIS2 both push it down the supply chain; it is the artifact a customer's own auditor asks for first. Asked for by: GDPR Art. 28; DORA; NIS2; DOJ bulk data rule. (roadmap#444) - id: reg_data_residency label: Data residency statement facet: regulatory points: 4 rule: 'common[].type includes "DataResidency"' description: > A statement of where data is stored and processed. The DOJ bulk-data rule made this a transfer question rather than a preference, and sovereign-cloud procurement asks it directly. Asked for by: DOJ bulk data rule; EU Data Act; sovereign cloud. (roadmap#444) - id: reg_incident_notification label: Incident notification commitment facet: regulatory points: 4 rule: 'common[].type includes "IncidentNotification"' description: > A published incident-notification commitment with a timeframe. A customer subject to SEC Item 1.05, DORA or NIS2 inherits the obligation and cannot meet it without one from its vendor. Asked for by: SEC Item 1.05 flow-down; DORA; SOCI; NIS2. (roadmap#444) - id: reg_age_assurance label: Age assurance facet: regulatory points: 4 rule: 'common[].type includes "AgeAssurance"' description: > An age-assurance statement or mechanism. NOT YET GATED: the catalog has no derived consumer-surface signal, so this is scored only within an applicable regime rather than against every provider (see the applicability note beside NA_UNLESS_CHECK in score.rb). Asked for by: UK Online Safety Act; AU Social Media Minimum Age; app store accountability laws. (roadmap#444) - id: reg_notice_and_action label: Notice-and-action mechanism facet: regulatory points: 4 rule: 'common[].type includes "NoticeAndAction"' description: > A notice-and-action route for illegal content. NOT YET GATED, for the same reason as age assurance. Asked for by: EU Digital Services Act. (roadmap#444) - id: reg_transparency_report label: Transparency report facet: regulatory points: 4 rule: 'common[].type includes "TransparencyReport"' description: > A published transparency report. NOT YET GATED, for the same reason as age assurance. Asked for by: DSA; UK Online Safety Act. (roadmap#444) - id: reg_exit_assistance label: Exit assistance / switching terms facet: regulatory points: 4 rule: 'common[].type includes "ExitAssistance"' description: > Published switching and exit-assistance terms. The Data Act made egress and exit a regulated term of cloud contracts rather than a commercial courtesy. Asked for by: EU Data Act cloud switching. (roadmap#444) - id: reg_mandate_verified label: Mandate implemented, not merely claimed facet: regulatory points: 8 regime: [banking_open_finance, energy_utilities, health] rule: 'the mandated surface is evidenced by a resolvable endpoint, register entry or conformant discovery document — not by a compliance page' description: > THE LARGEST UNMEASURED EFFECT IN THE CATALOG, and the reason it lands in 0.6 rather than waiting. Across 95 energy organizations scored on a deliberately ruthless mandate ladder, a VERIFIED mandate was worth about twelve points of composite — live-implemented 42.2 against not-applicable 36.6 — while a CLAIMED-but-unverifiable mandate scored 30.4, BELOW the 30.2 of organizations under no obligation at all. That second number is the finding. Self-declared compliance is not merely uninformative, it is NEGATIVE signal, and any assessment that reads compliance pages instead of calling endpoints will rank the field backwards at the top. Compare RESO in real estate at 2.0 points: same question, two sectors, a six-fold difference in effect, because one mandate came with a public register and conformant discovery endpoints and the other came with a badge. The failure mode is already live here: two Ontario utilities present as Green Button compliant and cannot be verified, one because its onboarding host returns HTTP 200 for every path including invented ones, being a single-page-app catch-all. Without a verification state that provider scores as compliant. open_source: label: Open Source Surface description: > The maintainership surface an open-source API product publishes on its own repository. Scored ONLY where we hold a live successful read of that repository — harvested directly from the GitHub API, never inferred from the pointers in apis.yml. WHY NOT READ THE POINTERS. Every other provider-level check in this rubric reads common[]. These deliberately do not. A pointer records that WE wired something; the harvest records that the PROVIDER published something. Scoring the pointer would dock a provider for catalog work we had not got to — the two-sided attribution failure these cohort passes exist to catch. This was not theoretical. 647 of the 1,151 records in the first evidence file had been RECONSTRUCTED from apis.yml pointers after a partial run clobbered the originals, and they disagreed with a live read systematically: CodeOfConduct +22.2 points, ContributionGuide +18.0, SecurityPolicy +13.9, and not a single provider holding only one signal against 21% in the live set. Reconstruction can only recover what somebody had already wired, so sparse providers had nothing to reconstruct from and vanished. All 647 were re-harvested live before this facet shipped, and reconstructed records are excluded from the facet by score.rb regardless. IssueTracker IS DELIBERATELY NOT A CHECK. It reads 100.0% across all 1,148 live-harvested repositories, because the harvester derives /issues from the repository URL and every GitHub repo has one. It is not an observation of the provider. Scoring it would hand free points out for existing. checks: - id: os_security_policy label: Published vulnerability-disclosure path facet: open_source points: 14 rule: 'a SECURITY policy is present on the provider''s own product repository' description: > Where an integrator reports a vulnerability in the thing they just put into production. The rarest of the four at 35.0% and the one that most directly affects a consumer, which is why it carries the most points. - id: os_contribution_guide label: Documented contribution route facet: open_source points: 10 rule: 'a CONTRIBUTING guide is present on the provider''s own product repository' description: > Whether the project is actually open to participation or merely published. 62.4% coverage. - id: os_releases label: Published release history facet: open_source points: 10 rule: 'the provider''s own product repository publishes releases' description: > Versioned, dated artifacts — the thing a consumer checks before depending on a project. Commonest of the four at 76.0%, but priced above the code of conduct because it carries far more information about whether the project is maintained. - id: os_code_of_conduct label: Stated code of conduct facet: open_source points: 6 rule: 'a CODE_OF_CONDUCT is present on the provider''s own product repository' description: > A stated standard for participation. Priced lowest of the four despite being rarer than releases at 49.6%: it is the most template-prone signal in the set, frequently dropped in wholesale, and so says the least about the project that holds it. upsert: label: Create-or-Update Ergonomics description: > Whether a provider's WRITE surface lets a caller create-or-update in one call, measured directly from the OpenAPIs in the catalog rather than from anything we wired. Scored ONLY where a contract parsed AND carried write operations: 6,803 providers of 7,955 with a parseable contract. The other 1,125 accept no writes and go N/A — a read-only API is not deficient for being unable to upsert. TWO TRAPS THE SCANNER AVOIDS, both found by getting them wrong first. COMPONENT TITLES ARE NOT THE CONTRACT: Pipedrive names its response schemas UpsertPersonResponse and UpsertOrganizationResponse on plain addPerson and updatePerson — internal naming leaking outward. A naive grep credits Pipedrive with an upsert it does not have on persons, organizations or deals, so matching is restricted to path, operationId, summary and description. And ALTERNATE-KEY LOOKUP IS NOT UPSERT: HubSpot's /batch/read also takes idProperty, so read, search, query, list, export, archive, delete, merge, validate, preview, clone, revert and publish paths are excluded along with every non-write method. WHAT IS DELIBERATELY NOT SCORED. The scanner also detects a documented 200-vs-201 split, and an earlier draft of this facet counted it as an outcome discriminator. It is not one: a 200/201 pair is documented for many unrelated reasons and says nothing about which branch actually ran. It matches 569 providers against 94 for a real discriminator field, and counting it would have made the top of this facet six times commoner than the measurement that justifies the facet at all. Recorded in the evidence file, worth zero points. Reference implementation: HubSpot's POST /crm/objects/{version}/contacts/ batch/upsert — idProperty in, `new: true|false` per result item out, 200/207. The only common CRM implementation carrying the whole pattern. checks: - id: upsert_outcome_discriminator label: The response says which branch ran facet: upsert points: 14 rule: 'a create-or-update response carries a boolean discriminator (new, created, is_new, was_created)' description: > The scarce one, and the one that matters: 1.4% of providers that accept writes. Upsert you cannot reconcile afterwards is upsert you have to trust. Without a discriminator a caller cannot tell an insert from an update without re-reading, which is the search-and-branch the upsert was supposed to remove. Priced highest because it is both the rarest signal and the one that changes what an integrator can safely build. - id: upsert_alternate_key label: The caller declares the key to match on facet: upsert points: 10 rule: 'a write operation accepts a caller-named natural key (idProperty, external_id, match_on, on_conflict, id_type) or an alternate-key path shape' description: > 9.8%. This is where identity resolution actually changes hands: the provider agrees to match on an identifier the caller already owns rather than making the caller discover the provider's own id first. Includes Salesforce's PATCH /sobjects/{OBJECT}/{FIELD}/{value} path shape, which expresses the same commitment in the URL instead of the body. - id: upsert_named label: A named create-or-update operation facet: upsert points: 8 rule: 'an operation is named as an upsert or a create-or-update in its path, operationId or summary' description: > 12.3%. The capability is discoverable from the contract without reading prose. Priced below the alternate key deliberately: naming an operation `upsert` is a claim, whereas accepting a caller's key is a commitment. - id: upsert_declared_conflict label: Duplicate handling is stated at all facet: upsert points: 4 rule: 'the create endpoint carries a conflict/duplicate-handling flag, or the description states create-if-absent behaviour' description: > 9.2%, and worth little on purpose. This is the capability existing but undiscoverable — stated only in prose ("creates it if it does not exist", usually on PUT /{id}), or bolted onto create as a boolean (Twenty CRM's `upsert: true`). It is real and a caller can use it, but it cannot be found by reading the contract's shape, so it earns a fraction of a named operation. # --------------------------------------------------------------------------- # Output bands — used to label providers in UI / search. # Composite score (0–100) maps to a band; bands drive sorting tiers and badges. # --------------------------------------------------------------------------- # Band cut points are calibrated against the observed catalog distribution, not # picked round. Re-derive them with signals/band_distribution.rb after any # material rubric change — a band nobody occupies, or one holding 40% of the # catalog, tells a provider nothing about where they stand or what to do next. # # v0.4 re-cut (2026-07-17), from the 2026-07-15 snapshot of 8,956 providers: # - `minimal` held 40.7% of the catalog — a single undifferentiated bucket # spanning the whole 0–29 range. A provider doing real work from 6 to 28 # never saw their label move, which breaks the improvement loop the score # exists to drive. # - The 0–29 range is not uniform. 1,180 providers spike at 6–8 (the true # "index entry and nothing else" floor), 9–14 is a sparse valley (236 # providers), and 15–29 is a densely populated ramp (2,231). The valley at # 14/15 is a real feature of the data, so that is where `minimal` now ends # and `emerging` begins — the cut follows the distribution rather than a # percentile. # - `exemplar` was documented as 70–100, but the catalog's observed ceiling is # 79.2. It is now expressed as an open-ended floor (70+) so the ladder stops # advertising 20 points of range that nobody has ever occupied. # # v0.6 re-cut (2026-07-28), 25,573 providers, 70/60/45/30/15 -> 66/56/42/28/13. # THE PRINCIPLE: 0.6 is a correctness release, not a change in ambition. A # provider that published nothing different should not change band because the # rubric learned to read authorship. The batch moved the composite down by a # mean of 1.92 points and a median of 1.80 — provenance grading and the raised # discoverability bar pushing down, contract-type-agnostic scoring and broadened # governance pushing up — so the cuts move with it. # # Held against the 0.5.1 shares, the re-cut preserves what each rung MEANS: # # band 0.5.1 0.6 at 66/56/42/28/13 # exemplar 1.1% 1.0% # strong 3.8% 4.1% # developing 13.4% 13.7% # thin 15.0% 15.0% # emerging 22.5% 23.5% # minimal 44.2% 42.6% # # 2,239 providers change band — 8.8%, against 13.8% if the old cuts were left in # place. Every one of those moved because its evidence changed: GraphQL-native # providers rising as the contract facet learned to read them (grafast, pothos, # envelop, graphql-code-generator, agility-cms all +10.7), telecom rising into a # regime that did not exist (totogi +15.0), and providers resting on derived # artifacts falling. # # `minimal` at 42.6% still holds more of the catalog than any band should. That # is a CATALOG COMPOSITION fact, not a calibration miss: 4,999 providers sit in a # single 2-point bucket at 4–6, the true "index entry and nothing else" floor of # a 25,573-provider catalog that grew from 8,956. Splitting it needs a signal # that distinguishes those providers from each other, which no facet currently # has. Queued, not fudged. # 0.24.0 — `share:` refreshed from the first PUBLISHED 0.23.0 run (_data/history/2026-09-25.json, # 27,360 providers). Cuts unchanged. `minimal` rises 39.0% -> 41.9% mostly because roadmap#593 now # scores 1,096 defunct companies zero instead of leaving their old numbers in place. bands: - id: exemplar label: Exemplar min: 66.5 range: 66.5+ share: 1.5% description: > Reference-quality API operations across every facet — a rich contract, published governance, transparent operations, and machine-readable commercial terms. The top ~1% of the catalog, and the band no provider reaches by accident. - id: strong label: Strong min: 54.3 range: 54.3 – 66.4 share: 4.3% description: > Solid contracts, transparent operations, and an easy start. Typically complete on four or five facets with one clear soft spot — most often governance or a missing commercial artifact. - id: developing label: Developing min: 39.3 range: 39.3 – 54.2 share: 12.9% description: > Real signal across most facets with visible, nameable gaps. The contract exists but is thin on descriptions or examples, or the portal is good while governance and commercial terms are absent. - id: thin label: Thin min: 26.2 range: 26.2 – 39.2 share: 16.3% description: > Limited machine-readable signal and partial portal coverage. Usually a provider with documentation a human can read but little a machine or agent can consume without scraping. - id: emerging label: Emerging min: 11.0 range: 11 – 26.1 share: 23.2% description: > More than an index entry, but the surface is still mostly links rather than artifacts. These providers have started publishing — a portal, a few common links, maybe a spec — and are the cohort most likely to move a full band from modest, well-targeted work. - id: minimal label: Minimal min: 0 range: 0 – 10.9 share: 41.9% description: > Index entry only; little beyond a description and a link. Nothing here is machine-readable enough for an agent to act on without a human first reading the site. # --------------------------------------------------------------------------- # Trending — applied on top of the absolute score using week-over-week deltas. # Stored as a sibling label so search can boost improving APIs. # --------------------------------------------------------------------------- trending: rising_threshold: 5 falling_threshold: -5 history_window_weeks: 12 # =========================================================================== # Agent Readiness — a STANDALONE score, deliberately NOT blended into the # composite above. The composite measures how complete and consumable an API # surface is for a human developer; this measures how safely an autonomous AI # AGENT can drive it. They are correlated but not the same, so they are scored # and displayed side by side rather than merged. # # Model adapted from api-evangelist/agent-readiness (the nine-dimension model, # scored 0–3 there). Here each dimension is a provider-level presence check # awarding points; the earned total is normalized to 0–100 and mapped to a # band. Sourced entirely from signals already in the catalog — the x-agentic- # access contract, MCP servers, Agent Skills, error/idempotency/rate-limit # common links, well-known catalogs — so it re-runs on every scoring pass with # no deep-spec parsing. # # Unlike the composite, a missing spec here is a REAL deficiency, not N/A: an # API with no machine-readable contract cannot be driven by an agent at all, # so every dimension is always in the denominator. # =========================================================================== # =========================================================================== # 0.12 — ACCOUNTABILITY. A STANDALONE LAYER. NEVER FOLDED INTO THE COMPOSITE. # =========================================================================== # # WHAT IT MEASURES: who is answerable, and what must happen before a thing ships. # Not what a contract says -- `contract_governance` does that, and carrying both # under the word "governance" would have put two unrelated Governance numbers on # one provider page. That collision is why this layer exists under this name. # # WHY `accountability` AND NOT `policy`. Half these checks are not about a # document at all: accountable_officer, standing_body and impact_assessment # measure APPARATUS AND PROCESS. A provider could publish an immaculate policy and # score half. Naming the layer after the artifact would also be # presence-is-not-provenance in the title bar -- the constraint this layer is # built on is that a policy PDF that exists is not a governed institution; one # with a version, an approval date, a named owner and a review cycle is evidence. # (`policy` also collides with four existing checks that live in other facets: # deprecation_policy, privacy_policy, reg_privacy_policy, os_security_policy.) # # THE BLUEPRINT IS ENTERPRISE-GENERAL. It was derived from universities, where the # Open University is the only institution in the research with real governance -- # a versioned Responsible AI Policy V1.3, a named SIRO, mandatory assessments. But # every check transposes to a commercial vendor without alteration. What varies by # sector is not the blueprint, it is the DISCLOSURE SURFACE: a university publishes # because it answers to students and regulators, a bank under supervision, a SaaS # vendor behind a Trust Center login, and a private company may govern well and # publish nothing. That is why `domains:` is a field rather than baked into check # names -- v1 reads `ai`, and the same eight checks will read a data, security or # access policy without a rename. # # IT IS NOT A HYPE INDEX. The layer must be able to rank an institution with ONE # narrowly-scoped tool, a versioned policy and mandatory assessments ABOVE one with # five vendor tools and no policy. `proportionality_clause` is the check that keeps # it honest: the Open University's principle 5.8, "keep AI use proportionate", is # the only institutional text in the research treating NOT DEPLOYING as a valid # outcome. If a draft of this ever ranks tool count, it is wrong. # # UNSCORED IN 0.12. The schema ships; no number does. Five profiled institutions # is a hypothesis, not a calibration, and `band_distribution.rb` cuts bands from a # measured distribution -- there is none yet. Tier 2 checks are RESEARCHED, not # harvested, and cannot run at 26k scale. Scoring waits for ~50 institutions. # --------------------------------------------------------------------------- # 0.12 — DISCLOSURE STATES (roadmap#28, #70, #67, and the university research). # # An index-class check reads a pointer in apis.yml while the evidence lives on the # provider's own surface. When the check is unearned there are two readings the # rubric already handles -- we never indexed it, they never published it. There are # THREE MORE, and collapsing them into one zero is how a policy choice, a language # barrier and a login become indistinguishable from an absence. # # published public URL, fetched, status code recorded -> scoreable # refused serves a browser, 403s an identified crawler -> OURS # authwalled exists, behind SSO / a customer portal / an NDA -> OURS # language published, not in a language we read -> OURS # unpublished no evidence either way -> reportable # # THE THREE MIDDLE STATES ARE OUR LIMIT, NOT THEIRS, and a report may never state # one as a market finding. Same rule the `attribution:` block enforces for points, # applied to reachability. # # WHERE EACH WAS EARNED: # refused -- www.tibco.com and www.sap.com serve 200 to a browser and 403 to a # declared, self-identifying catalog crawler. TIBCO scores 57.2 and # SAP 56.9, and part of both numbers is a statement about their edge # policy rather than about what they publish. Blocking crawlers is an # ordinary, defensible decision -- which is exactly why it needs a # name instead of quietly becoming a lower score. # authwalled -- NYU's Private GenAI pilot sits behind institutional SSO. # Generalises to any SaaS Trust Center behind a login. # language -- Yonsei's generative-AI guideline exists only on the Korean surface. # # `language` and `authwalled` were EARNED BY THE UNIVERSITY RESEARCH: three of five # profiled institutions hit one or the other. The commercial catalog never needed # them and would have gone on mis-reading those cases indefinitely. # # A JS CHALLENGE IS NOT A REFUSAL. makeBIMI returns Cloudflare's "Just a moment..." # interstitial to everything -- an anti-bot challenge a headless browser would pass, # not a WAF rule naming our crawler. Only the second is a statement about us. disclosure_states: published: scoreable: true attribution: index refused: scoreable: false attribution: ours note: serves a browser, refuses a declared crawler — named, not penalised authwalled: scoreable: false attribution: ours note: published behind SSO, a customer portal or an NDA language: scoreable: false attribution: ours note: published, not in a language we read js_challenge: scoreable: false attribution: ours note: anti-bot interstitial — a headless browser would pass it unpublished: scoreable: true attribution: provider note: the only state a report may quote as an absence accountability: standalone: true scored: false schema_version: '0.1' label: Accountability description: > Who is answerable for this organisation's use of a technology, and what must happen before it is deployed. Standalone, beside Agent Readiness; never part of the Kin Score composite. domains: [ai, data, security, access] active_domains: [ai] # A Tier-1-only organisation is NEVER ranked against a Tier-2 one, and every # published score carries its tier. This is roadmap#35's finding -- cohorts # enriched to different depths measure our coverage as much as the market -- # stated as a scoring constraint instead of a caveat. tiers: 1: machine-checkable; runs catalog-wide (document metadata, probed status codes) 2: researched; runs only on a profiled cohort (ownership, process, proportionality) # Two classes the commercial catalog never needed, both EARNED by the university # research: three of five profiled institutions hit one or the other. A zero in # either is OUR research gap and may never be reported as an institutional # finding. They generalise -- a German public body, a Japanese vendor, and any # SaaS Trust Center behind a login are the same shape. attribution_classes: catalog: we can satisfy it alone index: their surface, our pointer — probe first language: published, but not in a language we read authwall: published, behind SSO or a customer portal frontier: only the organisation can produce it checks: - id: policy_published tier: 1 attribution: index points: 10 description: A policy document for the active domain RESOLVES — status code, not link presence. - id: policy_versioned tier: 1 attribution: frontier points: 8 description: Carries a version, an approval date and a review cycle. - id: policy_owner_named tier: 2 attribution: frontier points: 8 description: A named ROLE owns it (DPO, CISO, Chief Trust Officer, SIRO). - id: accountable_officer tier: 2 attribution: frontier points: 7 description: A senior accountable officer exists and is named. - id: standing_body tier: 2 attribution: frontier points: 6 description: A standing governance body with a named chair. - id: impact_assessment tier: 2 attribution: frontier points: 10 description: A MANDATORY assessment before deployment, not an optional guideline. - id: proportionality_clause tier: 2 attribution: frontier points: 6 description: > The policy contemplates NOT deploying. The check that stops this being a hype index — it must be able to rank restraint above enthusiasm. - id: regulation_scoped tier: 2 attribution: frontier points: 5 description: > Scoped against a NAMED regulation rather than generic ethics language. Lives here and not in the education regime: this is organisational posture, not a property of the API surface, and carrying it in both was the same collision the governance rename exists to fix. # PLACEHOLDERS. Not cut, and not cuttable until a real cohort is scored. `Owned` # replaces the draft's `Accountable`, which collided with the layer name — and is # the truer word anyway, since it is what policy_owner_named and # accountable_officer actually establish. bands: - {id: governed, label: Governed, note: versioned policy, named owner, mandatory assessment, and an operated surface} - {id: owned, label: Owned, note: real governance and named ownership, but no programmatic surface} - {id: provisioned, label: Provisioned, note: tools provided and documented; governance thin or unowned} - {id: declared, label: Declared, note: something published, with no ownership or process behind it} - {id: undeclared, label: Undeclared, note: building or teaching with no findable posture} agent_readiness: schema_version: '0.2' standalone: true # not part of the composite; own score + own band label: Agent Readiness description: > How safely an autonomous AI agent — not just a human developer — can drive this API. Measures machine-readable contracts, agent-native access controls, and the operational signals (idempotency, stable errors, rate-limit state) an agent needs to act without a human papering over the gaps. dimensions: - id: spec_presence label: Machine-Readable Contract points: 18 signal: 'api_specs includes an OpenAPI document' description: > A public OpenAPI contract exists. Agents call APIs from contracts, not HTML docs — with no spec there is no programmatic surface to drive, which is why this is the single largest award. # REWEIGHTED 15 -> 10 AND PROVENANCE-GRADED IN 0.6. Not a judgment that the # x-agentic-access contract matters less — it is the most explicit agent-design # signal in the catalog and has no equivalent anywhere in the field. It is a # judgment that this dimension was measuring API Evangelist. Of the 6,388 # providers carrying an agentic-access artifact, 6,383 are `method: generated` # — 99.9%. At 15 points every one of them earned the second-largest award in the # model for work this pipeline did on their behalf, and a dimension nearly # everyone earns identically is not discriminating between anyone. - id: agentic_access label: Agentic Access Contract points: 10 provenance: agentic_access signal: 'agentic_access artifact present (x-agentic-access), graded by author' description: > The provider publishes an x-agentic-access contract classifying each operation by action-class, consequence, and human-in-the-loop escalation. The most explicit "this API was designed to be driven by an agent" signal in the catalog — when the provider publishes it. A derived classification keeps a floor: it is a real artifact an agent can fetch and act on, it is simply not evidence about the provider's design intent. - id: reversibility_documented label: Documented Reversibility points: 6 graded: true credit: {verified: 1.0, documented: 0.4} signal: 'a reversal operation in the contract, graded up when a window is documented too' description: > Does the contract say what can be UNDONE, how, and within what window. roadmap#68 proposed this over a consequence multiplier on dry-run and idempotency, and preferred it for a reason that holds up: a multiplier needs whole markets classified by hazard, which is the hard part, while this measures something no dimension covers and needs no such classification. It is what an agent actually needs BEFORE it acts. Dry-run lets it rehearse and idempotency stops it double-firing; neither tells it whether the action it is about to take can be taken back. GRADED. `documented` = a reversal operation exists in the contract (cancel, refund, void, reverse, undo, rollback, restore). `verified` = that AND a stated window (grace_period, cancellation_window, "within 30 days"). A path says the capability exists; the window is what makes it plannable. A window with NO reversal operation behind it earns nothing -- that is a policy sentence, not a capability. MEASURED 2026-08-18 across 7,579 providers holding a contract: 1,353 (17.8%) expose a reversal operation, 343 (4.5%) document a window, 171 (2.3%) do both. It discriminates without being near-empty, which is what a new dimension has to clear. GATED ON WRITE SURFACE like the other hazard dimensions: a read-only API has nothing to reverse, and a zero there would measure the absence of a hazard rather than the absence of work. - id: mcp_server label: MCP Server points: 12 provenance: mcp graded: true credit: {verified: 1.0, templated: 0.6, documented: 0.4, platform: 0.25} # --------------------------------------------------------------------- # 0.22.0 (roadmap#317) — GRADED BY WHO BUILT IT, not only by whether it answered. # # 0.6 fixed REACHABILITY: it stopped paying for servers nobody could connect to. # It left AUTHORSHIP unfixed, and authorship is most of the cohort. Measured by # clustering tool-name shapes across every server that enumerates (451 of 472 # live): 292 providers — 64.7% — serve a tool surface shared with other # providers. 129 share one commerce fingerprint, 62 are Wix, 37 Mintlify, 35 # Shopify. 51 answer at /wp-json/mcp/mcp-oauth-server: one WordPress plugin on a # marketing site, not 51 product decisions. # # All 292 hold the full 12 points today — 2,628 points paid for other people's # engineering, inside the layer whose purpose is to say whether THIS provider is # ready for agents. # # THE RUBRIC ALREADY DECIDED THIS for a different protocol: `agentic_commerce` # grades {self: 1.0, platform: 0.25}. Answering it differently for MCP was the # inconsistency; this removes it. # # templated 0.6 a real server whose URL an agent CANNOT CONSTRUCT — # https://{tenant}.mcp.example.com/mcp. Positive evidence, so # above `documented`; no self-service path, so below `verified`. # platform 0.25 the tool shape is shared with other providers. Real and # callable, and not this provider's design. # # ABSENT IS NOT `provider`. Authorship is knowable only where a server enumerates; # the 1,055 that gate tools/list behind auth are never classified and keep # `verified`. Unknown authorship is never read as platform authorship — roadmap#125. # # Net across both grades: -2,551. This mostly REMOVES credit. # --------------------------------------------------------------------- signal: 'deployment.mode + probe verdict on the mcp/ manifest, not the pointer; an unprobed slug falls back to authorship' description: > A Model Context Protocol server makes the API directly callable by agents over a uniform tool surface — the most direct expression of agent-first design. PROVENANCE-GRADED IN 0.6. Across four national banking markets exactly one institution ran a genuinely hosted MCP; in UK insurance the data credited 14.3% of the cohort and the real number was zero. Catalog-wide, 1,882 of 3,046 MCP artifacts are derived candidates with no URL. Twelve points is the third-largest award in this model and it was being paid, more often than not, for a server nobody can connect to. - id: auth_clarity label: Machine-Readable Auth points: 10 graded: true credit: bound: 1.00 served: 0.90 negotiable: 0.75 bearer: 0.35 signal: 'a served openid-configuration/oauth-authorization-server carrying `issuer` (served), else the securitySchemes class in the provider OpenAPIs — bound (mutualTLS, DPoP, Signature) > negotiable (oauth2 authorizationCode/clientCredentials, openIdConnect) > bearer (http bearer, apiKey)' description: > Can an agent authenticate in a way that is bound to it, or only bear a secret? Graded in 0.12.2 (roadmap#97): this credited presence and stopped, so `apiKey` earned the same ten points as OIDC. IETF draft-klrc-aiagent-auth-00 calls static API keys "an antipattern for agent identity — bearer artifacts that are not cryptographically bound, do not convey identity, are typically long-lived and are operationally difficult to rotate". A dimension named Machine-Readable Auth was paying top price for the artifact the field is converging on calling unsuitable. THE FLOOR IS 0.35 AND NOT ZERO, deliberately: a documented API key is still machine-readable auth, and zeroing the 2,209 providers who declare only `apiKey` would measure the market rather than the provider. Read from the refined per-tag OpenAPIs, which already carry `securitySchemes` — no probe and no new artifact. The apis.yml pointer remains a FALLBACK grading `bearer`, so a provider whose specs we have not indexed is not zeroed for our own gap; a pointer cannot name a scheme class. THE ID STAYS `auth_clarity` ON PURPOSE. `auth_scheme_strength` in planned_dimensions describes this change, but the dimension id is POSITIONAL — DIM_ORDER in build_listings.py and DIMENSIONS in the glyph both encode by slot — so renaming it is a coordinated four-place change of the kind roadmap#89 documents. The regrade is the value; the rename is cosmetic and can ride a future glyph release. Same reasoning as the `emits_as` facet aliases. # --------------------------------------------------------------------- # THE THREE SPEC-VERIFIED DIMENSIONS (graded in 0.6) # # These were link-based proxies: a provider earned the full award for # publishing a documentation page titled "Idempotent Requests". That is the # one criticism of this rubric a reviewer will find first, it is fair, and # a published competitor (Jentic's JAIRF, Apache-2.0, December 2025) ships # this class of check today. # # 0.6 does NOT replace the proxies — replacing them would zero every # provider with a documented behaviour and no published spec, which is a # different error. Each becomes GRADED instead: # # verified the behaviour is present in the contract itself 1.00 # documented only a provider-level link asserts it 0.50 # # A provider who proves it in the spec now outscores one who claims it in # prose, and one who does neither still scores zero. # --------------------------------------------------------------------- - id: idempotency label: Idempotency points: 9 graded: true credit: {verified: 1.0, documented: 0.5, derived: 0.125} # 0.23.0 (roadmap#787) — `derived` = every pointer that would make this `documented` is a # file API Evangelist derived (its own `method:` says derived/generated/modeled…), not the # provider documenting it. 0.125 = documented 0.5 x the derived provenance credit 0.25, the # same discount every provenance-graded check takes. `searched` (a transcription of the # provider's own prose) stays `documented`. Same grade on error_semantics and # rate_limit_signal. The agent-native gate does not accept it (band_gate.unsatisfied_grades). signal: 'OpenAPI mutating operations declare an idempotency key — a header, a request-body property, or a named de-duplication token whose own description says so (verified); else common[].type matches /idempoten/i (documented)' # ----------------------------------------------------------------------- # 0.20.1 (roadmap#289) — WHAT COUNTS AS A DECLARED IDEMPOTENCY KEY. # # Until 0.20.1 the verified arm also fired on `requestBody.to_s =~ /idempoten/i` # — a substring over the stringified request body. That credited PROSE: an # operation whose description said "this endpoint is NOT idempotent" earned the # check it denied. Measured over 133,932 specs, 70 of 337 providers' credit # rested on that arm alone. # # Removing it outright was wrong in the other direction. 11 of those 70 declare # a real `idempotency_key` property that the reader missed only because it would # not resolve a single local $ref, and 29 more ship the capability under the # industry's other name. Square, Block and Moneris were all in the first group. # # So the vocabulary lives here rather than as a regex in score.rb, and is read # in two tiers: # # names a field called this IS an idempotency key, on its own # dedup_names a field called this counts only when its OWN description, # example or default says it prevents duplicate execution. # `clientToken` is AWS's idempotency convention across # hundreds of APIs and elsewhere can mean an auth token, so # it is never taken on the name alone. # # `unique_token` is in dedup_names and `unique_id` / `uniqueId` deliberately are # NOT: measured, the latter are generic identifiers — 10web's sitemap id, # akamai's network-list id — while shopify documents `unique_token` with the # example value "client-side-idempotency-token". # # Net movement: 337 -> 381 providers verified (+73, -29). The 29 losses are # providers whose only evidence is the word appearing in prose; shopify is one, # and its request schema is literally `schema: {}` with the token appearing only # inside an example payload. # ----------------------------------------------------------------------- key_names: names: - /idempoten/i dedup_names: - /\Aclient[-_]?(request[-_]?)?token\z/i - /\Adedup(e|lication)?[-_]?(key|id|token)\z/i - /\Aunique[-_]?token\z/i confirms: >- idempoten|prevent\w*\s+(the\s+)?(accidental\s+)?(creation\s+of\s+)?duplicat| avoid\w*\s+duplicat|only\s+once|exactly\s+once|no\s+more\s+than\s+once| duplicate\s+(request|creation|execution|submission) description: > Mutating operations accept an idempotency key. Agents retry; without idempotency a retry double-charges a card, sends a message twice, or opens a duplicate ticket. Full credit requires the parameter to appear on POST / PATCH / PUT operations in the contract — the difference between a provider saying they support it and a contract an agent can act on. - id: error_semantics label: Stable Error Semantics points: 8 graded: true credit: {verified: 1.0, documented: 0.5, derived: 0.125} signal: 'OpenAPI $refs a shared error schema across 4xx/5xx responses (verified), else common[].type includes ErrorCatalog / ErrorCodes / DeclineCodes' description: > Errors are a documented, stable envelope with stable codes. Agents branch on errors — free-text messages break that branching and send an agent into blind retries. Full credit requires a single error schema referenced across error responses: a typed envelope, not a catalogue of codes in a table. - id: openapi_examples label: Request/Response Examples points: 7 graded: true credit: {verified: 1.0, partial: 0.5, documented: 0.25} signal: 'share of operations carrying request/response examples; else an Examples / Code Samples link' description: > Meaningful examples are published. Examples are the cheapest way an agent learns a payload shape before it ever makes a call. Graded in 0.6 because as a bit it ran at roughly 0% across payments and healthcare and discriminated between nobody: full credit at 50%+ of operations carrying an example, half below that, a quarter for a documentation link alone. - id: rate_limit_signal label: Rate-Limit Signaling points: 7 graded: true credit: {verified: 1.0, documented: 0.5, derived: 0.125} signal: 'OpenAPI responses document X-RateLimit-* / RateLimit headers (verified), else a rate_limits artifact or RateLimits link (documented)' description: > Rate-limit behaviour is documented as machine-readable data. An agent needs to know when to back off; "you will get a 429 eventually" is not something it can plan against. Full credit requires the API to surface live rate-limit state in RESPONSE HEADERS, which is what an agent reads mid-run — documented limits tell it the ceiling, headers tell it where it is. - id: event_surface_described label: Typed Event Surface points: 6 signal: 'AsyncAPI document, OR webhooks/callbacks objects in the as-published OpenAPI, OR common[].type includes Webhooks' description: > Event and webhook surfaces are described by a contract, so an agent that must react to state changes has a typed surface rather than example payloads. RENAMED AND WIDENED IN 0.9 — it was `asyncapi_events` and read only the asyncapi/ directory, which named the artifact rather than the capability and scored a provider false for describing their events the other legal way. A webhook can be described in OpenAPI: 3.1 added a top-level `webhooks` object and `callbacks` predates it. In this catalog 125 providers do exactly that — 87 via `webhooks` across 2,218 events, 39 via `callbacks` — against ZERO who publish AsyncAPI. Both count, equally: the dimension asks whether an agent can read the event surface, not which specification the provider chose to write it in. - id: agent_skills label: Agent Skills points: 5 provenance: skills signal: 'skills artifact present, graded by who authored it' description: > Packaged operating instructions an agent should follow when using the API, rather than leaving usage to be inferred from the spec. PROVENANCE-GRADED IN 0.6: 2,018 of 2,274 skill sets in the catalog are API-Evangelist-generated. In UK insurance all 27 were; across all of telecom, provider-published agent skills exist at exactly three companies. - id: well_known_catalog label: Well-Known Catalog points: 4 signal: 'common[].type includes WellKnown, APICatalog, or api-catalog' description: > A /.well-known/api-catalog (RFC 9727) linkset — the canonical machine entrypoint an agent hits first to discover the provider's APIs and MCP endpoints. - id: consent_identity label: Consent & Bot Identity points: 3 signal: 'common[].type includes AIPREF, ContentSignal, WebBotAuth, or HTTPMessageSignatures' description: > Forward-looking signals for machine-readable AI usage preferences (AIPREF, Content-Signals) and cryptographically identified agent traffic (Web Bot Auth / RFC 9421). Rare today; rewards the providers defining the frontier. SecurityTxt was accepted here until 0.15.0 and earned 93% of the credit — an RFC 9116 vulnerability-disclosure contact expresses no AI usage preference and identifies no agent. It still scores under well_known_published, which is where a /.well-known/ document belongs. # GRADED, not binary — the only dimension scored on a scale rather than a bit. # A survey of 22,341 catalog hosts (2026-07-28) found 65 providers serving an # agent card and only 10 of them conformant: `capabilities` shipped as an array # where A2A defines an object, `supportedInterfaces` where the spec says # `additionalInterfaces`, no `protocolVersion` at all. A boolean would record 65 # adopters of a specification 41 of them are not following. - id: agent_card label: A2A Agent Card points: 8 graded: true signal: 'a2a/-a2a.yml manifest, graded on conformance.grade against A2A 1.0.0' # 0.23.0 (roadmap#461) — a card fetched from a host outside the provider's own registrable # domains is PLATFORM-SERVED (Microsoft Foundry for a hosted agent, Mintlify for a docs site): # the operator's identity and content, the platform's host and transport. The conformance # grade is multiplied by this, like mcp_server's `templated` (0.6), not `platform` (0.25). # Kin's call 2026-09-25. Unmeasurable (no source URL, no provider domain) is not platform-served. platform_served_credit: 0.6 credit: conformant: 1.0 # passes every structural check near-conformant: 0.6 # correctly shaped, omits optional fields flavored: 0.25 # agent card in spirit, fails a hard check invalid: 0.0 description: > The provider serves a machine-readable agent discovery manifest at the A2A well-known path (/.well-known/agent-card.json, RFC 8615), advertising its identity, capabilities, skills, endpoint and auth. Weighted above agent_skills despite low adoption for a structural reason: an agent card is the only agent surface in this rubric that CANNOT be derived on a provider's behalf — it is served from the provider's own host or it does not exist. Where mcp_server, agent_skills and agentic_access can all credit an artifact API Evangelist authored, this one is provider-published by construction, and so is immune to the provenance defect that distorts the others. # NEW IN 0.6 — the fourth planned dimension, and the only one with no # provider-level proxy to supersede. It has to be read from the contract or not # at all, which is why it waited for spec parsing. - id: dry_run_mode label: Dry-Run / Simulate Mode points: 4 signal: 'OpenAPI: destructive operations expose a dry_run / simulate / preview / validate_only parameter' description: > A destructive operation can be planned before it is committed. This is the safest agent-native affordance in existence and the rarest: it lets an agent show a human what it is about to do, or check its own work, without doing it. Every other safety rail in this model limits the damage of an action that has already happened; this one is the only dimension that prevents it. - id: delegated_identity label: Delegated User Identity points: 6 graded: true credit: served: 1.00 documented: 0.50 signal: 'a served discovery document listing authorization_code in grant_types_supported (served), else an oauth2 authorizationCode flow or openIdConnect declared in an OpenAPI (documented)' description: > Can a caller obtain a token scoped to the HUMAN it is acting for, or only a credential belonging to the integration itself? Section 10.3 of draft-klrc-aiagent-auth-00 splits exactly this way — the user delegates authorization, versus the agent obtains its own — and nothing in this rubric distinguished them. It is the difference between an audit log that can name a delegated subject and one that cannot, which Section 11 of that draft makes a MUST. DISTINCT FROM `auth_clarity` on purpose. A provider can hold strong bound credentials and still offer no delegation path, and the reverse is equally possible; scoring them as one dimension would let a strong answer to one question hide a missing answer to the other. MEASURED BEFORE IT WAS BUILT: 768 providers declare `authorizationCode`, ~67% of the 1,142 declaring any oauth2 and 20x the `openIdConnect` population. That discriminating power is what separates it from `agent_identity_declared`, which stays parked at 13 providers. ADDED AT SLOT 16, APPENDED. Dimension order is positional in DIM_ORDER and in the glyph; appending shifts nothing, inserting would shift every slot after it. - id: protected_resource_metadata label: Protected Resource Metadata points: 5 graded: true credit: verified: 1.00 documented: 0.50 signal: 'a served /.well-known/oauth-protected-resource carrying `resource` (documented), and naming its authorization_servers (verified)' description: > RFC 9728. Section 10.9.2 of draft-klrc-aiagent-auth-00 — an agent discovers HOW a resource is protected and WHICH authorization server protects it, at runtime, instead of being configured by a human. It is the ONLY part of that draft's composition that is a fetchable artifact at the provider's own domain; WIMSE identifiers, attestation and Transaction Tokens all live inside provider infrastructure and cannot be observed from outside. `resource` is the required field. `authorization_servers` is what makes the document actionable — without it an agent learns the resource is protected but not by whom, which describes a lock and not the key. NOT PROBED BY STATUS CODE. api.slack.com answers 200 text/html to this path and to both OAuth metadata paths — a docs-site catch-all — so a status probe would award full credit three times over to a provider serving none of them. The saved BODY is read and the required field tested. - id: dynamic_client_registration label: Registration Without a Human points: 6 signal: 'a `registration_endpoint` in the served RFC 8414 / OIDC discovery document' description: > RFC 7591. Section 10.9.3 — if every new agent needs a developer to fill in a portal form and paste a key, the provider has no agent onboarding path regardless of what its docs claim. `console_or_sandbox` and `sign_up_present` measure the HUMAN onboarding path only; this is the machine one. Costs ONE JSON KEY rather than a probe: `registration_endpoint` is a field of the discovery document the pipeline already fetches and saves on 889 providers. APPENDED AT SLOT 18. Dimension order is positional in DIM_ORDER and the glyph. - id: agentic_commerce # 0.18.2 (roadmap#188) — LABEL ONLY, no scoring change. "Agentic Commerce Surface" # invited exactly the reading roadmap#185 made: "98.3% false = nobody has built for # agents acting with consequence." The check measures one thing — a UCP/ACP # well-known document on the provider's own domain — and correctly reads false on # both protocol authors (Stripe, OpenAI), because neither is a storefront. The # label now says what is measured, so it can no longer support the sentence the # dimension cannot. label: Agentic Commerce Well-Known Document points: 5 graded: true credit: self: 1.00 platform: 0.25 signal: 'a parsing /.well-known/ucp.json or acp.json declaring a version and at least one service — `self` when its endpoints are on the provider''s own domain, `platform` when they are on a vendor''s' description: > 197 providers hold a real, parsing `/.well-known/ucp.json` and every one scored zero before this: `well_known_catalog` credits only api-catalog, security.txt and protected-resource, and NONE of the 197 holds any of those. A provider standing up a conformant agentic-commerce document was indistinguishable from one serving no `.well-known` at all. OPERATOR ATTRIBUTION IS SETTLED BEFORE THE AWARD. 193 of the 197 point at `.myshopify.com` — that is not 193 merchants shipping an agentic-commerce surface, it is one platform shipping one 193 times under its merchants' names, the same failure that ranked universities for Figshare's contract. The grade is decided from the document's own service endpoints: on the provider's registrable domain it is theirs; on a vendor's it is real, visible, and the vendor's. `platform` is graded down rather than zeroed because the capability genuinely exists — a buyer's agent can transact there. A PARSING DOCUMENT IS NOT ENOUGH: a version and at least one declared service are required, or it is a stub at the right path. NO AP2 CHECK AND NO x402 CHECK. AP2 defines no well-known path and no pointer — its artifacts are SD-JWT mandate chains presented in-band at transaction time, under authentication, so nothing anonymous is ever fetchable; 0 of the 197 UCP documents reference it. x402 is a 402 plus a response header and needs a live request to a paid endpoint. Scoring either would claim a measurement the surface does not permit — the rule the rubric already applies to draft-klrc-aiagent-auth. APPENDED AT SLOT 19. - id: pagination_ratio label: Pagination points: 5 graded: true credit: paginated: 1.0 partial: 0.5 signal: 'share of collection GETs (an array, or one wrapped in data/items/results ...) that declare a page/limit/offset/cursor parameter, a Link header or a next/cursor field; na with no collection GETs' description: > 0.25.0 (roadmap#982). An agent that cannot page a collection either truncates silently or pulls everything. Paginated at 90% of collection GETs, partial at 50%. Measured on a 1,000-provider sample: 35% of the providers with collection GETs paginate none of them. - id: operation_distinctiveness label: Distinct Operations points: 3 graded: true credit: distinct: 1.0 mostly: 0.5 signal: 'share of operations whose summary is unique within its document after light normalisation; na without two summarised operations' description: > 0.25.0 (roadmap#983, step 1). An agent choosing a tool by its description cannot tell two identical summaries apart, and it is the cheapest agent-readiness failure to fix. Distinct at 98% unique, mostly at 90%. Exact and normalised matches only; embedding distance is a later step. - id: mcp_tool_quality label: MCP Tool Quality points: 6 graded: true credit: full: 1.0 three_quarters: 0.75 half: 0.5 quarter: 0.25 manifest_check: tool_quality signal: 'graded from the `tool_quality` block of the provider''s mcp/ manifest (a live tools/list capture, mcp_tool_quality.py); the 0-1 credit of the four sub-checks, rounded to the nearest quarter; na with no capture or a platform-authored server' subchecks: - id: annotations points: 2 rule: 'share of tools carrying readOnlyHint or destructiveHint; full credit at >= 90%, linear below' - id: param_descriptions points: 2 rule: 'share of parameters with a description; full credit at >= 90%, linear below; no parameters = full credit' - id: hazard_hints points: 1 rule: 'no state-changing tool (name heuristic) is missing a destructiveHint' - id: weight points: 1 rule: '0.5 for a tool list under 20k tokens, plus 0.5 for no single tool over 1,200 tokens' description: > 0.26.0 (roadmap#994, promoted from the 0.25 observed signal). Whether an agent can use a server's tools safely and cheaply: annotated hazards, described parameters, and a tool list that fits in a context window. Not applicable without a live capture, or for a platform-authored server whose tool shape is not the provider's design (mcp_server already discounts those). # Cut points calibrated against the real distribution (re-cut 2026-07-28, # 25,573 providers) — re-derive with band_distribution.rb after any change to # dimensions or points. The spread is deliberately bimodal: a large floor at # 0–9 (no agent signal) and a large plateau — the ~3,300 providers the # enrichment pipeline gave the same baseline (a spec, a generated agentic- # access contract, documented auth, rate limits) and nothing more. No cut can # split an identical-score plateau, so agent-ready is intentionally broad: it # is the baseline cohort, and the differentiators (MCP, idempotency, stable # errors, examples) are what lift a provider out of it into agent-native. # # WHY THE CUTS MOVED IN 0.5.1 (60/45/15 -> 56/42/14). Agent Readiness is # earned/max, so adding agent_card raised max from 104 to 112 and rescaled every # provider's score by 104/112 — an arithmetic change, not a measurement one. # Left alone it would have pushed the baseline plateau from 48 to 44.6, just # under the old 45 cut, and DEMOTED 3,726 providers (14.6% of the catalog) for # publishing nothing different. The cuts are re-derived at the same valleys in # the rescaled distribution: 56 sits in the 57–59 trough, 42 just below the # plateau now at 44, 14 at the old 15 boundary. Result: 15 providers change # band, all UPWARD, and every one of them earned it with a published agent card. # # WHY THEY MOVED AGAIN IN 0.6 (56/42/14 -> 46/34/6). This time the cause is a # measurement change, not arithmetic, and it is the largest correction in the # rubric's history. Provenance grading cut the credit for derived MCP servers, # agent skills and agentic-access contracts to a quarter, which collapsed the # enrichment baseline plateau — the ~3,300 providers who all scored ~44 on a # spec, a GENERATED agentic-access contract, documented auth and rate limits. # That plateau now sits at 30–32 and holds 2,084 providers. # # Every cut is placed at a real feature of the re-scored distribution: # # 6 the valley immediately above the floor. 15,651 providers sit at 0–4 # with no agent signal at all; the 4–6 bucket holds 58. # 34 the valley ABOVE the baseline plateau (34–36 holds 244, against 2,084 # at 30–32). This is the correction stated as a cut point: a provider # whose only agent artifacts were written for it is agent-AWARE, not # agent-ready, and the old 42 cut sat on the wrong side of that plateau. # 46 the shoulder of a >50% drop (44–46 holds 487, 46–48 holds 232). # # Resulting shares: agent-native 1.2%, agent-ready 14.3%, agent-aware 23.1%, # human-only 61.4%. Agent-native falls from 6.1% to 1.2% and that IS the # finding — most of the old cohort was agent-native on artifacts API Evangelist # wrote. Of the 1,210 providers scoring above 46, the band gate below demotes # 895 for having no idempotency and no stable error envelope. # --------------------------------------------------------------------------- # BAND GATE (new in 0.6) — no dimension compensates for a missing safety rail. # # Agent Readiness is additive, so strengths cover for absences. The four largest # awards plus examples — spec_presence 18, agentic_access, mcp_server 12, # auth_clarity 10, openapi_examples 7 — clear the Agent-Native floor with # idempotency, error_semantics and rate_limit_signal ALL AT ZERO. That is # precisely the provider whose agent retries a payment twice, branches on # free-text errors, and backs off only after a 429. Calling it Agent-Native is # the single worst false positive this model can produce. # # Jentic's JAIRF makes that configuration impossible with a weighted harmonic # mean. Adopting one here would destabilise every score in the catalog and force # a recalibration for a problem that lives in one band. The proportionate fix is # a gate: cheap, mechanically simple, defensible in a sentence, and it touches no # arithmetic below the top band. Same family as JAIRF's structural gates # (FC < 40 caps at Level 0) — a score that adds up without ever refusing to award # is a score that can be farmed. # # A provider that meets the gate on the DOCUMENTED half-credit still passes: the # gate asks whether the rail exists at all, not how well it is evidenced. band_gate: agent-native: requires_all: [idempotency, error_semantics] demote_to: agent-ready # 0.18.2 (roadmap#243) — the gate reads COVERAGE, not presence. A documented # idempotency credit still earns its points, but the gate also consults the # provider's own conventions artifact, structurally and never by prose: # idempotency.coverage: partial|none fails the gate, and an enumerated scope: # list of <=5 operations reads as partial where no coverage field exists yet # (leadping: 2 of 99 mutating operations held agent-native; its artifact said # so in its own scope list). coverage: full and prose-only artifacts pass # unchanged — Stripe states a header across all writes and enumerates nothing. # 1-2 demotions today; the conventions recipe now emits the field, so the gate # tightens as artifacts are re-touched. idempotency_scope_check: true # 0.23.0 (roadmap#787) — our own derivation earns partial points, never the gate. unsatisfied_grades: [derived] rationale: > An agent driving a surface with no idempotency and no stable error envelope is not being driven safely, however much else the provider publishes. discloses: band_gated_from disclosure_note: > 0.9.3 — when this gate fires the payload emits `band_gated_from`, naming the band the score alone would have earned. 1,024 providers carried a label one step below their number with nothing saying why, which handed a reader a band and a published range that contradict each other. The field is absent when no gate fired, so its presence is the disclosure. # 0.18.2 (roadmap#245) — REACHABILITY CAP, a gate one band down. gutendex serves # no request to any programmatic client (host-wide 403 including an invented control # path) and robots.txt disallows its only API endpoint to every user-agent with named # agent bans and Content-Signal ai-train=no — and stayed band agent-ready, because # nothing read reachability or operator consent. The enrichment probe's own verdict # (x_coverage.state, lifted to the provider record by build.py) now caps the agent # band: probed-unreachable and parked surfaces cannot band above agent-aware, # disclosed via band_gated_from like every demotion. blocked/unreadable do NOT cap — # they are statements about the probe run, not the operator (roadmap#207's line). reachability_cap: demote_to: agent-aware states: [probed-unreachable, parked] # BAND RE-CUT AT 0.13.0. Four new dimensions took `max` from 117 to 139, so every # agent score is multiplied by 0.8417 before any provider earns a single new point. # The cuts are scaled by the SAME factor rather than re-derived from the curve, because # the property that matters after a denominator change is that A PROVIDER WHO PUBLISHED # NOTHING NEW KEEPS ITS BAND. Providers who gained on the new dimensions move up on merit; # nobody moves down for standing still. That is the 0.5.1 lesson, where agent_card at 8 # points would have demoted 3,726 providers (14.6%) for publishing nothing different. # # 5.1 also lands inside the deep valley from 4 to 13 that follows the 2-3 spike of 2,842 # providers, so the lowest cut is not sitting on a cliff where a fractional score change # would flip thousands between bands on the next run. # # The `share:` values below are UPDATED to what the catalog actually holds rather than # forcing the curve back to the old prose. The distribution moved for real reasons and # the documentation follows it, not the other way round. # # THE TOP TWO SHARES ARE POST-GATE, and that is why they are not what scaling predicts. # 849 providers score at or above 38.7 but only 313 keep agent-native: the band gate # demotes the other 536 for missing idempotency AND a stable error envelope. Scaling the # CUT does not scale the GATE, so agent-native lands at 1.1% rather than the 3.1% the # percentile implies, and those 536 land in agent-ready instead. bands: - id: agent-native label: Agent-Native min: 38.7 range: 38.7+ share: 1.4% description: > Built to be driven by agents, and the provider built it — a contract, a real agent surface the provider itself publishes, and the safety rails the band gate now requires: idempotency AND a stable error envelope. The providers an agent can drive safely today, as opposed to the providers somebody has written agent artifacts about. - id: agent-ready label: Agent-Ready min: 28.6 range: 28.6 – 38.6 share: 13.1% description: > An agent can drive the core surface. A machine-readable contract and documented auth are in place, and there is real agent-facing work beyond the baseline; the safety rails (idempotency, stable errors, rate-limit signalling) mostly are not. NARROWED IN 0.6. This band used to hold the enrichment baseline plateau — ~3,300 providers whose agentic-access contract was generated for them. Once that credit was graded down the plateau fell to 30–32 and the cut moved above it, so this band now means an agent surface the provider had a hand in rather than one the catalog supplied. - id: agent-aware label: Agent-Aware min: 5.1 range: 5.1 – 28.5 share: 25.5% description: > Partial machine-readable surface. An agent can read some of the API but would hit implicit conventions a human silently absorbs — the gaps where it retries blindly or gets stuck. - id: human-only label: Human-Only min: 0 range: 0 – 5 share: 60.0% description: > Little an agent can consume without a human first reading the site. A developer can integrate it; their agent cannot yet. # All four dimensions planned at 0.5.1 SHIPPED IN 0.6. Three landed as graded # upgrades to the link-based proxies they were specified to supersede # (idempotency, rate_limit_signal, error_semantics) rather than as replacements, # so a provider with a documented behaviour and no published spec keeps half # credit instead of dropping to zero. `dry_run_mode` landed as a new dimension, # since no provider-level proxy for it exists. # # --------------------------------------------------------------------------- # POSTURE: DISCOVERY NOW, CERTIFICATION LATER. A deliberate choice, recorded # here so it is not mistaken for an oversight. # # Today this rubric reads what a provider DECLARES and, from 0.6, verifies a # growing slice of it against the contract they serve. It does not certify. # Certifying every field asked for in apis.json — attesting that a declared # artifact is served, is current, and says what the declaration says it says — # was scoped and started via API onboarding, and the work and ongoing overhead # are large enough that pursuing it now would stall the thing the score is # actually for. # # What the score is for RIGHT NOW is discovery, plus the competitive pull that # makes a provider want to move their number. That pull is the mechanism: a # provider who publishes real artifacts to climb has published real artifacts, # and the catalog is better whether or not they were chasing a rank. The # rubric is expected to be optimized against. Hardening is the answer to that, # not gatekeeping, and it is a moving target by design. # # The direction of travel is therefore: declared -> verified-in-contract -> # attested/certified, one artifact class at a time, cheapest verification # first. 0.6 took the first step for four dimensions. The two entries below # take the next one, and both came out of scoring a provider who optimized # hard against 0.6 with entirely truthful artifacts (Xquik, 2026-08-01) — # which is exactly the pressure test that shows where declaration and reality # are still allowed to diverge. # --------------------------------------------------------------------------- # # --------------------------------------------------------------------------- # OBSERVED SIGNALS — measured every pass, reported, worth ZERO points. # # A signal lands here when it is fully implementable AND has no distribution. # That is a different reason for waiting than anything in `planned_dimensions` # below, where every entry is blocked on a CAPABILITY we do not have yet — a # probe, a parser, a collection. These are blocked on the catalog: the # detector works, runs, and finds nobody. # # WHY NOT JUST SCORE THEM AT ZERO. Because a dimension no provider can earn is # not a measurement, it is a rescale. Agent readiness is a 139-point # denominator; adding a 4-point dimension with zero earners divides every # provider in the catalog by 143 instead of 139 and moves ~1,900 of them # across a band cut. Nobody would have gotten worse at anything. That is the # `agent_card` failure in 0.5.1 — a raised denominator produced demotions that # were pure arithmetic — and the standing rule since is that a denominator # change ships with a band re-cut. Paying that cost to distinguish nobody from # nobody is the trade this block exists to refuse. # # It is also the honest answer to the opposite temptation: leaving a real, # ratified signal entirely unmentioned until it is popular enough to score. # A rubric that only names what its catalog already does is a lagging # indicator. Naming it here, with the count attached, means the first provider # to ship it is visible on the pass that finds them rather than whenever # somebody thinks to look. # # PROMOTION. `score.rb` prints the count for each signal in the run summary. # When one clears `promote_at`, it becomes a scored dimension in the next # rubric version — with points, a band re-cut, and the usual release. # --------------------------------------------------------------------------- observed_signals: - id: accept_query label: Accept-Query Advertisement signal: 'an OpenAPI response declares an Accept-Query header (RFC 10008 s.3)' spec_check: accept_query_header observed: 0 observed_at: '2026-08-27' observed_basis: > Zero of 26,641 providers, per the headers catalog (api-evangelist/headers/_store/accept-query.md), whose assemble.py reads declared headers out of every published specification file in the network. Independently confirmed here by the spec detector. promote_at: 25 promote_at_basis: > The headers catalog's own promotion line — 25 distinct providers is what it takes for a header to earn a page there rather than sit in the tail. Reusing that number keeps one definition of "in use" across both catalogs instead of inventing a second. description: > RFC 10008 (June 2026) standardised QUERY, an HTTP method that is safe and idempotent like GET but carries a request body like POST, and registered `Accept-Query` as the response header through which a resource advertises that it accepts QUERY and which query media types it understands. This is the most agent-legible discovery signal to arrive in years, and it is the reason it belongs on this list rather than a general standards list. Every other machine-readable declaration this rubric reads is a document somewhere else — a spec file, a well-known linkset, an MCP manifest. This one is served BY THE RESOURCE, AT THE RESOURCE, at request time. An agent that wants to know whether a search endpoint speaks a structured query language, and which one, asks the endpoint. No documentation site, no catalog, no out-of-band artifact. Zero observed. The method is three months old, and OpenAPI could not describe it at all until 3.2 added `additionalOperations` — 3.1's Path Item Object has a fixed set of method fields with no room for QUERY. So the tooling gate only just lifted. Recording the zero now makes this a baseline rather than a discovery later: `Accept-Query` adoption is the cleanest single measure of whether QUERY is landing in production or living in specification documents, and that is a curve worth having from t=0. - id: query_method label: QUERY Method Operations signal: 'an OpenAPI 3.2 path declares additionalOperations.QUERY' spec_check: query_method_operation observed: 0 observed_at: '2026-08-27' observed_basis: > Measured by the spec detector across every OpenAPI document in the catalog. Distinct from `accept_query`: this is the method appearing in a contract, that one is the resource advertising it at runtime. A provider can do either without the other, and which of the two moves first is itself the interesting result. promote_at: 25 description: > The companion contract-side signal. `POST /resource/search` is the workaround QUERY exists to retire, and it carries a real cost: it tells every cache, proxy, retry policy and code generator in the path that a READ is unsafe and non-idempotent. Every conditional request, every automatic retry, every cacheable response a read should get, a search endpoint has been giving up for twenty years. Worth watching for a second reason. RFC 10008 deliberately defines no query language — the body is whatever media type the resource advertises, which is why the RFC's own example names `application/jsonpath` and `application/sql`. That leaves an open slot directly above the method for a filter grammar a machine can validate, and which grammar fills it is a question this catalog is positioned to answer rather than guess at. - id: webmcp label: WebMCP In-Browser Tools signal: >- a script served by the provider's own pages registers tools with the browser's modelContext (W3C Web ML CG WebMCP draft) probe: webmcp observed: 81 observed_at: '2026-09-03' observed_basis: > 81 of 730 providers probed by signals/probe_webmcp.py across the hosted-MCP cohort (the providers whose MCP pages resolved a live endpoint — the population most likely to have gone browser-native too). BUT 72 OF THE 81 ARE ONE SCRIPT: cdn.readme.io's docs-hub bundle registers a search_docs tool on every ReadMe-hosted docs site (verified in the bundle: document.modelContext ?? navigator.modelContext, then registerTool). Platform-authored, exactly the shape contract_self_operated (0.18.0) and the live-MCP finding exist to keep from being credited as provider work. The DISTINCT deployments number 9: Cloudflare (x2 properties), Zapier, Nylas, Render, and four self-hosted (two of them a shared /.webmcp/bridge.js pattern). 6 of 81 ship only the deprecated navigator surface, dead in Chrome 150+ — the adoption curve and the decay curve, both from t=0. Detection is script-scoped (inline script bodies and fetched script files, never page prose) and requires the modelContext object AND a registration call in the SAME script, so a docs article ABOUT WebMCP cannot score as shipping it. Frozen snapshot at all/0-working/webmcp-deployment.json, same contract as mcp-deployment.json: every probed slug gets a verdict, so absent means unprobed, never "has nothing" (roadmap#125's lesson, inherited on day one). promote_at: 25 promote_at_basis: > The same line accept_query reuses from the headers catalog — 25 distinct providers is one definition of "in use" across the network's catalogs. THE RAW COUNT (81) ALREADY CLEARS IT AND PROMOTION IS STILL DEFERRED, deliberately: 72 of the 81 are one documentation platform's bundle, and the count that has to clear the line is providers whose own engineering shipped it — 9 today. Promoting on the raw count would re-create the false credit 0.18.0 just removed. On promotion this becomes a graded dimension (the mcp_server/reversibility shape: a runtime-verified tool list at 1.0, static detection at 0.4, with platform-shipped graded down the way tenant contracts are), with points, a band re-cut, and the usual release. description: > WebMCP (a W3C Web Machine Learning CG draft; Chrome ships it as an origin trial, Chrome 149-156) lets a WEB PAGE register typed, callable tools with the browser via document.modelContext.registerTool(), so an in-browser agent can drive the page's actual functionality instead of scraping its DOM. It is the browser-side counterpart of the MCP server this layer already scores: mcp_server measures whether the API is agent-drivable out-of-band; this measures whether the provider's SITE is agent-drivable in the session the user is already in — auth, state and all. Two reasons it is worth a tracked baseline now, and one reason it is NOT a scored dimension. Worth tracking: it is the first standards-track mechanism that makes the interactive web surface, not the API behind it, a first-class agent target — precisely the layer this rubric can see nowhere else — and the spec is young enough that the adoption curve from t=0 is itself a finding (the API surface moved from navigator to document mid-2026, and WHICH surface a provider ships is recorded in the snapshot as `flavor`). Not scored: nobody calls these tools yet — no mainstream agent invokes WebMCP tools as of 2026-09 — and a dimension with a near-empty earner set is a rescale, not a measurement (the agent_card lesson, restated at the top of this block). Measurement note: the name is already colliding. At least one provider (Pixeltable) markets a server-side MCP endpoint as its "WebMCP Server"; a detector keyed on the word would false-positive, which is why the probe keys on the registration API and not the name — and why Pixeltable correctly reads `none` in the snapshot. # What is queued next, and why each is waiting: planned_dimensions: - id: artifact_liveness label: Declared Artifact Liveness signal: 'a live common[] URL whose content matches its declared type, on a pointer-liveness file kept fresh — liveness itself already ships (roadmap#16)' blocked_on: probe status: build issue: https://github.com/api-evangelist/roadmap/issues/984 description: > Most operational and commercial checks are presence-only — they credit `common[].type` and never fetch the URL. A StatusPage entry pointing at an auth-gated health endpoint returning 403 scores identically to a real status page; so does a dead link, or a Plans URL serving a marketing page. This is the cheapest certification step available and the natural first one: a periodic HEAD/GET across declared artifacts, grading resolves / wrong-content / dead, feeding a multiplier rather than a new dimension. It is also the step that makes every downstream attestation claim defensible. - id: aauth_resource_metadata label: AAuth Resource Metadata signal: 'a served /.well-known/aauth-resource.json carrying `issuer` and `jwks_uri`' blocked_on: adoption status: parked issue: https://github.com/api-evangelist/roadmap/issues/985 description: > draft-hardt-oauth-aauth-protocol (Dick Hardt, 20 August 2026, Standards Track, expires 21 February 2027) — catalogued at /store/aauth/. Unlike draft-klrc-aiagent-auth above, AAuth IS observable: it defines four `/.well-known/aauth-*.json` documents, three JWT `typ` values and three HTTP headers, so it passes the test this cluster applies to AP2 and x402. Only `aauth-resource.json` is a PROVIDER's to serve — agent, person and access belong to three other roles. MEASURED 2026-08-30, AND THE ANSWER IS ZERO. Probed across the 1,486 hosts in this catalog that serve a REAL OAuth/OIDC discovery document — the most AAuth-adjacent cohort that exists, 1,304 providers, 513 of them serving a real RFC 9728 protected-resource doc — at all four AAuth paths. 5,944 requests. ZERO hosts serve an AAuth document. 269 answered 200 with something that was not one. PARKED, NOT DROPPED, and parked for the reason `agent_identity_declared` is: a dimension nobody can earn measures the market rather than the provider, and belongs in a report finding. `well_known_published` above now names aauth-resource.json in its accepted set, which costs nothing today and means the first provider to serve one is credited rather than silently zeroed — the roadmap#123 lesson, applied before the fact instead of after. RE-MEASURE BEFORE BUILDING. The probe is in the enrichment recipe's named path list; the write-up is all/0-working/aauth-adoption-2026-08-30.md. THE ONE APPARENT HIT WAS A CATCH-ALL, and it changed how this cluster probes. data.nasdaq.com returned a validly-shaped document at all four AAuth paths — and at a nonsense control path, `/.well-known/apis-io-negative-control-`, which returned the identical body. Testing a required field is NOT sufficient when the host echoes the requested path back into that field: `resource` was populated because the catch-all filled it from the URL. THE PROBE FOR ANY NEW WELL-KNOWN PATH MUST INCLUDE A NEGATIVE CONTROL — one request to a path that cannot exist — and discard the host on a 2xx. A control sweep of all 1,486 hosts found exactly one such host, so the defect is contained and NOT systemic; nasdaq-data-link's protected_resource_metadata credit stands, because that document is genuine and at its correct path. What is not creditable is anything NEW probed against that host. - id: agent_identity_declared label: Workload Identity for Callers signal: 'WIMSE/SPIFFE identifiers, WIT/SVID credentials, or Workload-Proof-Token accepted at the API surface' blocked_on: collection status: parked issue: https://github.com/api-evangelist/roadmap/issues/985 description: > Sections 5-6 — the identifier and its cryptographic binding, the actual spine of the draft. Almost certainly near-empty on the public API surface today: 13 providers in the catalog declare mutualTLS at all, and workload identity currently lives inside private meshes rather than at a public edge. Parked deliberately, not dropped. Re-measure before building it; a dimension nobody can earn measures the market, not the provider, and belongs in a report finding rather than in a score. # 0.25.0 (roadmap#986): per-operation contract checks grade only documents that carry operations. A # webhooks-only document (GatiFlow's split) has nothing these can measure. spec_checks_per_operation: [operations_summary_coverage, operations_description_coverage, operations_tagged, operations_operation_ids, response_coverage, error_responses_documented, security_applied]