OpenAPI Extensions Are Not a Mess, They Are a Map

apidays London 2026 · OpenAPI track

Kin Lane — API Evangelist

1 October 2026 · Convene Sancroft

Setting the scene

The map

2021 with a flashlight. 2026 with the catalog.

The map03 / 28

2021 with a flashlight, 2026 with the catalog

	2021	Aug 2026 (abstract)	Today
Providers	14	7,012	7,606
As-published OpenAPIs	a few dozen	15,722	24,801
Distinct provider `x-` extensions	~50	1,637	2,249
Uses	—	440,422	594,748

Stripped before counting: 27,239 HTTP header names that sit where an extension key would, and 5,169 uses of our own markers (42 names).

The map04 / 28

Eighteen jobs the specification does not do

Data & schema semantics1,212 names · 159,666 uses
Docs & developer experience179 names · 39,256 uses
Security79 names · 8,580 uses
SDK & code generation57 names · 52,823 uses
Mocking & testing49 names · 10,438 uses
Change management45 names · 6,746 uses
Visibility42 names · 6,119 uses
Artificial intelligence30 names · 1,307 uses
Capability declaration27 names · 7,473 uses

Provenance27 names · 1,345 uses
Events24 names · 10,524 uses
Performance & quality22 names · 9,556 uses
Runtime & gateway18 names · 982 uses
Pagination12 names · 631 uses
CLI11 names · 1,151 uses
Monetization7 names · 574 uses
Legal3 names · 56 uses
Privacy3 names · 36 uses

Named for a job: 1,847 names. Named for an owner: 402 names carrying 277,485 uses — 47% of all usage. Bars are square-root scaled.

The map05 / 28

The registry exists

entries at spec.openapis.org/registry

the OpenAPI Initiative's own backport shims

from the API community

# the whole process
1 markdown file
1 pull request

Seven registered. Two thousand two hundred in the wild.

Part one

The vocabularies that spread

SDK generators, documentation platforms and gateways — how one company's words end up in thousands of other companies' contracts.

Part one · The vocabularies that spread07 / 28

Redocly — the one that registered

124

providers use x-codeSamples

providers use x-internal

1 of 4

keys registered

x-codeSamples:
  - lang: cURL
    source: curl -X POST https://api.anrok.com/v1/seller/…

x-codeSamples is in the registry. x-internal — the visibility key 75 providers depend on — is not.

Part one · The vocabularies that spread08 / 28

Speakeasy — designed, not accreted

keys in x-speakeasy-

providers

registered

x-speakeasy-name-override: listApplications
x-speakeasy-unknown-values: allow   # 5,167 uses

What does your generated client do when the server sends an enum value it has never seen? Speakeasy wrote that answer into the contract.

Part one · The vocabularies that spread09 / 28

Microsoft — documented for a decade, never registered

195

x-ms- keys

164,499

uses across Azure and Graph

registered

x-ms-pageable:
  nextLinkName: nextLink        # 9,578 uses
x-ms-long-running-operation: true
x-ms-examples: { … }           # 11,673 uses

A public specification with prose for every key. Everything right except the last step.

Part one · The vocabularies that spread10 / 28

AWS — the standard nobody chose

companies outside AWS carry an x-amazon-apigateway- key

publish their gateway's backend wiring

x-amazon-apigateway-integration:
  uri: arn:aws:apigateway:us-east-1:lambda:path/…
       arn:aws:lambda:us-east-1:••••••••••••:
       function:contract-positions/invocations
  httpMethod: POST

API Gateway imports OpenAPI and exports it back out. Publish the export as your docs, and the vocabulary — and your Lambda — ship with it.

Part one · The vocabularies that spread11 / 28

ReadMe — working code in eighty companies' contracts

providers

350

documents

1,040

uses

x-readme:
  code-samples:
    - language: java
      install: <dependency><groupId>com.asana</groupId>…

Not a docs hint. An install line and a working call, for one operation, in one language — in the contract.

Part one · The vocabularies that spread12 / 28

Stoplight — an extension that outlived its acquisition

10,889

uses

providers

things it tells you about the API

x-stoplight:
  id: 8v9on8n2939z2

The editor's fingerprints, left behind at export. Frequency measures how a document was made, not what matters in it.

Part one · The vocabularies that spread13 / 28

Stainless — inside the model providers' contracts

keys

providers

818

uses of x-stainless-const

x-stainless-const: true
# OpenAI · Groq · Together AI · Cloudflare
# SambaNova · Fireworks · Portkey

The contract describes the API. Their namespace describes how to read it into idiomatic code. The cleanest line in the series.

Part one · The vocabularies that spread14 / 28

Mintlify — a lot with one key

key

providers

881

uses

x-mint:
  href: /reference/generate-from-template-v2

This operation's human documentation lives here. The smallest vocabulary that still did the job.

Part one · The vocabularies that spread15 / 28

Fern — SDK design decisions in the contract

846

uses each, always as a pair

providers

x-fern-sdk-group-name: forms
x-fern-sdk-method-name: list

# client.forms.list()

For most developers the SDK is the API. Fern put that design decision where it can be reviewed.

Part one · The vocabularies that spread16 / 28

Tyk — one key, a whole gateway

key at the document root

published JSON Schema

x-tyk-api-gateway:
  info:       { name, state }
  server:     { listenPath, authentication }
  upstream:   { url, rateLimit }
  middleware: { global, operations }

One namespaced, schema'd object. The OpenAPI around it stays clean and portable. Alongside, not inside — done well.

Part two

The vocabulary being invented for agents

Sixteen companies. No coordination. By the end of this part, one key means five different things.

Part two · The vocabulary being invented for agents18 / 28

Six weeks

	Aug 19	Today
Agent tool-surface keys	13	24
Providers using them	10	16
Share of providers	0.14%	0.21%

Everyone generates MCP servers from OpenAPI — Speakeasy, Stainless, Kong, Apigee, Postman, Zuplo. Almost nobody tells the generator anything.

Part two · The vocabulary being invented for agents19 / 28

Wistia — the best agent vocabulary nobody knows about

keys

513

uses

provider

x-wistia-mcp-annotations:
  idempotent_hint: true
  idempotent_hint_justification: Re-sending the same
    update with identical attributes leaves the
    resource in the same state…

Names, descriptions, annotations with justifications, toolsets, per-plan gating. Great design with an audience of one.

Part two · The vocabulary being invented for agents20 / 28

Windmill and Algolia — convergence nobody can see

uses as a boolean — Windmill, Algolia

uses as a string — my own specs

# Windmill, Algolia
x-mcp-tool: true

# apis.io, API Evangelist (me)
x-mcp-tool: find_artifacts

Two teams, no coordination, same spelling, same shape. The other half of the collision is me.

Part two · The vocabulary being invented for agents21 / 28

Zoho — the largest deployment, on the path

342

uses

documents

provider — Zoho Inventory

/purchasereceives:
  x-mcp-group:
    - Purchase Receives

Everyone else marks an operation. Zoho marks the path — and names the business capability it belongs to.

Part two · The vocabulary being invented for agents22 / 28

Constant Contact — a prompt in the contract

keys: x-ctctmcp-allow, x-ctctmcp-tool-desc

x-ctctmcp-tool-desc: >
  …default to a polished, production-ready HTML
  marketing email, not a schema-valid stub. Treat
  any included HTML example as the minimum visual
  quality bar…

Not an API description. Prompt engineering, addressed to a model, shipped in the contract for an HTTP endpoint.

Part two · The vocabulary being invented for agents23 / 28

MoEngage and Secureframe — the sequence, and who sees it

expose

internal · external — visibility, for agents

order

which tools to call first — workflow, in prose

x-moe-mcp:
  expose: { external: true, internal: true }
  tool_description: |
    Typical agent flow:
      1. Call list_offerings
      2. Pick the offering ID from the results
      3. Call update_offering with that ID

OpenAPI describes one operation at a time. These describe an operation's place in a sequence — Arazzo's job, done in a description field.

Part two · The vocabulary being invented for agents24 / 28

Zuplo — declaring a whole server

x-mcp-server

Zuplo, legal.ge

x-mcp

Redocly — same idea, different key

x-mcp-server:
  name: zuplo-docs
  version: 1.0.0
  tools:
    - name: search-zuplo-docs

Annotate the operations — or point from the contract at a separate agent interface? The industry has not picked.

Part two · The vocabulary being invented for agents25 / 28

Pipedrive — a price on every tool call

371

x-token-cost, Pipedrive

574

uses of any pricing key, whole catalog

uses of x-x402-price

operationId: getDeals
x-tool-description: Retrieves paginated active deals…
x-token-cost: 10

If agents are going to transact, they need to know what a call costs before they make it. Almost nobody is saying.

Part two · The vocabulary being invented for agents26 / 28

One key, five meanings

Demodesk	`x-mcp: {enabled: true, toolName: users_get_me, title: Get current user}`	expose, named, with a human title
Eon	`x-mcp: true`	expose
Ripio	`x-mcp: {enabled: false}`	do not expose
Dolby	`x-mcp: {description: …, destructiveHint: true}`	describe, warn — or {expose: false}
Redocly	`x-mcp: {protocolVersion: …, servers: [ … ]}`	where the server is

A tool built for Eon checks whether x-mcp is truthy. {enabled: false} is a non-empty object. Ripio's hidden operation ships.

27 / 28

Alongside, not inside

Register it. One file, one pull request. Seven have. spec.openapis.org/registry
Keep operational metadata alongside the contract. Overlays when you augment a spec. APIs.json when you describe the operations around it.
Look it up before you invent it. Every key in this talk: apis.io/extensions

Rate this session

Thank you

Kin Lane — API Evangelist

apis.io/extensions · apievangelist.com · [email protected]

Rate this session