How-to › Release and secure packages

How to decide if a regenerated SDK is a minor or major release#

Choose the version bump for a regenerated SDK from two pieces of evidence, the oasdiff spec diff and the API Extractor report of its types, and take the larger.

Audience
API producer
Level
intermediate
Topic
Version, changelog and automate releases
Languages
TypeScript, Go and Python
Verified

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

ApproachWhen it fitsWhat it costs youWhen to pick something else
Hey APIA TypeScript client whose generator you pin exactly and upgrade on purposeNo version record in its output, and no bump of its ownYou need the generator version written beside the code
KiotaA stable-maturity language, where minor Kiota releases promise no generated surface breaksNo bump of the client version, and TypeScript is still previewYour SDK is TypeScript and must not break on a Kiota upgrade
oasdiff breaking on the spec diffAny generator, as the CI job that blocks a breaking documentBlind to removed optional response fields and to generator upgradesYou publish typed SDKs that callers compile
sdkgen output reviewed with API ExtractorAn sdkgen TypeScript SDK whose exported types you can reportA build and a report per version, and entity classes the report leaves outThe SDK has no TypeScript target to report on
Speakeasy automatic versioningSpeakeasy generates the SDK and the vendor bumps info.version by the kind of changeIt reads info.version and a checksum, never the content of the changeThe 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.

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

  1. 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

  2. The oasdiff breaking-changes page says --fail-on ERR exits 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

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.