soxom.yaml Reference

Complete reference for all soxom.yaml configuration options.

Top-Level Structure

version: "1.0"           # Required
sdk: {}                  # Required
spec: {}                 # Required
targets: []              # Required
resources: {}            # Optional
pagination: {}           # Optional
authentication: {}       # Optional
retries: {}              # Optional
timeouts: {}             # Optional
streaming: {}            # Optional

---

version

Configuration file version.

Property	Type	Required	Default
version	string	Yes	-

version: "1.0"

---

sdk

SDK package metadata.

Property	Type	Required	Default	Description
name	string	Yes	-	Package base name
version	string	Yes	-	Semantic version
description	string	No	-	Package description

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

---

spec

OpenAPI specification source.

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

*Either path or origin required.

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

---

targets

Target languages for SDK generation.

Simple List

targets:
  - typescript
  - python
  - go
  - java

With Configuration

TypeScript

Property	Type	Default	Description
package_name	string	kebab-case of sdk.name	npm package name. Use a scoped name (e.g. @acme/sdk) for organization-scoped packages.
module_format	string	esm	esm or cjs. Controls the package.json#type field and which conditional exports are emitted.
generator_version	string	latest	Pinned generator version (e.g. "0.1.0").

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

Python

Property	Type	Default	Description
package_name	string	sdk.name	PyPI package name
min_version	string	"3.8"	Minimum Python version

targets:
  python:
    package_name: acme-sdk
    min_version: "3.9"

Go

Property	Type	Default	Description
module	string	-	Go module path

targets:
  go:
    module: github.com/acme/sdk-go

Java

Property	Type	Default	Description
group_id	string	com.example	Maven group ID
artifact_id	string	sdk.name	Maven artifact ID

targets:
  java:
    group_id: com.acme
    artifact_id: acme-sdk

C#

Property	Type	Default	Description
package_id	string	PascalCase form of sdk.name	NuGet package ID
root_namespace	string	same as package_id	Root C# namespace
target_frameworks	string[]	[netstandard2.0, net8.0, net9.0]	Target framework monikers
generator_version	string	latest	Pinned generator version

targets:
  csharp:
    package_id: Acme.Sdk
    root_namespace: Acme.Sdk
    target_frameworks: [netstandard2.0, net8.0, net9.0]
    generator_version: "0.1.0"

---

resources

SDK structure and method mapping.

Property	Type	Description
$client	object	Methods on client root
<name>	object	Resource namespace

Resource Object

Property	Type	Description
methods	object	Method name → operation mapping
models	array	Associated schema names
subresources	object	Nested resources

resources:
  $client:
    methods:
      health: get /health

  users:
    models:
      - User
      - UserCreate
    methods:
      list: get /users
      create: post /users
      get: get /users/{id}
      update: put /users/{id}
      delete: delete /users/{id}
    subresources:
      settings:
        methods:
          get: get /users/{id}/settings
          update: put /users/{id}/settings

---

pagination

Pagination configuration.

Property	Type	Default	Description
default_type	string	cursor	cursor or offset
schemes	object	-	Pagination scheme definitions

Cursor Scheme

pagination:
  default_type: cursor
  schemes:
    cursor:
      cursor:
        request_param: after
        response_property: next_cursor
      limit:
        request_param: limit
        default: 20
        max: 100
      has_more:
        response_property: has_more

Property	Type	Description
cursor.request_param	string	Query parameter name
cursor.response_property	string	Response field with next cursor
limit.request_param	string	Limit query parameter
limit.default	integer	Default page size
limit.max	integer	Maximum page size
has_more.response_property	string	Boolean field for more pages

Offset Scheme

pagination:
  schemes:
    offset:
      offset:
        request_param: offset
      limit:
        request_param: limit
        default: 20
      total:
        response_property: total

---

authentication

Authentication configuration.

Property	Type	Default	Description
default	string	-	Default auth method
env_vars	object	-	Environment variable mappings
oauth2	object	-	OAuth 2.0 specific settings

authentication:
  default: bearer

  env_vars:
    bearer:
      token: ACME_API_TOKEN
    api_key:
      key: ACME_API_KEY
    basic:
      username: ACME_USERNAME
      password: ACME_PASSWORD
    oauth2:
      client_id: ACME_CLIENT_ID
      client_secret: ACME_CLIENT_SECRET

  oauth2:
    token_url: https://api.example.com/oauth/token
    auto_refresh: true
    default_scopes:
      - read
      - write

---

retries

Retry configuration.

Property	Type	Default	Description
enabled	boolean	true	Enable retries
max_attempts	integer	3	Maximum retry attempts
backoff	object	-	Backoff settings
retry_on	array	See below	Status codes to retry
retry_connection_errors	boolean	true	Retry on connection errors
respect_retry_after	boolean	true	Honor Retry-After header

Backoff Settings

Property	Type	Default	Description
initial_interval_ms	integer	500	Initial delay
max_interval_ms	integer	30000	Maximum delay
multiplier	number	2.0	Exponential multiplier
jitter	number	0.25	Randomization factor

Default Retry Codes

retry_on:
  - 408  # Request Timeout
  - 429  # Too Many Requests
  - 500  # Internal Server Error
  - 502  # Bad Gateway
  - 503  # Service Unavailable
  - 504  # Gateway Timeout

retries:
  enabled: true
  max_attempts: 3
  backoff:
    initial_interval_ms: 500
    max_interval_ms: 30000
    multiplier: 2.0
    jitter: 0.25
  retry_on:
    - 429
    - 500
    - 502
    - 503
    - 504
  retry_connection_errors: true
  respect_retry_after: true

---

timeouts

Timeout configuration.

Property	Type	Default	Description
default_ms	integer	60000	Total request timeout
connect_ms	integer	10000	Connection timeout
read_ms	integer	30000	Read timeout
operations	object	-	Per-operation overrides

timeouts:
  default_ms: 60000
  connect_ms: 10000
  read_ms: 30000

  operations:
    batch_process:
      default_ms: 300000
    reports_generate:
      default_ms: 120000
    upload_file:
      default_ms: 600000

---

streaming

Streaming configuration.

Property	Type	Default	Description
sse.enabled	boolean	true	Enable SSE support
sse.sentinel_events	array	["[DONE]"]	Events to filter out

streaming:
  sse:
    enabled: true
    sentinel_events:
      - "[DONE]"
      - "END"

---

Complete Example

version: "1.0"

sdk:
  name: acme-sdk
  version: 1.0.0
  description: SDK for Acme API

spec:
  path: ./openapi.yaml

targets:
  typescript:
    package_name: "@acme/sdk"
    module_format: esm
  python:
    package_name: acme-sdk
    min_version: "3.9"
  go:
    module: github.com/acme/sdk-go
  java:
    group_id: com.acme
    artifact_id: acme-sdk
  csharp:
    package_id: Acme.Sdk
    root_namespace: Acme.Sdk
    target_frameworks: [netstandard2.0, net8.0, net9.0]

resources:
  $client:
    methods:
      health: get /health
  users:
    models: [User, UserCreate]
    methods:
      list: get /users
      create: post /users
      get: get /users/{id}

pagination:
  default_type: cursor
  schemes:
    cursor:
      cursor:
        request_param: after
        response_property: next_cursor
      limit:
        request_param: limit
        default: 20
        max: 100
      has_more:
        response_property: has_more

authentication:
  default: bearer
  env_vars:
    bearer:
      token: ACME_API_TOKEN

retries:
  enabled: true
  max_attempts: 3

timeouts:
  default_ms: 60000

streaming:
  sse:
    enabled: true