mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
mintlify[bot]
674ef1a5f0
Co-authored-by: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
101 lines
3.9 KiB
Plaintext
101 lines
3.9 KiB
Plaintext
---
|
|
title: "Complex data types"
|
|
description: "Describe APIs with flexible schemas using oneOf, anyOf, and allOf keywords for optional properties, polymorphism, and multiple data formats."
|
|
keywords: ["oneOf", "anyOf", "allOf", "schema composition", "polymorphic schemas"]
|
|
---
|
|
|
|
When your API accepts multiple data formats, has conditional fields, or uses inheritance patterns, OpenAPI's schema composition keywords help you document these flexible structures. Using `oneOf`, `anyOf`, and `allOf`, you can describe APIs that handle different input types or combine multiple schemas into comprehensive data models.
|
|
|
|
## `oneOf`, `anyOf`, `allOf` keywords
|
|
|
|
For complex data types, OpenAPI provides keywords for combining schemas:
|
|
|
|
- `allOf`: Combines multiple schemas (like merging objects or extending a base schema). Functions like an `and` operator.
|
|
- `anyOf`: Accepts data matching any of the provided schemas. Functions like an `or` operator.
|
|
- `oneOf`: Accepts data matching exactly one of the provided schemas. Functions like an `exclusive-or` operator.
|
|
|
|
<Warning>Mintlify treats `oneOf` and `anyOf` identically since the practical difference rarely affects using the API.</Warning>
|
|
|
|
For detailed specifications of these keywords see the [OpenAPI documentation](https://swagger.io/docs/specification/data-models/oneof-anyof-allof-not/).
|
|
|
|
<Info>The `not` keyword is currently unsupported.</Info>
|
|
|
|
### Combining schemas with `allOf`
|
|
|
|
When you use `allOf`, Mintlify performs some preprocessing on your OpenAPI document to display complex combinations in a readable way. For example, when you combine two object schemas with `allOf`, Mintlify combines the properties of both into a single object. This becomes especially useful when you use OpenAPI's reusable [components](https://swagger.io/docs/specification/components/).
|
|
|
|
```yaml
|
|
org_with_users:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Org'
|
|
- type: object
|
|
properties:
|
|
users:
|
|
type: array
|
|
description: An array containing all users in the organization
|
|
# ...
|
|
components:
|
|
schemas:
|
|
Org:
|
|
type: object
|
|
properties:
|
|
id:
|
|
type: string
|
|
description: The ID of the organization
|
|
```
|
|
|
|
<ParamField body="org_with_users" type="object">
|
|
<Expandable>
|
|
<ParamField body="id" type="string">
|
|
The ID of the organization
|
|
</ParamField>
|
|
<ParamField body="users" type="object[]">
|
|
An array containing all users in the organization
|
|
</ParamField>
|
|
</Expandable>
|
|
</ParamField>
|
|
|
|
### `any` and `undefined` types
|
|
|
|
Fields typed as `any` or `undefined` render the same way as `oneOf` schemas with a picker that lets users select a concrete shape before sending a request. This allows the API playground to present a meaningful input even when the schema doesn't constrain the value to a single type.
|
|
|
|
### Providing options with `oneOf` and `anyOf`
|
|
|
|
When you use `oneOf` or `anyOf`, the options display in a tabbed container. Specify a `title` field in each subschema to give your options names. For example, here's how you might display two different types of delivery addresses:
|
|
|
|
```yaml
|
|
delivery_address:
|
|
oneOf:
|
|
- title: StreetAddress
|
|
type: object
|
|
properties:
|
|
address_line_1:
|
|
type: string
|
|
description: The street address of the recipient
|
|
# ...
|
|
- title: POBox
|
|
type: object
|
|
properties:
|
|
box_number:
|
|
type: string
|
|
description: The number of the PO Box
|
|
# ...
|
|
```
|
|
|
|
<ParamField body="delivery_address" type="object">
|
|
<div className="mt-4 rounded-xl border border-gray-100 px-4 pb-4 pt-2 dark:border-white/10">
|
|
<Tabs>
|
|
<Tab title="StreetAddress">
|
|
<ParamField body="address_line_1" type="string">
|
|
The street address of the residence
|
|
</ParamField>
|
|
</Tab>
|
|
<Tab title="POBox">
|
|
<ParamField body="box_number" type="string">
|
|
The number of the PO Box
|
|
</ParamField>
|
|
</Tab>
|
|
</Tabs>
|
|
</div>
|
|
</ParamField>
|