Skip to content
Soxom

Configuration Overview

The soxom.yaml file is the central configuration for Soxom SDK generation. It controls everything from SDK metadata to feature configuration.

File Location

Section titled “File Location”

soxom.yaml lives at the root of your Config Repository and is picked up automatically on every build. The path is fixed — Soxom does not search subdirectories or accept an alternate location.

Basic Structure

Section titled “Basic Structure”
# Required: Configuration version
version: "1.0"


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


# OpenAPI source
spec:
  path: ./openapi.yaml


# Target languages
targets:
  - typescript
  - python
  - go
  - java


# SDK structure
resources: {}


# Feature configuration
pagination: {}
authentication: {}
retries: {}
timeouts: {}
streaming: {}

Full Annotated Example

Section titled “Full Annotated Example”
version: "1.0"


# SDK metadata - defines package identity
sdk:
  name: acme-sdk                    # Package name
  version: 1.0.0                    # Semantic version
  description: SDK for Acme API     # Package description


# OpenAPI specification source
spec:
  path: ./openapi.yaml              # Local path to spec
  # origin: https://api.example.com/openapi.yaml  # Or remote URL


# Target languages with language-specific config
targets:
  typescript:
    package_name: "@acme/sdk"       # npm package name
    module_format: esm              # esm or cjs


  python:
    package_name: acme-sdk          # PyPI package name
    min_version: "3.9"              # Minimum Python version


  go:
    module: github.com/acme/sdk-go  # Go module path


  java:
    group_id: com.acme              # Maven group ID
    artifact_id: acme-sdk           # Maven artifact ID


# Resource grouping and SDK structure
resources:
  $client:                          # Methods on client root
    methods:
      health: get /health


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


# Pagination configuration
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 configuration
authentication:
  default: bearer
  env_vars:
    bearer:
      token: ACME_API_TOKEN


# Retry configuration
retries:
  enabled: true
  max_attempts: 3
  backoff:
    initial_interval_ms: 500
    max_interval_ms: 30000
    multiplier: 2.0
    jitter: 0.25
  retry_on:
    - 408
    - 429
    - 500
    - 502
    - 503
    - 504


# Timeout configuration
timeouts:
  default_ms: 60000
  connect_ms: 10000
  read_ms: 30000


# Streaming configuration
streaming:
  sse:
    enabled: true
    sentinel_events:
      - "[DONE]"

Configuration Sections

Section titled “Configuration Sections”
SectionRequiredDescription
versionYesConfiguration file version (always "1.0")
sdkYesSDK package metadata
specYesOpenAPI specification source
targetsYesTarget languages to generate
resourcesNoSDK resource structure
paginationNoPagination configuration
authenticationNoAuth configuration
retriesNoRetry behavior
timeoutsNoRequest timeouts
streamingNoSSE streaming settings

Configuration Hierarchy

Section titled “Configuration Hierarchy”

Soxom uses a layered configuration system:

  1. Global defaults - Set in soxom.yaml root sections
  2. Per-operation - Override using OpenAPI x-soxom-* extensions
  3. Runtime - Override when calling SDK methods

Validation

Section titled “Validation”

Validation runs automatically on every build — both soxom.yaml and the referenced OpenAPI spec are checked, and any errors surface in the Builds view of the dashboard. To preview validation before merging, push to a branch of the Config Repository: Soxom creates a preview build for it.

Next Steps

Section titled “Next Steps”