anyOf Handling

Soxom interprets anyOf as oneOf to avoid type explosion and provide predictable SDK types.

The Problem with anyOf

In OpenAPI, anyOf means “match one or more of these schemas.” This creates challenges for type generation:

# OpenAPI anyOf
Value:
  anyOf:
    - type: string
    - type: integer
    - type: array
      items:
        type: string

Theoretical valid values:

"hello" - string only
42 - integer only
["a", "b"] - array only
But also… combinations? The spec is ambiguous.

Type explosion problem:

// What type should we generate?
type Value =
  | string
  | number
  | string[]
  | (string & number)           // Impossible
  | (string & string[])         // Impossible
  | (number & string[])         // Impossible
  | (string & number & string[]) // Impossible

Soxom’s Approach

This provides:

Predictable types
Clean SDK code
Better developer experience
Consistent behavior across languages

Example

# OpenAPI
Result:
  anyOf:
    - $ref: '#/components/schemas/Success'
    - $ref: '#/components/schemas/Error'

Soxom generates (same as oneOf):

// TypeScript
type Result = Success | Error;

# Python
Result = Success | Error

Rationale

Alignment with Reality

In practice, APIs using anyOf almost always mean oneOf:

Response is either a success OR an error
Value is either a string OR a number
Data is either format A OR format B

True “any combination” semantics are rare and usually indicate spec issues.

Predictable SDKs

Treating anyOf as oneOf ensures:

Type-safe code generation
Clear discriminator handling
Consistent serialization/deserialization
Better IDE autocomplete

Industry Standard

This approach aligns with other SDK generators like Speakeasy, providing familiar behavior for API developers.

Recommendations

Use oneOf Instead

When you mean “one of these options”, use oneOf:

# Recommended
PaymentMethod:
  oneOf:
    - $ref: '#/components/schemas/CreditCard'
    - $ref: '#/components/schemas/BankAccount'
  discriminator:
    propertyName: type

Use allOf for Combinations

When you need combined properties, use allOf:

# For combining schemas
Employee:
  allOf:
    - $ref: '#/components/schemas/Person'
    - $ref: '#/components/schemas/Employment'

Avoid anyOf

If you have anyOf in your spec, consider:

Convert to oneOf if values are mutually exclusive
Convert to allOf if values should be combined
Restructure if neither fits

Migration Examples

anyOf to oneOf

Before:

Response:
  anyOf:
    - $ref: '#/components/schemas/SuccessResponse'
    - $ref: '#/components/schemas/ErrorResponse'

After:

Response:
  oneOf:
    - $ref: '#/components/schemas/SuccessResponse'
    - $ref: '#/components/schemas/ErrorResponse'
  discriminator:
    propertyName: status
    mapping:
      success: '#/components/schemas/SuccessResponse'
      error: '#/components/schemas/ErrorResponse'

anyOf to Separate Types

Before:

# Trying to express "string or number"
FlexibleId:
  anyOf:
    - type: string
    - type: integer

After:

# Just use string - IDs should be strings anyway
FlexibleId:
  type: string
  description: ID can be numeric but is always transmitted as string

Edge Cases

Nullable with anyOf

# Often seen for nullable types
MaybeUser:
  anyOf:
    - $ref: '#/components/schemas/User'
    - type: 'null'

Soxom handles this as a nullable type:

type MaybeUser = User | null;

Single-Item anyOf

# Sometimes used for inheritance
ExtendedUser:
  anyOf:
    - $ref: '#/components/schemas/User'
  properties:
    extra_field:
      type: string

Soxom treats this as simple extension (like allOf).

Summary

Keyword	Use When	Soxom Behavior
`oneOf`	Mutually exclusive options	Union type with discriminator
`allOf`	Combining/inheriting schemas	Composition/inheritance
`anyOf`	Avoid if possible	Treated as `oneOf`

Next Steps

oneOf (Unions) - Proper union type usage
allOf (Composition) - Type composition
Naming - Naming conventions