Full Configuration

A complete soxom.yaml configuration file with every option explained.

Complete Example

# =============================================================================
# SOXOM CONFIGURATION
# Complete example with all available options
# =============================================================================

# Configuration version (required)
# Always "1.0" for current Soxom version
version: "1.0"

# =============================================================================
# SDK METADATA
# Package identity used across all generated SDKs
# =============================================================================
sdk:
  # Base package name (required)
  # Transformed per-language: my-sdk → my_sdk (Python), mysdk (Go)
  name: acme-platform-sdk

  # Semantic version (required)
  # Used in package.json, pyproject.toml, pom.xml, go.mod
  version: 2.1.0

  # Package description (optional)
  # Appears in package registry listings
  description: |
    Official SDK for the Acme Platform API.
    Provides access to users, orders, products, and payments.

# =============================================================================
# OPENAPI SPECIFICATION SOURCE
# =============================================================================
spec:
  # Local path to OpenAPI spec (required if no origin)
  # Relative to soxom.yaml location
  path: ./api/openapi.yaml

  # Remote URL for spec (optional)
  # Used with --refresh flag to re-download
  origin: https://api.acme.com/v2/openapi.yaml

# =============================================================================
# TARGET LANGUAGES
# Which SDKs to generate and language-specific settings
# =============================================================================
targets:
  # TypeScript/JavaScript
  typescript:
    # npm package name (default: sdk.name)
    # Supports scoped packages: @org/package
    package_name: "@acme/platform-sdk"

    # Module format (default: esm)
    # Options: esm (recommended), cjs
    module_format: esm

  # Python
  python:
    # PyPI package name (default: sdk.name with underscores)
    package_name: acme-platform-sdk

    # Minimum Python version (default: "3.8")
    # Affects type hint syntax and features
    min_version: "3.9"

  # Go
  go:
    # Go module path (required for Go)
    # Used in go.mod and import statements
    module: github.com/acme/platform-sdk-go

  # Java
  java:
    # Maven group ID (default: com.example)
    group_id: com.acme.platform

    # Maven artifact ID (default: sdk.name)
    artifact_id: platform-sdk

# =============================================================================
# RESOURCE GROUPING
# Define SDK structure and method mappings
# =============================================================================
resources:
  # $client: Methods directly on the client object
  # Usage: client.health(), client.version()
  $client:
    methods:
      health: get /health
      version: get /version

  # Resource namespace with full configuration
  users:
    # Associated models (for documentation/IDE hints)
    models:
      - User
      - UserCreate
      - UserUpdate
      - UserSettings

    # Method mappings: name → "HTTP_METHOD /path"
    methods:
      list: get /users
      create: post /users
      get: get /users/{user_id}
      update: put /users/{user_id}
      delete: delete /users/{user_id}
      search: post /users/search

    # Nested subresources
    # Usage: client.users.settings.get("user-123")
    subresources:
      settings:
        models:
          - UserSettings
        methods:
          get: get /users/{user_id}/settings
          update: put /users/{user_id}/settings

      preferences:
        methods:
          get: get /users/{user_id}/preferences
          update: put /users/{user_id}/preferences

  # Orders with custom method names
  orders:
    models:
      - Order
      - OrderCreate
      - OrderItem
    methods:
      list: get /orders
      create: post /orders
      get: get /orders/{order_id}
      # Custom action methods
      cancel: post /orders/{order_id}/cancel
      refund: post /orders/{order_id}/refund

  # Products
  products:
    models:
      - Product
      - ProductCreate
    methods:
      list: get /products
      create: post /products
      get: get /products/{product_id}
      update: put /products/{product_id}
      delete: delete /products/{product_id}

  # Payments with union types
  payments:
    models:
      - Payment
      - PaymentCreate
      - PaymentMethod
      - CreditCard
      - BankAccount
    methods:
      list: get /payments
      create: post /payments
      get: get /payments/{payment_id}

  # Chat with streaming
  chat:
    subresources:
      completions:
        models:
          - ChatCompletion
          - ChatCompletionChunk
          - ChatMessage
        methods:
          create: post /chat/completions

  # Reports (long-running operations)
  reports:
    models:
      - Report
      - ReportRequest
    methods:
      generate: post /reports/generate
      get: get /reports/{report_id}

  # Batch operations
  batch:
    methods:
      process: post /batch/process

# =============================================================================
# PAGINATION
# Configure auto-pagination behavior
# =============================================================================
pagination:
  # Default pagination type for list endpoints
  # Options: cursor, offset
  default_type: cursor

  # Pagination scheme definitions
  schemes:
    # Cursor-based pagination (recommended)
    cursor:
      # Cursor parameter configuration
      cursor:
        # Query parameter name for cursor
        request_param: after
        # Response field containing next cursor
        # Can use JSONPath: data[-1].id for ID-based
        response_property: next_cursor

      # Limit/page size configuration
      limit:
        request_param: limit
        default: 20        # Default page size
        max: 100           # Maximum allowed

      # Has more indicator
      has_more:
        response_property: has_more

    # Offset-based pagination
    offset:
      offset:
        request_param: offset
      limit:
        request_param: limit
        default: 20
      # Total count (for calculating pages)
      total:
        response_property: total

# =============================================================================
# AUTHENTICATION
# Configure SDK authentication methods
# =============================================================================
authentication:
  # Default authentication method
  # Options: bearer, api_key, basic, oauth2
  default: bearer

  # Environment variable mappings
  # SDK reads credentials from these env vars automatically
  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

  # OAuth 2.0 specific configuration
  oauth2:
    # Token endpoint (if not in OpenAPI spec)
    token_url: https://api.acme.com/oauth/token

    # Automatic token refresh (default: true)
    auto_refresh: true

    # Default scopes for requests
    default_scopes:
      - read
      - write

# =============================================================================
# RETRIES
# Automatic retry configuration
# =============================================================================
retries:
  # Enable/disable retries globally (default: true)
  enabled: true

  # Maximum retry attempts (default: 3)
  max_attempts: 3

  # Exponential backoff configuration
  backoff:
    # Initial delay before first retry (default: 500ms)
    initial_interval_ms: 500

    # Maximum delay cap (default: 30000ms)
    max_interval_ms: 30000

    # Exponential multiplier (default: 2.0)
    # delay = initial * (multiplier ^ attempt)
    multiplier: 2.0

    # Randomization factor (default: 0.25)
    # Adds ±25% jitter to prevent thundering herd
    jitter: 0.25

  # HTTP status codes that trigger retry
  retry_on:
    - 408  # Request Timeout
    - 429  # Too Many Requests
    - 500  # Internal Server Error
    - 502  # Bad Gateway
    - 503  # Service Unavailable
    - 504  # Gateway Timeout

  # Retry on connection errors (default: true)
  retry_connection_errors: true

  # Respect Retry-After header (default: true)
  # If server sends Retry-After, use that instead of backoff
  respect_retry_after: true

# =============================================================================
# TIMEOUTS
# Request timeout configuration
# =============================================================================
timeouts:
  # Default total request timeout (default: 60000ms)
  default_ms: 60000

  # Connection establishment timeout (default: 10000ms)
  connect_ms: 10000

  # Time to first byte (default: 30000ms)
  read_ms: 30000

  # Per-operation timeout overrides
  # Use operation name from resources: {resource}_{method}
  operations:
    batch_process:
      default_ms: 300000      # 5 minutes
    reports_generate:
      default_ms: 120000      # 2 minutes
    chat_completions_create:
      default_ms: 300000      # 5 minutes for AI
    files_upload:
      default_ms: 600000      # 10 minutes

# =============================================================================
# STREAMING
# Server-Sent Events configuration
# =============================================================================
streaming:
  sse:
    # Enable SSE support (default: true when text/event-stream in spec)
    enabled: true

    # Sentinel events to filter out
    # These terminate the stream but shouldn't be passed to user
    sentinel_events:
      - "[DONE]"
      - "END"
      - "DONE"

When to Use Each Option

Option	Use When
sdk.description	Publishing to package registries
spec.origin	Spec is hosted remotely, want auto-refresh
targets.<lang>.package_name	Custom package naming conventions
resources.$client	API has top-level utility endpoints
resources.*.subresources	API has hierarchical resource relationships
pagination.schemes.offset	API uses traditional offset pagination
authentication.oauth2	API uses OAuth 2.0 flows
retries.enabled: false	Testing or when server handles retries
timeouts.operations.*	Specific endpoints need more time
streaming.sse.sentinel_events	API sends termination markers

Minimal vs Full

Minimal Configuration

version: "1.0"
sdk:
  name: my-sdk
  version: 1.0.0
spec:
  path: ./openapi.yaml
targets:
  - typescript

Recommended Configuration

version: "1.0"
sdk:
  name: my-sdk
  version: 1.0.0
  description: SDK for My API
spec:
  path: ./openapi.yaml
targets:
  - typescript
  - python
resources:
  # Map your resources here
authentication:
  default: bearer
  env_vars:
    bearer:
      token: MY_API_TOKEN
retries:
  enabled: true
  max_attempts: 3

Use the full configuration when you need fine-grained control over SDK behavior.