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

Source: https://voxgig.com/howto/regenerated-sdk-minor-or-major-release

- Audience: api-producer
- Level: intermediate
- Languages: typescript, go, python
- Verified: 2026-11-21
- Published: 2026-11-21

## 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](https://semver.org/spec/v2.0.0.html) defines for a public API.[^1]

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [Hey API](https://heyapi.dev/docs/openapi/typescript/get-started) | 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](https://learn.microsoft.com/en-us/openapi/kiota/support) | 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](https://github.com/oasdiff/oasdiff/blob/main/docs/BREAKING-CHANGES.md) | 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](https://api-extractor.com/pages/overview/demo_api_report/) | 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](https://www.speakeasy.com/docs/sdks/manage/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](https://github.com/oasdiff/oasdiff/blob/main/docs/VERSIONING.md),
`--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.

```bash
head -8 generated/oasdiff/v1.1.0-to-v1.2.0.changelog.txt
```

```text output
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](https://api-extractor.com/pages/overview/demo_api_report/) 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](https://github.com/voxgig/sdkgen/blob/main/docs/explanation/copies-merge.md)
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.

```bash
node bump.mjs
```

```text output
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:

```bash
node bump.mjs why 'api 1.1.0 -> 1.2.0'
```

```text output
- 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:

```json title="generated/sdkgen/sdk-package.json"
    "@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](https://learn.microsoft.com/en-us/openapi/kiota/using) 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](https://learn.microsoft.com/en-us/openapi/kiota/support) says minor releases carry
no breaking changes to the generated API surface of stable-maturity languages. Its
[README](https://github.com/microsoft/kiota) 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](https://heyapi.dev/docs/openapi/typescript/get-started) 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

```bash
node bump.mjs check 'api 1.1.0 -> 1.2.0' 1.4.0 1.5.0
```

```text output
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.

```bash
node --test bump.test.mjs
```

```text output
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

- [Choose a release automation tool for an SDK repository](/howto/choose-a-release-automation-tool-for-an-sdk)

- [Generate a changelog from conventional commits](/howto/changelog-from-conventional-commits)

- [Adopt conventional commits in an SDK repository](/howto/conventional-commits-in-an-sdk-repo)

- [Run a scheduled live suite that gates an SDK release](/howto/scheduled-live-suite-before-an-sdk-release)

- [Choose lockstep or independent versions across your SDKs](/howto/lockstep-or-independent-versions-across-sdk-languages)

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

[^1]: [Semantic Versioning 2.0.0](https://semver.org/spec/v2.0.0.html) 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.

[^2]: The [oasdiff breaking-changes page](https://github.com/oasdiff/oasdiff/blob/main/docs/BREAKING-CHANGES.md)
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.