An OpenAPI extension is any property whose name begins with x-. The specification reserves that prefix so tools can carry meaning the specification itself does not define — x-amazon-apigateway-integration tells API Gateway how to wire an operation, x-codeSamples tells a docs renderer what snippets to show, x-mcp-tool tells an MCP server what to expose as a tool. A parser that does not recognize an extension is required to ignore it, which is what makes them safe and also what makes them proliferate.
The problem is that almost none of them are written down anywhere a third party can find. I have been cataloguing every extension I can find in published contracts, and the vocabulary runs into the thousands of distinct keys. Meanwhile the OpenAPI Extension Registry — which exists, at spec.openapis.org/registry — holds a few dozen entries, most of them the OpenAPI Initiative’s own backport shims. Strip those out and the number the wider community has registered is a single digit.
So yes, register yours. The process is not a standards committee, a working group, or a year of meetings. It is a pull request with one markdown file. Redocly did it for x-codeSamples. That is the entire bar, and it is startlingly low relative to how many vendors have not cleared it.
Why it matters: an unregistered extension is a private dialect. Your customers cannot look it up, a code generator cannot know whether two similar keys mean the same thing, and an agent reading the contract has to guess. I keep finding the same semantics spelled several different ways by different vendors, and collisions where two organizations picked the same key for different things. Registration is how you turn a key your tooling happens to read into something anybody can point at.
A few practical rules. Namespace it — x-acme-retry, not x-retry — because the unprefixed names are exactly where collisions happen. Document what it applies to, what shape its value takes, and what a consumer should do when it is absent. And keep extensions out of your canonical contract where you can: an overlay is usually the better home for something that describes how one tool should treat your API rather than what your API is.
