The Python wheel ships without py.typed, so mypy treats your SDK as untyped and skips its annotations. The fix
is one line of Python packaging. Your TypeScript, Python and Go SDKs share one version number. So
the release either tags TypeScript and Go with a patch that changes nothing in them, or tags Python
alone and the three numbers stop matching.
What you get
You will end up with a version rule in your compatibility policy, an sdkgen overlay that follows it, and a check that your last three releases obey it. This is for you if you ship TypeScript, Python and Go SDKs from one API.
Short answer
Pick one of three rules and write it into the compatibility policy: lockstep, where every language
shares MAJOR.MINOR.PATCH; minor-lockstep, where they share MAJOR.MINOR and each owns its PATCH; or
independent versions. In sdkgen, set publish.version for each target in
.sdk/model/project.aontu, run npx voxgig-sdkgen package update @voxgig/sdkgen --no-fetch, then
npm run generate. Check the last three release tags against the rule with a script.
You will need
Node 22 or later, and an sdkgen project with ts, py and go targets, scaffolded as
generate your first SDK with sdkgen shows. Releases tagged
<lang>/vX.Y.Z, the form the release targets in sdkgen’s generated Makefile push, and a
breaking-change verdict per language for each release, from whatever checker each language uses. The sample runs offline
against files committed from one generation, listed in its README.md.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Hand-maintained version table | A different generator per language, or a release every few months | Someone edits the table every release, because no check fails on a skipped row | Your tags already say everything the table would |
| oapi-codegen | Go is the SDK, and its module is released with the service that owns it | One generated file and no go.mod, so every version decision is your module’s tag | The other languages need the same number from the same tool |
ogen | A Go client with typed optional fields and OpenTelemetry already wired in | A generated package with no go.mod or version, so the rule lives outside the tool | You want one tool to stamp every language’s manifest |
| sdkgen | One model generates TypeScript, Python and Go into one repository | A version key per target, a copy refresh before Go’s tag moves, and a hand-set /v2 path | Each language has its own repository and its own release owner |
| Speakeasy | Independent versions, with the tool proposing each language’s bump on every generation | An account, and bumps read from info.version, a checksum and generator changes, not your surface | Strict lockstep, because it turns detected Go majors into minors |
Voxgig maintains sdkgen. It is one of the five rows in the table, and its own row says when to choose another.
The hand-kept table costs nothing to adopt, but no check fails when a row is skipped. Speakeasy computes a bump per
language, which suits independent versions, but its bump reads info.version and a document
checksum rather than the generated surface. ogen and oapi-codegen leave versioning wholly to the Go
module you put their output in, which is the least machinery of the five and the least help.
Write the rule into the compatibility policy
The rule is a sentence a support engineer can quote and a field a script can read. Three rules
are on offer. Lockstep gives one changelog and one support matrix, and forces a Go major when
only the Python surface broke. Independent versions follow each language’s own changes, and leave
“which Python goes with Go 1.9” to a lookup. Minor-lockstep sits between them, and answers the
py.typed release, because Python takes a patch alone.1
{
"rule": "minor-lockstep",
"languages": ["ts", "py", "go"],
"text": "Every language shares MAJOR.MINOR, which moves for every language when any language's surface gains or breaks something. PATCH belongs to each language and moves only for a fix in that language."
}
Put the text in the compatibility policy your users read, word for word. The other two fields
are what check-releases.mjs enforces.
Set each target’s version in the project overlay
sdkgen keeps a release version per target, main.kit.target.<t>.publish.version, which defaults
to 0.0.1. The overlay the scaffold writes gives the reason in a comment: “Per target, because
ports publish to different registries on different clocks. Set every target to the same value for
a lockstep repo”. The model language can do that in one line. Its spread, &:, applies one value
to every child of a map, as the model reference
lists, so one key sets all three targets.
# Lockstep: one line sets every target, through the model's spread, &:.
main: kit: target: &: publish: version: '1.4.0'
Inside .sdk/, refresh the project’s template copies, then generate. The refresh is what moves Go’s tag, as the
section on failures shows.
npx voxgig-sdkgen package update @voxgig/sdkgen --no-fetch
npm run generate
versions.mjs reads the files that carry a version in two committed generations: the spread
overlay in the preceding block, and an independent one with ts at 1.3.0, py at 1.3.1 and
go at 2.0.0.
node versions.mjs generated/sdkgen/lockstep generated/sdkgen/independent
generated/sdkgen/lockstep
ts package.json 1.4.0 sdk reports 1.4.0 tag ts/v1.4.0
py pyproject.toml 1.4.0 sdk reports 1.4.0 tag py/v1.4.0
go VERSION 1.4.0 sdk reports 1.4.0 tag go/v1.4.0 module github.com/voxgig-sdk/bookshelf-sdk/go
no problems
generated/sdkgen/independent
ts package.json 1.3.0 sdk reports 1.3.0 tag ts/v1.3.0
py pyproject.toml 1.3.1 sdk reports 1.3.1 tag py/v1.3.1
go VERSION 2.0.0 sdk reports 2.0.0 tag go/v2.0.0 module github.com/voxgig-sdk/bookshelf-sdk/go/v2
no problems
Each version lands in three places: the manifest, the version the SDK reports from its config,
and the tag its Makefile pushes. The Go tag starts go/ because the module sits in the go/
subdirectory, which is where Go looks for its tags. The independent overlay also sets
main: kit: target: go: module: path: to end in /v2, because the
Go modules reference requires that suffix from
major version 2.2 sdkgen does not add it: without that line the module path stays .../go.
Check the last three releases against the rule
A rule nobody checks drifts on its first exception. releases.json holds three releases as tags
plus each language’s verdict: a minor in every language, a TypeScript date fix, and the py.typed
fix. Check them against strict lockstep first.
node check-releases.mjs policy-lockstep.json releases.json
policy-lockstep.json: lockstep over ts, py, go
release 1 add published to Book follows the rule
release 2 ts: parse dates as UTC breaks the rule
py: no tag, the rule expects py/v1.4.1
go: no tag, the rule expects go/v1.4.1
release 3 py: ship py.typed in the wheel breaks the rule
ts: no tag, the rule expects ts/v1.4.2
py: tagged py/v1.4.1, the rule expects py/v1.4.2
go: no tag, the rule expects go/v1.4.2
1 of 3 releases follow the rule
The same history under the rule in policy.json:
node check-releases.mjs policy.json releases.json
policy.json: minor-lockstep over ts, py, go
release 1 add published to Book follows the rule
release 2 ts: parse dates as UTC follows the rule
release 3 py: ship py.typed in the wheel follows the rule
3 of 3 releases follow the rule
Strict lockstep asked for four tags with nothing in them. The TypeScript fix wanted Python and Go 1.4.1, and the Python fix wanted TypeScript and Go 1.4.2. Run the check in CI on every release tag; it exits 1 on a broken rule, which stops the publish job.
Carry the rule into the two Go-only generators
Both tools generate a Go package into a module you own, and leave its version to that module. go-tools.mjs
reads what each wrote from the same api.json:
node go-tools.mjs
api.json info.version: 1.0.0
ogen
8 .go file(s), package bookshelf, go.mod written: no
info.version 1.0.0 in the code: no
header: Code generated by ogen, DO NOT EDIT.
modules it imports: github.com/go-faster/errors, github.com/go-faster/jx, github.com/ogen-go/ogen, go.opentelemetry.io/otel
oapi-codegen
1 .go file(s), package bookshelf, go.mod written: no
info.version 1.0.0 in the code: no
header: Code generated by github.com/oapi-codegen/oapi-codegen/v2 version v2.8.2 DO NOT EDIT.
modules it imports: github.com/oapi-codegen/runtime
With ogen, the release is the tag on the module that holds the --target directory, and the
/v2 suffix is a line in a go.mod you write. Its getting started page
records ogen itself as a tool dependency in that go.mod, so the generator version is pinned beside
your own. Its configuration has no version option.
oapi-codegen works the same way from package and output in its configuration file, and its
README shows the same go get -tool pinning. Its runtime module, github.com/oapi-codegen/runtime,
is a second version your go.mod tracks. With either tool, check-releases.mjs is what enforces
the rule across languages. Both beat sdkgen when Go is the SDK that matters and its module already
releases with the service, because no template copy sits between your go.mod and your tag.
Check it worked
The test suite reads the committed generations and the release history, and covers the Python-only break that forces a Go major under lockstep and a misspelled change level that must not pass.
node --test versions.test.mjs
1..12
# tests 12
# suites 0
# pass 12
# fail 0
# cancelled 0
# skipped 0
# todo 0
When it goes wrong
The Go tag stays at the scaffold version. You set go to 2.0.0 and ran npm run generate, and
TypeScript and Python moved while Go did not. The scaffold copied go/VERSION into .sdk/tm/go
with the version filled in, and generate reuses that copy.
node versions.mjs generated/sdkgen/stale
generated/sdkgen/stale
ts package.json 1.3.0 sdk reports 1.3.0 tag ts/v1.3.0
py pyproject.toml 1.3.1 sdk reports 1.3.1 tag py/v1.3.1
go VERSION 0.0.1 sdk reports 2.0.0 tag go/v0.0.1 module github.com/voxgig-sdk/bookshelf-sdk/go
3 problem(s)
go: VERSION says 0.0.1, the SDK reports 2.0.0
go: the Makefile tags go/v0.0.1, the SDK reports 2.0.0
go: version 2.0.0 needs a module path ending in /v2
The generate printed one warning, and it names the fix:
WARN: model/sdkgen generate-copies target go: 1 file(s) in .sdk are unchanged copies, but @voxgig/sdkgen 4.44.3 has changed since they were copied, so this run generates from older templates. Run `npx voxgig-sdkgen package update @voxgig/sdkgen --no-fetch` to refresh them.
Run that refresh after every version change, then generate. A hand edit to go/VERSION does not
survive the next generate.
The third problem in that output is a Go major without its suffix. The Go modules reference
requires /v2 in the path of any v2 module, so a go/v2.0.0 tag on a path without it is not a
valid version of that module. Add the module: path: line.
A release candidate stops the check with not a MAJOR.MINOR.PATCH version. That is deliberate:
npm writes 1.4.0-rc.1 and PyPI normalizes it to 1.4.0rc1, so extend parseVersion with each
registry’s spelling before you rely on it.
When not to do this
Do not hold strict lockstep when one language breaks more often than the others. Every Python break becomes a Go major, a fresh import path for every Go caller, for a change none of them can see.
Do not reach for sdkgen’s per-target versions when each language lives in its own repository with
its own release owner. The overlay assumes one repository and one generate. Speakeasy’s version per
language in gen.yaml, moved per target with speakeasy bump major -t typescript, fits that shape better.
Do not adopt a generator for versioning alone. If Go is your only SDK, ogen or oapi-codegen inside
the service’s own module is less to run than any multi-language tool, and the module’s tags already
are the policy.
Do not let the policy and the check disagree. If the text says minor-lockstep and CI runs
independent, the check passes while the promise breaks.
Related how-tos
Last verified
Verified 2026-11-21 against Node 22.23.5, @voxgig/create-sdkgen 0.31.9, @voxgig/sdkgen 4.44.3,
@voxgig/apidef 8.32.4, ogen v1.25.0 and oapi-codegen v2.8.2, with Go 1.24.7 switching to the
toolchain those two require. Every output block is what the command preceding it printed. The
generations ran once, in generate.sh, and their files are committed under generated/.
@voxgig/sdkgen 4.45.0 was run on the stale case too: it left go/VERSION at 0.0.1 with the same
warning until the refresh, and added no /v2 suffix. Speakeasy was not run, and its version per
language in gen.yaml is read from its documentation.
Footnotes
-
Python has a version segment of its own for small corrections. PEP 440 permits post-releases,
1.4.0.post1, for minor errors that do not affect the distributed software, such as the release notes. It strongly discourages them for maintenance releases with actual bug fixes. A wheel missingpy.typedchanges what is distributed, so it is a patch, which is outside what the post-release segment is for. ↩︎ Back to text -
The Go modules reference gives the reason as the import compatibility rule. If an old package and a new package share an import path, the new package must be backwards compatible with the old one. A major version is therefore a different module path, and the reference says modules with distinct suffixes are treated as separate modules. Speakeasy’s versioning page downgrades a detected Go major to a minor unless the bump is forced. That keeps Go users on one path, at the price of moving the Go number away from the others. ↩︎ Back to text