Response schemas are structured definitions that describe the format and content of data returned by an API. They ensure that both the API provider and the consumer have a clear, predictable understanding of what the response should look like.

To define clear response schemas, follow these guidelines:
  • Always define a primary success code for each response. Common examples include:
    Status code Description
    200 Successful request
    201 Resource created
  • Define an explicit error schema such as ErrorResponse to ensure predictable error handling. This schema should include fields that describe the error in detail.
  • Avoid unnecessary complexity in schema design. Use oneOf, allOf, or anyOf only when strictly required. Prefer simpler schema shapes for better readability and maintainability.
  • For list endpoints, use an envelope that includes metadata along with the items. This approach provides additional context such as total count and pagination details. Here is an example schema for a customer list:
    CustomerList:
  title: CustomerList
  type: object
  required: [items, total]
  properties:
    items:
      type: array
      items:
        $ref: '#/components/schemas/Customer'
    total:
      type: integer
      description: Total available (not just page size)
    nextCursor:
      type: string
      nullable: true
  • Use format attributes such as date-time, uuid, or email to provide additional validation and clarity.