Nested Object and Array Schemas in OpenAPI

Nested Schemas in OpenAPI

Real-world APIs rarely deal with flat data structures. Orders contain line items, users have addresses, and configurations have nested settings. OpenAPI provides several mechanisms for defining complex nested schemas.

Nested Objects

components:
  schemas:
    UserProfile:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        address:
          type: object
          properties:
            street:
              type: string
            city:
              type: string
            state:
              type: string
            zip:
              type: string
            country:
              type: string
              default: US

Arrays of Objects

Order:
  type: object
  properties:
    id:
      type: string
    items:
      type: array
      items:
        type: object
        required: [product_id, quantity]
        properties:
          product_id:
            type: string
          quantity:
            type: integer
            minimum: 1
          unit_price:
            type: number
    total:
      type: number

Schema Composition with allOf

Extend a base schema:

BaseEntity:
  type: object
  properties:
    id:
      type: string
      format: uuid
    created_at:
      type: string
      format: date-time
    updated_at:
      type: string
      format: date-time

User:
  allOf:
    - $ref: "#/components/schemas/BaseEntity"
    - type: object
      required: [email]
      properties:
        email:
          type: string
          format: email
        name:
          type: string

Polymorphism with oneOf and discriminator

Notification:
  oneOf:
    - $ref: "#/components/schemas/EmailNotification"
    - $ref: "#/components/schemas/SmsNotification"
    - $ref: "#/components/schemas/PushNotification"
  discriminator:
    propertyName: type
    mapping:
      email: "#/components/schemas/EmailNotification"
      sms: "#/components/schemas/SmsNotification"
      push: "#/components/schemas/PushNotification"

EmailNotification:
  type: object
  required: [type, recipient, subject]
  properties:
    type:
      type: string
      enum: [email]
    recipient:
      type: string
      format: email
    subject:
      type: string
    body:
      type: string

SmsNotification:
  type: object
  required: [type, phone_number, message]
  properties:
    type:
      type: string
      enum: [sms]
    phone_number:
      type: string
    message:
      type: string
      maxLength: 160

Recursive Schemas

Self-referencing schemas for tree structures:

TreeNode:
  type: object
  properties:
    name:
      type: string
    children:
      type: array
      items:
        $ref: "#/components/schemas/TreeNode"

Best Practices

• Extract frequently used sub-objects into named schemas
• Use allOf for inheritance instead of copy-pasting properties
• Use discriminator with oneOf for type-safe polymorphism
• Limit nesting depth to 3-4 levels for readability