Skip to content

Schema for callback and webhook includes readOnly property in the request instead of the writeOnly property #2724

@jedidiahkkh

Description

@jedidiahkkh

Describe the bug
I'm trying to reuse an object across a normal endpoint and the callback/another webhook. In the callbacks and webhooks, the writeOnly fields don't show anywhere, instead the readOnly fields show up in both the request and response. Interestingly, for the webhook response payload, the writeOnly field shows up in the example as expected, but not the schema definition.

Expected behavior
For normal endpoints I expect writeOnly fields to only show in the request and readOnly fields to show in the response. However for callbacks and webhooks, since the roles of the API server and the client are reversed (server is sending the request), I would expect the roles of readOnly and writeOnly to be reversed.

Do correct me if this assumption is wrong, this is what I understood from #1540.

Minimal reproducible OpenAPI snippet(if possible)

openapi: 3.1.0
info:
  title: API Documentation
  description: API documentation with endpoints and webhooks using simpleObject schema

servers:
  - url: https://api.mycompany.com
    description: Production server
  - url: https://staging.api.mycompany.com
    description: Staging server

components:
  schemas:
    # Global schema object that will be used across all endpoints
    simpleObject:
      type: object
      properties:
        readOnly:
          type: string
          readOnly: true
          description: A read-only string field
          example: "This field is read-only"
        writeOnly:
          type: string
          writeOnly: true
          description: A write-only string field
          example: "This field is write-only"
      required:
        - readOnly
        - writeOnly

paths:
  /api/data:
    post:
      summary: Create data entry
      description: Creates a new data entry in the system
      operationId: createDataEntry
      tags:
        - Data API
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/simpleObject'
      responses:
        '200':
          description: Data entry created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/simpleObject'
      callbacks:
        dataProcessed:
          '{$request.body#/callbackUrl}':
            post:
              summary: Data processing callback
              description: Called when the data entry has been processed
              requestBody:
                required: true
                content:
                  application/json:
                    schema:
                      $ref: '#/components/schemas/simpleObject'
              responses:
                '200':
                  description: Callback acknowledged
                  content:
                    application/json:
                      schema:
                        $ref: '#/components/schemas/simpleObject'

webhooks:
  dataUpdated:
    post:
      summary: Data updated webhook
      description: Webhook triggered when data is updated in the system
      operationId: dataUpdatedWebhook
      tags:
        - Webhooks
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/simpleObject'
      responses:
        '200':
          description: Webhook received and processed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/simpleObject'

Screenshots

Image Image

Additional context
I've created a minimal repo here

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions