Complex data types

When an endpoint accepts multiple shapes of input or returns composed objects, describe those structures in your OpenAPI schema instead of flattening them into vague free-form JSON.

​

Use the composition keywords intentionally

• allOf combines schemas into one object shape.
• anyOf allows a payload to match any valid option.
• oneOf documents mutually exclusive alternatives.

​

Example: extending a base schema

components:
  schemas:
    Documentation:
      type: object
      properties:
        id:
          type: string
        title:
          type: string

    DocumentationWithManifest:
      allOf:
        - $ref: "#/components/schemas/Documentation"
        - type: object
          properties:
            files:
              type: array
              items:
                $ref: "#/components/schemas/ManifestFile"

​

Example: alternative request shapes

requestBody:
  required: true
  content:
    application/json:
      schema:
        oneOf:
          - $ref: "#/components/schemas/PushFullDocsRequest"
          - $ref: "#/components/schemas/PushChangedPathsRequest"

​

Make the result readable

• Give each alternative a clear name.
• Add examples to each branch when the shapes are similar.
• Prefer smaller reusable schemas over one large anonymous object.

If the reader cannot tell when to use each branch, the problem is usually the schema design, not the docs renderer.