Generator versioning

Each language Soxom supports has its own independently versioned generator — for example, the Python generator is on its own semver track from the TypeScript or Java generator. The generator_version field under each target in soxom.yaml pins which version produces that SDK.

Why pin a version

Without pinning, a build picks up whatever generator version is currently “latest stable” for that language. This is convenient early on, but it means a spec-only change can quietly pull in generator-side changes: new lint rules, formatting tweaks, internal restructuring, or improved type inference. The diff in the resulting Staging Release will reflect both your spec change and the generator’s drift.

Pinning isolates those two axes. A spec-only change produces a spec-only diff. Generator upgrades happen on your schedule, with their own review.

Setting the version

Set generator_version per target. The value is a semver string.

targets:
  python:
    package_name: my_sdk
    generator_version: "0.3.0"

  typescript:
    package_name: "@acme/sdk"
    module_format: esm
    generator_version: "0.1.0"

  java:
    group_id: com.acme
    artifact_id: acme-sdk
    generator_version: "0.2.0"

Available versions for each language are shown in the dashboard’s SDK Target settings. Use those — versions change as generators are released, and hardcoded lists in documentation will go stale.

Omitting the field

If you leave generator_version off a target, Soxom tracks the latest stable generator for that language. This is fine while you are still iterating on the SDK shape, but it is risky for SDKs you have already published — your next spec change could ship alongside generator changes you did not intend.

For any SDK Target in production, pin a version.

Upgrading

To move to a newer generator, change the value in soxom.yaml and commit. The next build uses the new generator.

Review the resulting staging-release PR carefully. Generator upgrades can produce non-trivial diffs even with no spec change — that is the point of pinning, but it also means the diff is doing real work. Treat it like any other dependency bump.

Go generator Preview

The Go generator is currently on a 0.x track and stability is not yet guaranteed. Some features (notably streaming) may be incomplete, and minor versions can introduce breaking changes to the generated SDK shape.

If you depend on the Go output, pin a specific version rather than tracking latest. When you decide to upgrade, plan time for a full review of the resulting diff.