SDK Metadata

The sdk and spec sections define your SDK’s identity and source specification.

SDK Section

The sdk section defines package metadata used across all generated SDKs.

sdk:
  name: my-sdk
  version: 1.0.0
  description: SDK for My API

Properties

Property	Required	Type	Description
name	Yes	string	Base package name
version	Yes	string	Semantic version (e.g., 1.0.0)
description	No	string	Package description

Name Transformation

The sdk.name is transformed for each target language:

sdk.name	TypeScript	Python	Go	Java
my-sdk	my-sdk	my_sdk	mysdk	my-sdk
acme-api	acme-api	acme_api	acmeapi	acme-api

Note

You can override the package name per-language in the targets section.

Version

Use semantic versioning for your SDK version:

sdk:
  version: 1.2.3          # Standard
  version: 1.0.0-beta.1   # Pre-release
  version: 2.0.0-rc.1     # Release candidate

The version is used in:

• package.json for TypeScript
• pyproject.toml for Python
• go.mod for Go
• pom.xml for Java

Spec Section

The spec section defines where to find your OpenAPI specification.

spec:
  path: ./openapi.yaml

Properties

Property	Required	Type	Description
path	Yes*	string	Local path to OpenAPI spec
origin	No	string	Remote URL for spec

*Either path or origin must be provided.

Local Specification

Reference a local OpenAPI file:

spec:
  path: ./openapi.yaml           # YAML format
  # path: ./openapi.json         # JSON format
  # path: ./specs/api.yaml       # Subdirectory

Paths are relative to the soxom.yaml location.

Remote Specification

Fetch specification from a URL:

spec:
  origin: https://api.example.com/openapi.yaml

When using origin:

• Soxom fetches the spec at generation time
• Supports HTTP and HTTPS
• Supports YAML and JSON formats
• Caches locally for offline use

Combined Usage

Use both for local development with remote source of truth:

spec:
  path: ./openapi.yaml                           # Local cache
  origin: https://api.example.com/openapi.yaml   # Canonical source

When spec.origin is set, Soxom re-fetches the spec on every build, so the SDK always reflects the canonical source. No manual refresh step is needed — push to the Config Repository to build automatically, or trigger a build from the Builds view in the dashboard.

Supported Formats

Format	Extensions	Support
OpenAPI 3.1	.yaml, .yml, .json	Supported — see compatibility matrix for per-feature coverage
OpenAPI 3.0	.yaml, .yml, .json	Full
OpenAPI 2.0 (Swagger)	-	Not supported

Examples

Minimal Configuration

version: "1.0"

sdk:
  name: my-sdk
  version: 1.0.0

spec:
  path: ./openapi.yaml

targets:
  - typescript

Full Metadata

version: "1.0"

sdk:
  name: acme-platform-sdk
  version: 2.1.0
  description: |
    Official SDK for the Acme Platform API.
    Provides access to users, orders, and payments.

spec:
  path: ./api/openapi.yaml
  origin: https://api.acme.com/v2/openapi.yaml

targets:
  typescript:
    package_name: "@acme/platform-sdk"
  python:
    package_name: acme-platform-sdk

Next Steps

• Resources - Define SDK structure
• Targets - Language-specific settings