SDK Versioning

This page covers the hosted CodeForge engine only — how the platform decides the npm version of the SDK it publishes for you, not the OSS The Codegen Project CLI.

OpenAPI requires every document to declare info.version, but does not require that value to be semver. CodeForge classifies your declared version and picks one of two modes accordingly.

Which mode your document is in

Your info.version is trimmed and checked:

• Document-versioned when it is valid semver (1.2.3, v1.2.3, 1.2.3-beta.1), or when it is version-shaped (1, 1.2, v1.2) and coerces cleanly to one. Your declared version drives the SDK's release type, as you'd expect.
• Platform-managed for everything else: an empty string, a missing value, a date (2025-12-08), a word (beta), a git sha, or anything else that isn't version-shaped. CodeForge assigns and bumps the SDK version itself. This is not an error — the check log carries a warning saying the version isn't usable and the platform is managing it for this document.

A document that doesn't parse at all — invalid YAML or JSON — still fails; the fallback covers unusable versions, not broken documents.

Platform-managed mode

The first run for a document in this mode publishes 0.1.0, with the document version left unset. Every run detail page shows this as Unversioned rather than a blank field.

After that first run, each check compares a content hash of your spec against the hash stored on the last run:

• Same content → no run. Nothing republishes just because a check happened.
• Different content, or no stored hash to compare against → a patch release.
• Your generation parameters changed → a major release, same as in document-versioned mode.
• The generator CLI was upgraded → the same upgrade-detection rule applies as in document-versioned mode.

When more than one of these applies at once, the highest release type wins.

If you later add a real semver info.version, your document switches to document-versioned mode from that run onward. If you remove or degrade it, the same content-hash rule switches you back. Either way, your SDK's npm version only ever moves forward — it always continues from the last published version, so a document version that looks "lower" than a past one can never move the published SDK version backward.

Document-versioned mode

This is the mode most documents are already in, and it works as you'd expect: a semver diff between your document's current and previous version decides the release type (patch, minor, major), on top of the same generation-parameter and generator-upgrade rules described above.

One addition: if your declared version is unchanged between two runs but your spec's content changed anyway, and a content hash was recorded on the last run, CodeForge still issues a patch release. A run with no stored hash from before this behavior shipped keeps the old rule exactly — publishing your first hash-covered run does not trigger a one-time republish across every existing SDK.

What this does not cover

• Preview version parity. Generation previews still don't know the exact version your next publish will use — this only makes preview stop erroring for documents that were unusable before. The publish path still assigns the real version.
• A user-chosen fallback version. There's no setting to pick where the platform-managed sequence starts or how it increments — it is always 0.1.0, then patch-per-change.