Schema Overview

Soxom generates language-idiomatic types from your OpenAPI schemas, handling complex compositions and providing full type safety.

How It Works

OpenAPI Schema          Soxom               Generated Types
┌──────────────┐       ┌─────┐             ┌──────────────┐
│ components/  │──────▶│     │──────▶      │ TypeScript   │
│  schemas:    │       │     │             │  interfaces  │
│   User:      │       │     │             ├──────────────┤
│     type:    │       │     │──────▶      │ Python       │
│       object │       │     │             │  dataclasses │
│     props... │       │     │             ├──────────────┤
└──────────────┘       └─────┘──────▶      │ Go structs   │
                                           ├──────────────┤
                                           │ Java classes │
                                           └──────────────┘

Soxom parses each schema in components/schemas and generates:

• Type definitions
• Serialization/deserialization logic
• Validation where applicable
• Documentation from descriptions

Supported Schema Features

Feature	Support	Notes
Object types	Full	Generates classes/structs
Arrays	Full	Typed arrays/lists
Enums	Full	String and integer enums
oneOf	Full	Union types with discriminators
allOf	Full	Composition/intersection
anyOf	As oneOf	Treated as oneOf
$ref	Full	Reference resolution
nullable	Full	Optional/nullable types
Formats	Partial	date, date-time, uuid, etc.

Language Output

TypeScript

// From OpenAPI schema
interface User {
  id: string;
  email: string;
  name: string;
  status: UserStatus;
  createdAt: Date;
}

type UserStatus = 'active' | 'inactive' | 'suspended';

Python

# From OpenAPI schema
@dataclass
class User:
    id: str
    email: str
    name: str
    status: UserStatus
    created_at: datetime

class UserStatus(str, Enum):
    ACTIVE = "active"
    INACTIVE = "inactive"
    SUSPENDED = "suspended"

Go

// From OpenAPI schema
type User struct {
    ID        string     `json:"id"`
    Email     string     `json:"email"`
    Name      string     `json:"name"`
    Status    UserStatus `json:"status"`
    CreatedAt time.Time  `json:"created_at"`
}

type UserStatus string

const (
    UserStatusActive    UserStatus = "active"
    UserStatusInactive  UserStatus = "inactive"
    UserStatusSuspended UserStatus = "suspended"
)

Schema Composition

Soxom handles three OpenAPI composition keywords:

Keyword	Purpose	Soxom Behavior
oneOf	Union types	Generates discriminated unions
allOf	Composition	Flattens into single type
anyOf	Flexible union	Treated as oneOf

Tip

Use oneOf for unions and allOf for composition. Avoid anyOf when possible.

Naming Conventions

Soxom automatically transforms names for each language:

OpenAPI	TypeScript	Python	Go	Java
user_profile	userProfile	user_profile	UserProfile	userProfile
APIKey	apiKey	api_key	APIKey	apiKey
created_at	createdAt	created_at	CreatedAt	createdAt

See Naming for full details.

Type Mappings

Primitive Types

OpenAPI	TypeScript	Python	Go	Java
string	string	str	string	String
integer	number	int	int64	Long
number	number	float	float64	Double
boolean	boolean	bool	bool	Boolean

Format Types

Format	TypeScript	Python	Go	Java
date	string	date	time.Time	LocalDate
date-time	Date	datetime	time.Time	OffsetDateTime
uuid	string	UUID	string	UUID
binary	Blob	bytes	[]byte	byte[]

Next Steps

• oneOf (Unions) - Discriminated union types
• allOf (Composition) - Type composition
• Naming - Naming conventions