11 Vercel spec pairs: a real 12-endpoint removal, and the release notes that cried breaking

vercel · report · 2026-08-02 · source: change database

The Vercel SDK ships an OpenAPI spec with every release, which makes it one of the few providers where you can check the changelog against the wire, version by version. We did, three ways: a 11-pair head-to-head between two diff engines across the published spec history, a raw-versus-curated accounting of the one release that actually removed endpoints, and a record-level diff of the release whose notes claimed breaking changes. The changelog got it wrong in both directions.

The head-to-head

Across 11 consecutive published pairs of the Vercel SDK spec (v1.27.0 through the v1.28.x line), oasdiff — the mature Apache-2.0 comparator, run as a vendored release binary — reported 105 breaking units. specdiff, the zero-dependency engine inside mendapi, reported 38. Only 16 units matched at the same normalized anchor: a 15% overlap, the lowest in our parity series. Units are anchor-plus-kind findings after taxonomy normalization, with 0 engine errors and 0 timeouts.

Both sides decompose exactly:

- oasdiff's 105 = 16 matched + 89 oasdiff-only units - specdiff's 38 = 16 matched + 22 specdiff-only units

89 oasdiff-only units, four buckets, zero unexplained

Every unit oasdiff reported and specdiff stayed silent about was classified from oasdiff's own finding texts:

- *74 oneOf composition changes — the signature pattern of this corpus. Vercel's spec generator restructures response schemas into and out of oneOf unions constantly; the wire payloads that validated before still validate after. An engine that pages on every composition change pages you 74 times for this corpus alone. - 7 object-to-any type widenings — schemas relaxed to accept strictly more than before. - 7 union-branch-optionality changes — a branch inside a union became optional; every previously valid payload remains valid. - 1 enum widening* — a value was added to an accepted set.

74 + 7 + 7 + 1 = 89, real gaps: 0, accounting: 100%. Cite that zero as "0 unexplained detection gaps after disposition", not as "specdiff detects everything oasdiff does" — all four buckets are deliberate silences under a false-positive-rate-first policy, documented per bucket in the classification files.

On the other side, specdiff reported 22 units that oasdiff did not report at the same normalized anchor. Unlike the Twilio corpus, where the specdiff-only side was human-verified unit by unit, Vercel's entries were spot-verified as detection kinds were added and were not systematically re-adjudicated pair by pair — so we cite them as "reported only by specdiff at the unit level", not as an accuracy claim.

The release that actually broke things

Between spec v1.28.13 and v1.28.14, the raw diff produced 136 records. Ingest that raw and you would be paged 136 times. The curation pass — endpoint-level removals only — kept 12: every one a breaking path-removed, and every one an /v1/edge-config route. The other 124 records were additive surface growth (71 response properties, 39 enum values, 12 new paths, 2 request properties).

That is a real removal event: the Edge Config API family — items, schema, tokens, backups, restore — dropped from the spec in a single release. All 12 removals are in the change database behind this site with fixability verdicts, and the Vercel SDK migration guide covers the code paths they touch.

The release notes that cried breaking

One release later, v1.28.15's own release notes flagged two breaking changes: vercel.user.listUserEvents(): response.events[] Changed (Breaking) and vercel.user.listEventTypes(): response.types[] Changed (Breaking). We diffed the published specs for that pair, record by record: 44 records — 18 enum-value-added, 17 response-prop-added, 9 request-prop-added — and 0 breaking. Every change is additive. A client built against v1.28.14 keeps validating against v1.28.15.

Changelogs lie in both directions. v1.28.14's removal of 12 endpoints is the direction everyone fears; v1.28.15's breaking-change announcement over a purely additive diff is the direction that quietly trains your team to ignore the changelog. Measuring the wire is the only position that catches both.

Re-verified, pair for pair

The corridor was re-run from cached snapshots after ingestion: 14 of 14 pairs (v1.27.0 through v1.28.13) reproduced their baseline breaking-unit counts exactly — zero regressions, zero new unexplained units. That guards this page against silent drift of the tooling; it is a statement about these cached snapshot pairs, not a forward guarantee about future Vercel releases, and none of these ratios extrapolate beyond this corpus and these versions.

Check your own repo

Every breaking unit from this corridor is in the change database with a fixability verdict. To find out whether your repo is exposed — file and line number, no code leaving your machine:

npx mendapi scan --repo .

The full Vercel timeline lives on the Vercel breaking-change guide. The three-provider harness the head-to-head came from has its own write-up, the Stripe corpus shows the same audit at depth, and the engine comparison methodology is documented on the when to use mendapi page.

Detected and tracked by mendapi — Dependabot for every API you depend on. Scans run locally; your code never leaves your machine.