Skip to content

Conversation

@djm
Copy link

@djm djm commented Jul 9, 2025

Prior to this commit, providing operation_id to extend_schema on a webhook object would not have any effect on the resulting schema.

The OpenAPI 3.1 spec added support for webhooks being their own top-level definition. Each Webhook is an Operation Object.

Operation Objects are defined in the spec @ 4.8.10, and it dictates that they may contain an operationedId string field:

Unique string used to identify the operation. The id MUST be unique among
all operations described in the API. The operationId value is case-sensitive.
Tools and libraries MAY use the operationId to uniquely identify an operation,
therefore, it is RECOMMENDED to follow common programming naming conventions.

Some platforms, such as Fern docs, require operationId on webhooks in the schema to identify them. Without the ability to output operationId users cannot use their schema with services like this.

We took the decision to only output explicitly provided operationIds for two reasons:

  1. operationIds are not marked as REQUIRED by the spec in the languge.
  2. This will allow users to opt-in to this feature rather than have their webhooks defined with auto-generated names. The auto-name generation relies on the path segment which webhooks don't have and so users would have uniqueness issues here unless we also changed that algorithm.

Prior to this commit, providing `operation_id` to `extend_schema` on a
webhook object would not have any effect on the resulting schema.

The OpenAPI 3.1 spec added support for webhooks being their own
top-level definition. Each Webhook is an Operation Object.

Operation Objects are defined in the spec @ 4.8.10, and it dictates that
they may contain an `operationedId` string field:

>Unique string used to identify the operation. The id MUST be unique among
>all operations described in the API. The operationId value is case-sensitive.
>Tools and libraries MAY use the operationId to uniquely identify an operation,
>therefore, it is RECOMMENDED to follow common programming naming conventions.

Some platforms, such as Fern docs, require `operationId` on webhooks in
the schema to identify them. Without the ability to output operationId users
cannot use their schema with services like this.

We took the decision to only output explicitly provided operationIds for
two reasons:

1) operationIds are not marked as REQUIRED by the spec in the languge.
2) This will allow users to opt-in to this feature rather than have
   their webhooks defined with auto-generated names. The auto-name
   generation relies on the path segment which webhooks don't have and
   so users would have uniqueness issues here unless we also changed
   that algorithm.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant