Complex data types

Describe APIs with flexible schemas using oneOf, anyOf, and allOf keywords for optional properties, polymorphism, and multiple data formats.

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.

Mintlify treats oneOf and anyOf identically since the practical difference rarely affects using the API.

For detailed specifications of these keywords see the OpenAPI documentation.

The not keyword is currently unsupported.

​

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.

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

org_with_users · object

Show child attributes

id · string

The ID of the organization

users · object[]

An array containing all users in the organization

​

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:

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
        # ...

delivery_address · object

StreetAddress

address_line_1 · string

The street address of the residence

POBox

box_number · string

The number of the PO Box

​

Conditional requirements

In OpenAPI 3.1, you can make a property required only in certain cases with the if, then, else, dependentRequired, and dependentSchemas keywords. Mintlify reads these keywords and labels each affected field on the endpoint page with a required pill followed by its condition.

For example, this schema requires a card number for card payments, an account number for every other payment method, and a company name whenever the request includes a tax ID:

Payment:
  type: object
  required:
    - method
  properties:
    method:
      type: string
      enum: [card, bank_transfer]
    card_number:
      type: string
    account_number:
      type: string
    tax_id:
      type: string
    company_name:
      type: string
  if:
    properties:
      method:
        const: card
  then:
    required:
      - card_number
  else:
    required:
      - account_number
  dependentRequired:
    tax_id:
      - company_name

The endpoint page labels these fields:

• card_number: required if method = card
• account_number: required unless method = card
• company_name: required if tax_id is set

Mintlify summarizes conditions that test sibling properties for specific values with const or enum, or for presence with required. When a condition is too complex to summarize, the field shows a conditionally required pill instead.

A property test in if also passes when the property is missing. To get a specific label, make the tested property required, either in the object’s required list or in the if schema’s required list. Otherwise, the field shows the conditionally required pill.