Skip to content

Respect does not allow sending a null payload when an example is described in the OpenAPI schema #2497

@DmitryAnansky

Description

@DmitryAnansky

Describe the bug

When you have some example described in your OpenAPI, like

examples:
  simpleOrder:
    summary: Simple order with one item
    description: A basic order for a single product.
    value:
      customerId: cus_12345
      currency: EURO
      items:
        - productId: prod_abc
          quantity: 2
          unitPrice: 19.99
      notes: Please deliver after 6 PM

It is not possible to send null payload within requestBody, because the example is used as a default fallback.

workflows:
  - workflowId: sample
    steps:
      - stepId: create-order
        operationId: sample-api.createOrder
        requestBody:
          payload: null

Execution logs:

    Request Body:
      {
        "customerId": "cus_12345",
        "currency": "EURO",
        "items": [
          {
            "productId": "prod_abc",
            "quantity": 2,
            "unitPrice": 19.99
          }
        ],
        "notes": "Please deliver after 6 PM"
      } 

Expected behavior

Allow to send null payload.
Maybe use the example value only when the replacements described.

Logs

OpenAPI description

openapi: 3.1.0
info:
  title: Orders API
  version: 1.0.0
  description: API for creating customer orders.

servers:
  - url: https://api.example.com

paths:
  /orders:
    post:
      summary: Create a new order
      description: |
        Creates a new order for a customer and returns the created order details.
      operationId: createOrder
      requestBody:
        required: true
        description: Order creation payload
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrderRequest'
            examples:
              simpleOrder:
                summary: Simple order with one item
                description: A basic order for a single product.
                value:
                  customerId: cus_12345
                  currency: EURO
                  items:
                    - productId: prod_abc
                      quantity: 2
                      unitPrice: 19.99
                  notes: Please deliver after 6 PM
      responses:
        '201':
          description: Order successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
              examples:
                createdOrder:
                  summary: Created order response
                  value:
                    id: ord_98765
                    status: created
                    totalAmount: 39.98
                    currency: USD
                    createdAt: '2026-01-13T14:32:00Z'
        '400':
          description: Invalid request payload
        '500':
          description: Internal server error

components:
  schemas:
    CreateOrderRequest:
      type: object
      description: Payload used to create a new order.
      required:
        - customerId
        - currency
        - items
      properties:
        customerId:
          type: string
          description: Unique identifier of the customer placing the order.
          example: cus_12345
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
        items:
          type: array
          description: List of items included in the order.
          minItems: 1
          items:
            $ref: '#/components/schemas/OrderItem'
        notes:
          type: string
          description: Optional delivery or handling notes.
          example: Leave at the front desk.

    OrderItem:
      type: object
      description: A single line item in an order.
      required:
        - productId
        - quantity
        - unitPrice
      properties:
        productId:
          type: string
          description: Unique identifier of the product.
          example: prod_abc
        quantity:
          type: integer
          minimum: 1
          description: Number of units ordered.
          example: 2
        unitPrice:
          type: number
          format: float
          minimum: 0
          description: Price per unit at the time of ordering.
          example: 19.99

    Order:
      type: object
      description: Represents an order in the system.
      required:
        - id
        - status
        - totalAmount
        - currency
        - createdAt
      properties:
        id:
          type: string
          description: Unique identifier of the order.
          example: ord_98765
        status:
          type: string
          description: Current order status.
          enum: [created, paid, shipped, completed, cancelled]
          example: created
        totalAmount:
          type: number
          description: Total monetary value of the order.
          example: 39.98
        currency:
          type: string
          description: ISO 4217 currency code.
          example: USD
        createdAt:
          type: string
          format: date-time
          description: RFC 3339 timestamp when the order was created.
          example: '2026-01-13T14:32:00Z'

Redocly version(s)

  • 2.14.4

Node.js version(s)

  • v24.11.1

OS, environment

  • darwin / macOS

Additional context

Metadata

Metadata

Assignees

No one assigned

    Labels

    RespectRelated to the `respect` command which works with Arazzo specificationType: BugSomething isn't workingp2

    Type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions