Complex data types - Mintlify

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.

For detailed specifications of these keywords see the OpenAPI documentation.

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 leveraging 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

Providing options with oneOf and anyOf

When you use oneOf or anyOf, the options are displayed 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
        # ...