OpenAPI Extensions

Soxom uses custom OpenAPI extensions to configure SDK-specific behavior directly in your spec.

Extensions Overview

Extension	Location	Description
x-soxom-pagination	Operation	Configure pagination
x-soxom-retries	Operation	Override retry settings
x-soxom-timeout	Operation	Override timeout
x-soxom-streaming	Operation	Enable streaming
x-soxom-ignore	Operation, Schema	Exclude from generation

---

x-soxom-pagination

Configure pagination for list endpoints.

Location

Operation level (under paths./.get, etc.)

Schema

x-soxom-pagination:
  type: cursor | offset      # Required
  cursor: string             # JSONPath to cursor (cursor type)
  results: string            # JSONPath to results array
  has_more: string           # JSONPath to has_more boolean
  total: string              # JSONPath to total count (offset type)

JSONPath Syntax

Prefix	Meaning	Example
$request.	Request parameter	$request.after
$response.	Response field	$response.next_cursor

Cursor Pagination Example

paths:
  /users:
    get:
      operationId: listUsers
      x-soxom-pagination:
        type: cursor
        cursor: $request.after
        results: $response.data
        has_more: $response.has_more
      parameters:
        - name: after
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/User"
                  has_more:
                    type: boolean
                  next_cursor:
                    type: string

Offset Pagination Example

paths:
  /products:
    get:
      operationId: listProducts
      x-soxom-pagination:
        type: offset
        results: $response.data
        total: $response.total
      parameters:
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Product"
                  total:
                    type: integer

---

x-soxom-retries

Override retry configuration for specific operations.

Location

Operation level

Schema

x-soxom-retries:
  enabled: boolean           # Enable/disable retries
  max_attempts: integer      # Maximum retry attempts
  backoff:
    initial_interval_ms: integer
    max_interval_ms: integer
    multiplier: number
    jitter: number

Disable Retries Example

Use for non-idempotent operations:

paths:
  /payments:
    post:
      operationId: createPayment
      x-soxom-retries:
        enabled: false       # Don't retry payment creation
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PaymentCreate"
      responses:
        "201":
          description: Payment created

Custom Retry Config Example

paths:
  /batch/process:
    post:
      operationId: processBatch
      x-soxom-retries:
        max_attempts: 5
        backoff:
          initial_interval_ms: 1000
          max_interval_ms: 60000
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BatchRequest"

---

x-soxom-timeout

Override timeout for specific operations.

Location

Operation level

Schema

x-soxom-timeout: integer    # Timeout in milliseconds

Example

paths:
  /reports/generate:
    post:
      operationId: generateReport
      x-soxom-timeout: 120000    # 2 minutes
      summary: Generate a report
      responses:
        "202":
          description: Report generation started

  /batch/import:
    post:
      operationId: importBatch
      x-soxom-timeout: 300000    # 5 minutes
      summary: Import batch data

  /files/upload:
    post:
      operationId: uploadFile
      x-soxom-timeout: 600000    # 10 minutes
      summary: Upload a large file

---

x-soxom-streaming

Mark an operation as supporting streaming responses.

Location

Operation level

Schema

x-soxom-streaming:
  enabled: boolean           # Enable streaming
  format: sse | ndjson       # Stream format (default: sse)

Example

paths:
  /chat/completions:
    post:
      operationId: createChatCompletion
      x-soxom-streaming:
        enabled: true
        format: sse
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ChatRequest"
      responses:
        "200":
          description: Chat completion
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ChatCompletion"
            text/event-stream:
              schema:
                $ref: "#/components/schemas/ChatCompletionChunk"

Note: Streaming is automatically detected when text/event-stream is in response content types. Use x-soxom-streaming for explicit control.

---

x-soxom-ignore

Exclude operations or schemas from SDK generation.

Location

• Operation level
• Schema level (in components/schemas)

Schema

x-soxom-ignore: boolean     # true to exclude

Ignore Operation Example

paths:
  /internal/metrics:
    get:
      operationId: getMetrics
      x-soxom-ignore: true      # Not included in SDK
      summary: Internal metrics endpoint
      responses:
        "200":
          description: Metrics

  /debug/state:
    get:
      operationId: getDebugState
      x-soxom-ignore: true      # Not included in SDK
      summary: Debug state endpoint

Ignore Schema Example

components:
  schemas:
    InternalConfig:
      x-soxom-ignore: true      # Not generated as a type
      type: object
      properties:
        debug_mode:
          type: boolean

    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string

---

Complete Example

openapi: 3.1.0
info:
  title: Example API
  version: 1.0.0

paths:
  /users:
    get:
      operationId: listUsers
      x-soxom-pagination:
        type: cursor
        cursor: $request.after
        results: $response.data
        has_more: $response.has_more
      responses:
        "200":
          description: User list

  /payments:
    post:
      operationId: createPayment
      x-soxom-retries:
        enabled: false
      x-soxom-timeout: 30000
      responses:
        "201":
          description: Payment created

  /reports/generate:
    post:
      operationId: generateReport
      x-soxom-timeout: 120000
      x-soxom-retries:
        max_attempts: 2
      responses:
        "202":
          description: Report started

  /chat/completions:
    post:
      operationId: createCompletion
      x-soxom-streaming:
        enabled: true
      responses:
        "200":
          content:
            text/event-stream:
              schema:
                $ref: "#/components/schemas/CompletionChunk"

  /internal/debug:
    get:
      operationId: getDebug
      x-soxom-ignore: true
      responses:
        "200":
          description: Debug info

components:
  schemas:
    InternalState:
      x-soxom-ignore: true
      type: object

---

Precedence

When the same setting appears in multiple places:

1. OpenAPI extension (highest) - x-soxom-*
2. soxom.yaml operations - Per-operation config
3. soxom.yaml global - Global defaults
4. Built-in defaults (lowest)

Extensions always override soxom.yaml configuration.