Your Bookshelf SDK is on npm as @acme/bookshelf, on PyPI as bookshelf, and at
github.com/acme/bookshelf-go/v2, all from OpenAPI Generator. The replacement generator’s first
run publishes as @voxgig-sdk/bookshelf-sdk, imports as bookshelf_sdk, and exports no
DefaultApi. Every caller who upgrades gets an import error, although the version number promised a
compatible release.
What you get
You will end up with the replacement SDK under your published names, a per-language diff of the public surface, and a compatibility layer for the calls users make. This is for you if your users install an SDK you generate.
Short answer
Generate the replacement on a branch under the registry names you already publish: sdkgen sets
them per target in the project model, openapi-python-client takes name overrides, and orval
writes into your own package.json. Then list the old and new exports and compare. Shim the names
callers use, ship the rest as a major, and check the import path too, because sdkgen keeps a
Python import name of its own.
You will need
Node 22 or later, Python 3.12 or later, an SDK already published from OpenAPI Generator output,
and the OpenAPI document it came from. The sample’s api.json is the five-operation Bookshelf
document. generate.sh builds the published SDK with OpenAPI Generator, then the candidates, and
commits a surface listing for each, so the commands below run offline.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| A compatibility shim | Callers use a few operations, and you can carry two naming schemes for one major | Two names per operation until it is deleted, and old options it must refuse | Callers import the old runtime’s helpers |
openapi-python-client | A Python SDK whose distribution and import name must both stay | One module of functions per operation, so DefaultApi and ApiClient are gone | You also publish TypeScript or Go from the document |
| orval | A TypeScript SDK whose package.json you keep and own | Functions in one file, so DefaultApi, Configuration and the model helpers are gone | Callers construct API classes |
| sdkgen | TypeScript, Python and Go from one model, with each registry name set there | A Python import name fixed at <name>_sdk, and entity calls in place of DefaultApi | Python callers must keep their import line with no shim |
Voxgig maintains sdkgen, which this page runs alongside two other generators and does not recommend over them.
openapi-python-client keeps both Python names through configuration, where sdkgen needs a shim
package for the import name. orval keeps the npm name because it writes no package.json, and
that same choice leaves the versioning to you. All three change nearly every exported name.
Keep the published names in the model
sdkgen derives a name per registry from the project: @voxgig-sdk/bookshelf-sdk,
voxgig-sdk-bookshelf-sdk, and github.com/voxgig-sdk/bookshelf-sdk/go. The
model reference lists
publish.registry.package, module.path and module.package per target, and generate.sh
appends these lines to .sdk/model/project.aontu before it generates again.
# Publish under the names the OpenAPI Generator packages used. A Go module at v3 or above
# needs the major version at the end of its path, so the Go import path moves from /v2 to /v3.
main: kit: target: ts: publish: registry: package: '@acme/bookshelf'
main: kit: target: py: publish: registry: package: 'bookshelf'
main: kit: target: go: module: path: 'github.com/acme/bookshelf-go/v3'
main: kit: target: go: module: package: 'bookshelf'
main: kit: target: &: publish: version: '3.0.0'
The Go line is not optional. The Go modules reference requires a module at major version 2 or higher to end its path with that suffix, so a Go major is an import-path change by rule.
Diff the public surface
tools/list-surface.mjs reads a TypeScript entry through the TypeScript compiler API and a Go
module’s root package from source. tools/list_surface.py reads a Python package’s __init__.py
with ast. diff-surface.mjs compares each listing with the published one.
API Extractor is built to flag a pull request that changes a
TypeScript package’s API contract, which suits a team that wants this check in CI.
node diff-surface.mjs
TypeScript: @acme/bookshelf 2.3.0 from OpenAPI Generator
sdkgen, derived names package @voxgig-sdk/bookshelf-sdk (changed)
old exports kept: 1 of 53
sdkgen, names kept package @acme/bookshelf
old exports kept: 1 of 53
sdkgen, names kept, compat/ package @acme/bookshelf
old exports kept: 12 of 53, 13 methods gone, 5 signatures changed
orval, same package.json package @acme/bookshelf
old exports kept: 1 of 53
Python: bookshelf 2.3.0, import bookshelf, from OpenAPI Generator
sdkgen, derived names distribution voxgig-sdk-bookshelf-sdk (changed), import bookshelf_sdk (changed)
old exports kept: 0 of 11
sdkgen, names kept distribution bookshelf, import bookshelf_sdk (changed)
old exports kept: 0 of 11
sdkgen, names kept, py-compat/ distribution bookshelf, import bookshelf
old exports kept: 0 of 11
openapi-python-client, overrides distribution bookshelf, import bookshelf
old exports kept: 0 of 11
Go: github.com/acme/bookshelf-go/v2, package bookshelf, from OpenAPI Generator
sdkgen, derived names module github.com/voxgig-sdk/bookshelf-sdk/go (changed), package voxgigbookshelfsdk (changed)
old exports kept: 0 of 51
sdkgen, names kept, /v3 path module github.com/acme/bookshelf-go/v3 (changed), package bookshelf
old exports kept: 0 of 51
still removed with compat/: 41 TypeScript names, among them ApiResponse, BaseAPI, BlobApiResponse, BookFromJSON
methods gone: DefaultApi.createBookRaw, DefaultApi.createBookRequestOpts, DefaultApi.deleteBookRaw and 10 more
signatures changed: DefaultApi.createBook, DefaultApi.deleteBook, DefaultApi.getBook, DefaultApi.listBooks, DefaultApi.updateBook
The model lines fixed every registry name. The Python import did not move: 16 components of the
py target write the package as <Name>_sdk, so pip install bookshelf installs a package that
import bookshelf cannot find.1 record-py-import.sh tried module.name, which the model
reference lists, in project.aontu, where it fails to unify with the target’s own value, and in
the target’s model file, where the package stays bookshelf_sdk. sdkgen 4.45.0 did the same, as
py-import-name.txt records.
The one TypeScript export all three candidates share is the Book model type. The diff also
reads each kept class’s methods: compat/ keeps the five operations but drops 13 helpers such
as listBooksRaw, and each operation lost the initOverrides parameter.
Decide each difference: shim or major
Removing an exported name is a breaking change under
semantic versioning, so the choice is per name. compat/
keeps the five operations, Configuration, and the three error classes on top of the sdkgen SDK,
and marks DefaultApi deprecated. An initOverrides argument it cannot honor is refused rather
than dropped. Its fetch hands the SDK a copy of each response, so the response on a ResponseError
is the one the API sent, still unread.
export class DefaultApi {
#sdk
constructor(configuration = new Configuration()) {
const fetch = observed(configuration.fetchApi)
this.#sdk = new BookshelfSDK({ base: configuration.basePath, system: { fetch } })
}
async listBooks(...rest) {
noOverrides(rest, 'listBooks')
return call(async () => (await this.#sdk.Book().list()).map((b) => b.data()))
}
run-old-caller.mjs runs code written against the published package, unchanged, against that
package and against the shim, each with a fresh stand-in for the API.
node run-old-caller.mjs
OpenAPI Generator 2.3.0
listBooks Emma
createBook b2 Persuasion
updateBook Persuasion, 2nd ed. (1817)
deleteBook done
getBook ResponseError, status 404
application/json {"error":"no book b2"}
requests GET /books, POST /books, PATCH /books/b2, DELETE /books/b2, GET /books/b2
sdkgen 3.0.0 with compat
listBooks Emma
createBook b2 Persuasion
updateBook Persuasion, 2nd ed. (1817)
deleteBook done
getBook ResponseError, status 404
application/json {"error":"no book b2"}
requests GET /books, POST /books, PATCH /books/b2, DELETE /books/b2, GET /books/b2
The 41 names the shim leaves out come from the generated runtime and model files, BaseAPI,
Middleware, and the BookFromJSON helpers among them. They decide the version, with the 13
methods and the five signatures. Keep them all and the release can be a minor, or drop them and
ship 3.0.0 with the shim as the migration path, as here.
Keep the Python import name with a shim package
py-compat/bookshelf/__init__.py re-exports the sdkgen client under the old import name and warns
once on import. It keeps the import line and nothing else of the old package.
python3 check_py_compat.py
import bookshelf -> bookshelf_sdk.BookshelfSDK
same class as bookshelf_sdk.BookshelfSDK: True
DeprecationWarning: import bookshelf_sdk instead of bookshelf; bookshelf is removed in 4.0.0
from bookshelf import DefaultApi -> ImportError
import bookshelf.api.default_api -> ModuleNotFoundError
from bookshelf.entity import book_entity -> ModuleNotFoundError
isinstance across the two names: True
pickled as: bookshelf_sdk.BookshelfSDK
Code written against OpenAPI Generator’s DefaultApi still fails, and so does a submodule import
under the old name. The shim serves callers who moved to BookshelfSDK and kept import bookshelf. The generated pyproject.toml packages bookshelf_sdk* only, so the shim needs adding
to its include line before it ships.
Keep the names with openapi-python-client and orval
openapi-python-client takes project_name_override and package_name_override from a
configuration file, as its
README documents, and both held.
orval writes the client into a path you choose and no package.json, which generate.sh checks,
so the name stays wherever your manifest says.
echo "[4/5] openapi-python-client 0.30.0, with the project and package names kept"
mkdir -p opc && printf 'project_name_override: bookshelf\npackage_name_override: bookshelf\n' > opc/config.yml
(cd opc && uvx --from openapi-python-client==0.30.0 openapi-python-client generate --path ../api.json --config config.yml --output-path out >/dev/null 2>&1)
list_py opc/out/pyproject.toml opc/out/bookshelf > "$S/opc-py.json"
(cd opc/out && find bookshelf -name '*.py' | LC_ALL=C sort) > "$S/opc-py-files.txt"
echo "[5/5] orval 8.48.0, fetch client, in the package.json the published SDK already has"
mkdir -p orval/src && cp oag/ts/package.json orval/package.json
(cd orval && npx --yes orval@8.48.0 --input ../api.json --output ./src/bookshelf.ts --client fetch >/dev/null 2>&1)
Neither keeps the old surface. openapi-python-client exports Client, AuthenticatedClient,
and a module per operation, as generated/surface/opc-py-files.txt lists, in place of OpenAPI
Generator’s eleven names. orval exports 26 names, listBooks among them, as a function that
resolves to { data, status, headers } rather than to the books, as generated/orval/bookshelf.ts
shows. A shim over either is the same work as compat/.
Check it worked
node --test migrate.test.mjs
1..17
# tests 17
# suites 0
# pass 17
# fail 0
# cancelled 0
# skipped 0
# todo 0
# duration_ms 1825.932696
The first test asserts the two preceding transcripts are equal, request for request. Others pin the
identities in the diff, the shim’s warning and its limits, and the include line. Four test
the errors the shim throws for a JSON body, a text body, an empty body, concurrent calls, and a
request with no response. Two feed compare a listing with no exports, a removed method, and a
changed signature, and one deletes a listing and expects the diff run to fail.
When it goes wrong
Callers upgrade and their middleware stops running. A shim that accepts
new Configuration({ middleware }) and ignores the option does that. compat/ refuses each
Configuration option and initOverrides argument it cannot honor with a TypeError, which
tests check, so the caller learns before any request goes out.
Callers catch ResponseError, and await err.response.json() throws. The sdkgen error keeps
the status, the headers and a JSON body, and has read the body already, so a shim that builds a
new Response from it loses a text body. Keep the response the transport returned, as compat/
does.
pip install succeeds and import bookshelf fails. The distribution kept its name and the
import did not. Ship py-compat/ inside the same distribution, or say in the release notes that
the import line changes.
Go users run go get -u and stay on 2.3.0. The
-u flag upgrades each module to its latest version, and the
/v3 path is a different module. Announce the new import path in the release notes.
When not to do this
Do not switch generators to fix a naming problem. A rename inside OpenAPI Generator, with a mapping or an overlay and a deprecated alias, can ship as a minor. A switch costs a major in Go by rule and in TypeScript by the diff.
Do not ship the switch as a minor on the strength of a passing old caller. The caller covers the names it uses, and the surface diff lists 41 it does not.
Pick openapi-python-client when the SDK you publish is Python only and the import line must not
change, which it does through configuration and sdkgen does not. Pick orval when your
TypeScript users already call functions and you want to keep owning the package manifest.
Related how-tos
Last verified
Verified 2026-11-21 against Node 22.23.5, Python 3.13.18, @voxgig/create-sdkgen 0.31.9,
@voxgig/sdkgen 4.44.3, @voxgig/apidef 8.32.4, OpenAPI Generator 7.27.0,
openapi-python-client 0.30.0, orval 8.48.0, and TypeScript 5.9.3. Every output block is what
the command preceding it printed. All four generators ran once, in generate.sh, and the
listings and the code the commands read are committed under generated/. sdkgen 4.45.0 ran once,
in record-py-import.sh, and wrote the same Python package name.
Footnotes
-
The Python Packaging User Guide keeps a page on the difference between a distribution package, the name
pipinstalls, and an import package, the name animportstatement finds. Its example is Pillow, which installs as Pillow and imports asPIL, for historical reasons. The same page warns against installing a PyPI packagefooon seeingimport foo, which may install an unintended, even malicious, package. ↩︎ Back to text