Request bodies define the structure and content of data sent to an API operation. Properly specifying request bodies ensures accurate input validation, clear contracts, and better reuse of schemas. This section provides best practices for defining request bodies in your OpenAPI specification.

Key recommendations

The following recommendations help you define request bodies clearly and consistently in your OpenAPI specification:
  • Always specify content as application/json (or other media types) with a schema reference.
  • Use a top-level object schema instead of inline anonymous structures. This approach allows reuse and better naming.
  • Indicate optional versus required fields using the required array. Do not rely solely on description text.
  • If using arrays, fully specify the items schema, including type, $ref, and description.
  • Provide field-level description for non-obvious semantics or constraints.

Example of a well-defined request body

The following example demonstrates how to define a request body and responses for creating a new customer:

post:
  summary: Create a new customer
  description: Creates a customer record. Fails if externalId already exists.
  operationId: createCustomer
  requestBody:
    required: true
    content:
      application/json:
        schema:
          $ref: '#/components/schemas/CreateCustomerRequest'
  responses:
    '201':
      description: Customer created
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Customer'
    '409':
      description: Conflict – externalId already exists