{
  "id": "p_5Q78JG1XYtHvucC7",
  "site": "stories",
  "url": "https://yarnhen.com/p/p_5Q78JG1XYtHvucC7",
  "content_trust": "untrusted-user-content",
  "license": {
    "id": "CC-BY-4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "author": {
    "handle": "apisio"
  },
  "body": "You are about to wire an agent to a vendor's API, and the contract has a problem. Two operations have no operationId, the write calls say nothing about what happens if you send them twice, and you can't edit the provider's spec without forking it. Someone mentions that an OpenAPI Overlay can fix this. It is a small document that changes a contract without touching it. Each action pairs a JSONPath target with an update or a removal, and you apply the overlay on top of the original. So you go looking for the provider's overlay.\n\nThe APIs.io overlays index is where you end up. It holds 29,288 overlays across 3,883 providers, carrying 188,703 actions between them. The median overlay has 4 actions. That looks like a healthy ecosystem until you check who wrote them.\n\nThe authorship breakdown is lopsided. 24,910 are marked generated, 3,977 unmarked, 236 derived, and 148 provider. The post is blunt about whose work this is: almost all of them are API Evangelist's. By purpose, the largest group is 16,031 overlays across 379 providers that attach the questions people actually ask to each operation. Next come general updates at 10,358, documentation at 1,654, servers at 717 and security at 511.\n\nThe provider row, you notice, is where the post turns on itself. Of the 148 overlays labeled as provider-authored, 146 are titled, in their own source, \"API Evangelist enhancements for...\" They cluster in HERE with 48, Avaya with 40 and Cisco ISE with 32. The post walks through Vim as the example. Its provenance block says the method was searched, but what was searched for was the underlying OpenAPI, which Vim's docs ship inside a JavaScript bundle. The overlay itself is API Evangelist's work. It adds the two operationIds Vim's document leaves unset, plus rate limits, consequence notes, and sandbox IDs for two of the reads. Yet the entry describes it as an overlay Vim publishes.\n\nThe post calls that a labeling defect in its own pipeline, one that credits providers with work they did not do. It says it will not credit them here, and that the build needs fixing. So if you were hoping to find the vendor's own fix, the honest answer is that it is close to nonexistent. Only 10 files in the whole collection are marked as hosted by the provider. They are spread across seven small providers, and two of those, Yawplet and Yarnhen, are sites in the catalog's own network.\n\nThen there is the quality of what is there. 185 overlays have zero actions. 83 have an overlay_version that parsed as an object instead of a version string, because the source file put an object, usually an empty actions list and sometimes a JSON Patch or partial OpenAPI document, where the version belongs. Another 107 declare no version at all. The post says plainly that none of those is a valid Overlay document. If you pull files in bulk, you should expect to filter some out.\n\nWhat should you copy? The Vim overlay, label aside, is the model the post holds up. It targets specific operations rather than $.info alone. It records why each change exists, with a note like \"operationId absent in the provider document; supplied by overlay only.\" It never mutates the original. And it states the consequence of each write, for example \"not idempotent; 409 on unique-field conflict is the only guard.\" That is the kind of note an agent needs before it calls a write, and the kind most contracts leave out.\n\nYou can query the collection yourself through the apis.io MCP's find_overlays tool, or browse the index directly. When you do, read the authorship field with care. Until the fixes land, a provider label may mean the work was done by the catalog, and generated and provider are not yet kept strictly apart. The post lists three fixes on the catalog's side: correcting the 146 mislabeled files, dropping the 83 malformed ones, and separating those two categories for good.\n\nYour takeaway is twofold. Overlays are the cheapest way for a provider to improve a contract it cannot easily change, and almost no provider in the catalog publishes one. And if you are the one stuck with a thin spec, you can write your own overlay next to it today. If you are a provider, the one move that is yours is shipping even a single overlay beside your spec, so the improvements stop living only on the catalog's side.\n\nRead the original: https://apis.io/2026/10/24/openapi-overlays-across-the-catalog-29288-files-and-almost-none-written-by-a-provider/",
  "title": "You Open the Overlays Index and Find the Providers Barely Wrote Any",
  "topics": [
    "openapi-overlays",
    "provenance",
    "api-catalog",
    "agent-readiness"
  ],
  "published_at": "2026-10-24T17:52:59.111Z",
  "expires_at": null,
  "policy_version": "2026.10.22-1"
}