Skip to content
Soxom

Core Concepts

These are the nouns that appear throughout Soxom: in the dashboard, in your repositories, and in the rest of this documentation. Read this once and the rest of the docs will make a lot more sense.

Organization

Section titled “Organization”

The top-level container for everything you do in Soxom. An Organization holds members, billing, and one or more Projects. When you sign up you’re placed in your own Organization; teams typically share one.

Project

Section titled “Project”

A Project represents a single API and the SDKs generated from it. Each Project owns one Config Repository and zero or more SDK Targets. If you have two distinct APIs, you’ll have two Projects.

Config Repository

Section titled “Config Repository”

The GitHub repository you own that holds openapi.yaml and soxom.yaml. Soxom watches it for pushes and treats it as the source of truth for what your SDKs should look like.

  • Created by Soxom on your behalf when you create a Project, pre-populated with starter files.
  • Lives under the GitHub account or org you connected via the Soxom GitHub App.
  • A push to main triggers a build for every SDK Target in the Project. Pushes to other branches trigger builds on matching codegen/<branch> branches in each Staging Repository.

See the Config Repository workflow for the full lifecycle.

SDK Target

Section titled “SDK Target”

A single output of a Project: TypeScript, Python, Java, or Go (preview). A Project can have multiple SDK Targets — typically one per language you want to publish.

Each SDK Target has its own Staging Repository and Production Repository.

Staging Repository

Section titled “Staging Repository”

A Soxom-managed GitHub repository, one per SDK Target, where generated SDK code lives while it’s being prepared for release. You can read it, fork it, run CI against it, and write hand-maintained extensions to it, but Soxom owns its branch structure:

  • codegen/next — raw generator output for the Config Repository’s main branch. Soxom force-updates this branch on every build.
  • codegen/<branch> — raw output for non-main branches of the Config Repository, useful for previewing changes.
  • extended/next — generator output plus any hand-written extensions you maintain in the repo.
  • next — the final merged state, ready for staging release.
  • main — the latest staging release. Soxom opens a staging-release PR from next into main.

See the Staging Repository workflow for details.

Production Repository

Section titled “Production Repository”

A Soxom-managed GitHub repository, one per SDK Target, that holds the code your users actually consume. Tagged releases are cut here, and (optionally) published to npm, PyPI, Maven Central, or other registries.

The Production Repository tracks the Staging Repository’s main branch. Soxom opens a production-release PR each time the Staging Repository ships a new staging release.

See the Production Repository workflow for details.

Build

Section titled “Build”

A single execution of the generator pipeline for a Project. A Build is created every time you push to your Config Repository. It includes:

  • The Config Repository commit being built.
  • One run of the generator per enabled SDK Target.
  • The resulting commits on codegen/next (or codegen/<branch>) in each Staging Repository.

Builds appear on the Builds page in the dashboard with status, logs, and links to the produced commits.

See the Build workflow for more.

Staging Release

Section titled “Staging Release”

A versioned release of an SDK inside a Staging Repository, prepared as a PR from next into main. Soxom computes the new version from your Conventional Commit messages and assembles a changelog. Merging the PR creates the staging release and triggers a Production Release.

See the Staging Release workflow.

Production Release

Section titled “Production Release”

The user-facing release of an SDK. Cut as a PR in the Production Repository, derived from the most recent Staging Release. Merging the production-release PR:

  • Creates a git tag on the Production Repository.
  • Optionally publishes the package to a registry (if you’ve configured credentials).

See the Production Release workflow.

How they relate

Section titled “How they relate”
Organization
└── Project
    ├── Config Repository  (you own: openapi.yaml + soxom.yaml)
    └── SDK Target (one per language)
        ├── Staging Repository  (Soxom-managed)
        │   └── Staging Release  (PR from next → main)
        └── Production Repository  (Soxom-managed)
            └── Production Release  (tagged, published)

A push to the Config Repository produces a Build, which updates each Staging Repository. From there, merging a Staging Release leads to a Production Release.

Resources, methods, and the OpenAPI shape

Section titled “Resources, methods, and the OpenAPI shape”

Inside soxom.yaml you also describe how your API’s operations should be grouped into client methods. These are SDK-shaping concepts rather than platform concepts:

  • Resources group operations into namespaces like client.users.list().
  • Methods map OpenAPI operations onto SDK method names (list, get, create, …).
  • OpenAPI extensions (x-soxom-*) let you override pagination, retries, timeouts, or streaming on a per-operation basis.
resources:
  users:
    models: [User, UserCreate]
    methods:
      list: get /users
      create: post /users
      get: get /users/{id}

See the Resources reference and OpenAPI extensions reference for the full surface.

Next steps

Section titled “Next steps”