The vendor’s document moves from 1.1.0 to 1.2.0, your CI breaking-change job passes, and you
publish the regenerated SDK as a minor. A customer’s build then fails, because label_url is gone
from the Shipment type. The spec diff called the removal informational, and the version number
followed the document instead of the code your callers compile against.
What you get
You will end up with a release rule that reads two diffs, the spec’s and the generated SDK’s. A CI check fails when a proposed version is smaller than the evidence. This is for you if you publish an SDK that a generator rewrites.
Short answer
Run oasdiff breaking with --fail-on ERR between the old and new OpenAPI documents, then compare
API Extractor reports of the SDK generated from each. Release a major when either shows a break,
a minor when either shows an addition, and a patch otherwise. The second check catches what the
first cannot see: a removed optional response field, or a generator upgrade that renames a class
with no spec change at all.
You will need
Node 22 or later, an OpenAPI 3 document and a generated SDK under git, and Go 1.24 or later to
run oasdiff. Verified 2026-11-21 against Node 22.23.5, oasdiff v1.39.0, @microsoft/api-extractor
7.60.1, and the TypeScript SDK that @voxgig/create-sdkgen 0.31.9 generated with @voxgig/sdkgen
4.44.3 and @voxgig/apidef 8.32.4. The documents in api/ are four versions of an invented
carrier’s API. The bump levels are the ones
Semantic Versioning 2.0.0 defines for a public API.1
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Hey API | A TypeScript client whose generator you pin exactly and upgrade on purpose | No version record in its output, and no bump of its own | You need the generator version written beside the code |
| Kiota | A stable-maturity language, where minor Kiota releases promise no generated surface breaks | No bump of the client version, and TypeScript is still preview | Your SDK is TypeScript and must not break on a Kiota upgrade |
| oasdiff breaking on the spec diff | Any generator, as the CI job that blocks a breaking document | Blind to removed optional response fields and to generator upgrades | You publish typed SDKs that callers compile |
| sdkgen output reviewed with API Extractor | An sdkgen TypeScript SDK whose exported types you can report | A build and a report per version, and entity classes the report leaves out | The SDK has no TypeScript target to report on |
| Speakeasy automatic versioning | Speakeasy generates the SDK and the vendor bumps info.version by the kind of change | It reads info.version and a checksum, never the content of the change | The vendor bumps info.version by habit |
Voxgig maintains sdkgen. It is one of five options on this page, and it decides no bump. The
generated ts/package.json said 0.0.1 after every run here, and the generated Makefile tags
ts/v0.0.1, a version written into it at generation.
oasdiff is the cheapest rule and the one CI already runs, but it reads only the document. The type report reads what callers compile, for the price of a build per version. Speakeasy bumps from the document’s own number, and also from its own generator upgrades, by the features the SDK uses. Kiota bumps nothing, but its release policy limits what its own upgrades may change.
Classify the spec change with oasdiff
oasdiff compares two documents. breaking reports errors and warnings, and it exits 0 whatever it
finds unless --fail-on is given, a fact record.sh recorded for the 2.0.0 change.2 The
changelog command lists every change, informational ones included. Its
versioning policy,
--fail-on MISSING-VERSION-BUMP, fails a breaking change that info.version did not answer with a
major, which checks the vendor’s number rather than the SDK’s.
head -8 generated/oasdiff/v1.1.0-to-v1.2.0.changelog.txt
4 changes: 0 error, 0 warning, 4 info
info [api-version-changed] at v1.2.0.json
in info
the API version changed from `1.1.0` to `1.2.0`
info [response-optional-property-removed] at v1.1.0.json
in API GET /shipments
removed the optional property `items/label_url` from the response with the `200` status
A client that ignores unknown fields loses nothing when an optional field disappears, so oasdiff files it as info. A typed SDK loses a property, and every caller that read it stops compiling.
Compare the generated surface with API Extractor
record.sh regenerated one sdkgen project from each document, built the TypeScript SDK, and ran
API Extractor on its entry point.
Regeneration overwrites ts/, so git shows the change, but a diff of the generated source mixes
runtime code with the types callers use. sdkgen’s three-way merge applies to the copies under .sdk/, not to the
generated output, as its
copies and merge page
says. The report reduces the output to its exported declarations.
api-diff.mjs keys each member line by the declaration it sits in. A removed or changed member is
a major change, and an added one is minor. bump.mjs takes the larger of that and oasdiff’s level.
node bump.mjs
release oasdiff SDK surface info.version bump
api 1.0.0 -> 1.1.0 minor minor (-0 +5) minor minor
api 1.1.0 -> 1.2.0 minor major (-2 +0) minor major
api 1.2.0 -> 2.0.0 major major (-1 +1) major major
apidef 8.32.4 -> 8.33.1 none major (-7 +8) none major
The second row is the release that broke the customer. Both oasdiff and the info.version
column call it minor, and the generated types say major:
node bump.mjs why 'api 1.1.0 -> 1.2.0'
- export interface Shipment :: label_url?: string;
- export interface ShipmentListMatch :: label_url?: string;
The report has a gap. The SDK’s entry point does not export its entity classes, so API Extractor
prints an ae-forgotten-export warning and lists none of their methods. A method removed from
ShipmentEntity would escape it, so add the classes to what the report reads before relying on it.
Record the generator version as a release input
The fourth row changes no byte of the document. Upgrading to @voxgig/apidef 8.33.1, with
@voxgig/sdkgen 4.45.0, named the events entity event instead of tracking_event. The SDK then
lost TrackingEvent() and its types and gained Event(). generated/sdkgen/entities.txt also
records apidef 8.33.1 under sdkgen 4.44.3, which renamed it the same way, so the apidef upgrade
alone causes it.
The scaffold’s .sdk/package.json holds the generator as ranges:
"@voxgig/apidef": "~8.32.3",
"@voxgig/model": "~12.0.2",
"@voxgig/sdkgen": "~4.44.3",
"@voxgig/util": ">=0.5",
"@voxgig/struct": ">=0.2",
A fresh npm install resolves those to whatever is newest within the range, so commit
.sdk/package-lock.json, install with npm ci, and treat a change to that lockfile as a change to
the SDK.
Version the same changes in Kiota and Hey API
Kiota writes kiota-lock.json beside the
client, with kiotaVersion and a descriptionHash of the document. Both runs here recorded
"kiotaVersion": "1.38.0", and the hash changed between 1.0.0 and 1.2.0, so a lockfile diff shows
which input moved. Kiota bumps no client version. Its
support page says minor releases carry
no breaking changes to the generated API surface of stable-maturity languages. Its
README marks C#, Go, Java, PHP, and Python stable, and Kiota
printed that TypeScript is in preview. Its labelUrl property disappeared at 1.2.0 as sdkgen’s did, so
the same API Extractor check applies to its output.
Hey API writes no version into its output; the header of types.gen.ts names the package and
nothing more. Its get started page says
the package is in initial development and asks you to pin an exact version. Do that, and record
the version with the release. label_url left its Shipment type at 1.2.0 too.
Check it worked
node bump.mjs check 'api 1.1.0 -> 1.2.0' 1.4.0 1.5.0
api 1.1.0 -> 1.2.0: SDK 1.4.0 -> 1.5.0 is a minor release, the evidence needs major: FAIL
It exits 1, so a CI step that runs it beside the oasdiff job blocks the minor release.
node --test bump.test.mjs
1..13
# tests 13
# suites 0
# pass 13
# fail 0
# cancelled 0
# skipped 0
# todo 0
The suite holds the four decisions, oasdiff’s exit codes with and without --fail-on, the two
removed members, the rename under both toolchains, and the Kiota and Hey API output.
When it goes wrong
The CI breaking-change job is green on every pull request. It runs oasdiff breaking without
--fail-on, which exits 0. Add --fail-on ERR, and test the exit code, as bump.mjs refuses any
code other than 0 or 1.
A release passes both checks and a caller still breaks. The change sat in an entity class that the report leaves out. Export the classes from the entry point the report reads, or diff the class declarations as well.
The SDK changes when nobody touched the document. The generator moved inside its range. Pin it, and run the surface check on every generator upgrade as you would on a spec change.
When not to do this
Do not build the surface check for an untyped client. A JavaScript or Python caller does not fail to compile on a removed field, and oasdiff’s levels describe its exposure well enough.
Do not trust sdkgen’s output to stay still across a generator upgrade. Its scaffold pins with ranges, and apidef 8.33.1 renamed an entity with no spec change.
Do not let info.version decide alone. The vendor called the label_url removal 1.2.0.
Kiota is the better choice when your SDK targets C#, Go, Java, PHP, or Python, because its
release policy covers its own upgrades there. Speakeasy suits a team that wants the bump made for
it, from a vendor whose info.version tracks each change. Hey API suits a TypeScript-only team that pins it exactly.
Related how-tos
Last verified
Verified 2026-11-21 against Node 22.23.5, oasdiff v1.39.0, @microsoft/api-extractor 7.60.1,
@voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3 and 4.45.0, @voxgig/apidef 8.32.4 and 8.33.1,
Kiota 1.38.0, and @hey-api/openapi-ts 0.99.0. Every output block is what the command preceding
it printed. record.sh ran each tool once, and what they wrote is committed under generated/.
Speakeasy was not run; its rules come from its documentation.
Footnotes
-
Semantic Versioning 2.0.0 starts from a declared public API and says the version must change in a way that reflects how that API changed. It leaves the declaring to you. For a generated SDK, the declaration is whatever the generator exported on the day it ran. ↩︎ Back to text
-
The oasdiff breaking-changes page says
--fail-on ERRexits with return code 1 when there is an error. The same command without the flag reports the error on stdout and exits 0, which is a report rather than a gate. ↩︎ Back to text