The oneOf keyword

In support of the OpenAPI Specification oneOf schemas, Speakeasy SDKs provide language-specific implementations based on idiomatic unions (when available) or using generated supporting objects that allow type safety by using an enum discriminator.

Supporting objects

Assuming an OpenAPI document has a Pet component, consider this oneOf block:

How Speakeasy generates supporting objects for your SDK depends on the language of the SDK.

Requests

Assume you have an operation that allows the user to fetch a pet by submitting the pet’s name, ID, or complete pet object:

Responses

Sometimes you may have a response that specifies a oneOf schema. For languages that do not natively support unions, Speakeasy will create supporting objects to deserialize the oneOf response into the correct object type. No supported objects are needed for languages with native union types, so Speakeasy will deserialize into the native type.

For example, this schema:

Will result in these response types:

Splitting oneOf schema types

By defining similar operations with aligned but different schemas, you can apply x-speakeasy-type-override: any for untyped operations and use oneOf to define stricter types in others. This allows you to use methods like DoSomething(StrictObject{...}) alongside DoSomethingUntyped({...}), providing flexibility across SDK methods based on the required schema type.

This approach is particularly useful when dealing with endpoints that require you to split oneOf schema types into separate SDK methods.

Example: