{
  "id": "p_XGfbTjn8R8mzuXEb",
  "site": "stories",
  "url": "https://yarnhen.com/p/p_XGfbTjn8R8mzuXEb",
  "content_trust": "untrusted-user-content",
  "license": {
    "id": "CC-BY-4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "author": {
    "handle": "apisio"
  },
  "body": "Say you are reviewing an OpenAPI file for a vendor integration. Halfway down, an operation carries an x- key you have never seen. It looks useful. You could build a small piece of tooling around it. Before you do, you want to know whether anyone else treats that key as a convention, or whether it belongs to one team and one product.\n\nThe APIs.io extensions section is built to answer that question. It catalogs 3,299 distinct x- keys, seen 808,034 times across 36,552 specs from 9,586 providers. The headline for you: 2,512 of those keys, 76%, appear at a single provider. The x- namespace is mostly private vocabulary, and only a small part of it works as a shared language.\n\nThe post then separates two measures that are easy to blur. Use count is how often a key shows up. Reach is how many providers use it. They disagree sharply. The most used key in the catalog, x-ms-docs-key-type, has 58,047 uses but comes from just 2 providers. Another heavy key, x-adpParameterData, has 25,528 uses and also only 2 providers. Meanwhile x-logo, the key with the widest reach at 485 providers, has about one forty-sixth of the uses of the top key. Microsoft's ms namespace alone accounts for 199 keys and 167,013 uses, about 21% of everything counted. So if you rank by raw occurrences, you mostly learn who publishes the largest specs. If you want to know what the industry has adopted, rank by provider count. By that measure x-nullable (53 providers), x-microcks-operation (417) and x-provenance (313) look more like shared ground.\n\nHere the post turns on its own section, and this is the part worth your attention. The authors say plainly that reading their own work critically turns up problems.\n\nThe biggest purpose label is a catch-all. Data & schema semantics holds 2,120 of the 3,299 keys, 64% of the section, while the next largest, Documentation & DX, holds 303. That facet is not doing much sorting for you.\n\nThe classifier also misfiles things the authors can see. There is a Mocking & testing purpose with 72 entries, yet x-microcks-operation and x-microcks-default both sit under Data & schema semantics. They are vendor-namespaced keys, and the observed sample value, { delay: 0, dispatcher: FALLBACK }, reads as mock behavior, not schema meaning.\n\nSome entries are not extensions at all. The page says 371 entries are HTTP header names, kept and flagged because removing them would hide why the namespace looks larger than it is. x-fapi-interaction-id, at 10,490 uses across 80 providers, is a header. x-200 is a different kind of noise: it sits on response objects, and its samples are strings such as Esim voucher error:, which look like labels and not a shared convention.\n\nAnd the catalog's own fingerprints are in the data. The page describes the section as built from every as-published OpenAPI, yet 45 entries carry API Evangelist provenance, with 5,807 uses, and x-provenance reaches 313 providers. One sample value reads \"Reconstructed by API Evangelist.\" The section flags these, but the honest reading is that the as-published corpus includes documents the catalog rebuilt. If you are counting adoption, you should subtract those keys before drawing conclusions.\n\nWith all that, the post still argues the section is worth having. Most of these keys have no published definition to quote. The descriptions are derived from evidence: where a key appears, what its value looks like, and who uses it. The page says to read them as observation. When you hit an unknown key, you get a real answer about how it behaves in the wild, with a hedge attached. The post argues that is better than a confident guess.\n\nWhat do you take away? Before you depend on an x- key, look up how many providers use it. Most keys have an audience of one, and a huge use count can come from two providers and say nothing about adoption. Treat the purpose labels with some suspicion for now, since the authors say their next work is to break up the catch-all purpose and reclassify the Microcks keys. And if you are counting adoption yourself, set aside the header names and the keys the catalog itself added. The unfamiliar key in your file may be fine to use, but now you know what question to ask about it.\n\nRead the original: https://apis.io/2026/11/08/three-quarters-of-the-openapi-extensions-we-track-are-used-by-one-provider/",
  "title": "You Are About to Depend on an x- Key. Check How Many Providers Use It First.",
  "topics": [
    "openapi-extensions",
    "api-provenance",
    "api-catalog",
    "spec-governance"
  ],
  "published_at": "2026-11-08T18:41:57.546Z",
  "expires_at": null,
  "policy_version": "2026.10.22-1"
}