API Evangelist Paper · Standard Report
The OpenAPI Overlay Standard
122 stars, 21 contributors, two people writing four fifths of it — and Elastic, MongoDB, Cloudinary and Vercel running it in production. Attention and adoption have come apart.
About this report
The OpenAPI Overlay Specification applies a repeatable list of changes to an OpenAPI document without editing that document. Strip internal endpoints. Inject examples. Fix a generated spec before codegen. The original stays canonical and the transformation becomes an artifact you can version and re-run.
It has 122 stars, against Arazzo’s 460 and OpenAPI’s 31,123 — and it is the most genuinely used of the three. Of the documents a public-index probe can enumerate, 63.4% sit at paths indicating real use, against 36% for Arazzo. An Arazzo document describes something for a reader; an Overlay document does something in a pipeline, and an artifact with a job in CI gets maintained because the build breaks when it is wrong.
Elastic, MongoDB, Cloudinary, Seqera and Vercel run it in production — nearly all doing the same job: a machine produced a specification, it is not good enough for the audience it must serve, and an overlay repairs it on the way out.
The largest single distributor is a code generator. Speakeasy emits a codeSamples.yaml overlay during SDK generation, into customer repositories that never chose Overlay — the same mechanism that distributes Arazzo. And the specification itself is two people: 21 contributors ever, the top two holding 81.2%.
What's inside
- Executive summary — attention and adoption have come apart
- What an Overlay is, and what it is not
- How adoption was measured, and where the method was capped
- What the documents are actually for
- Who is actually using it
- The generator is the distribution channel
- Why it is used, and what that says
- The body
- Conformance, tooling, and the one deliberate holdout
- The scoring caveat
- What would have to be true
- The investable thesis
- Where this is going
What you get
These reports are experience-based and vendor-neutral, distilled from the API Evangelist research at apievangelist.com. Every API Evangelist Standard Report is free to download. Found something wrong, or an artifact this report missed? [email protected] — pointing at an artifact is the fastest way to change the next version.
arrow_back All reports