Skip to content

Support root-level webhooks for OpenAPI 3.1 documents (parse + WebhooksIn30 rule) - #199

Merged
geemus merged 4 commits into
ota42y:masterfrom
takayamaki:pr10-webhooks
Aug 6, 2026
Merged

Support root-level webhooks for OpenAPI 3.1 documents (parse + WebhooksIn30 rule)#199
geemus merged 4 commits into
ota42y:masterfrom
takayamaki:pr10-webhooks

Conversation

@takayamaki

Copy link
Copy Markdown
Contributor

Continuing the OpenAPI 3.1 work from #152.

OpenAPI 3.1 adds a root-level webhooks field:
a map of names to Path Item objects describing requests the API sends rather than receives.
3.0 has no equivalent field.

This PR adds parse support and version-mismatch detection.

Parse layer

webhooks is parsed as a hash of PathItem objects (with $ref support),
exposed as an accessor on the root object:

root = OpenAPIParser.load('spec_3_1.yaml')
root.webhooks['invoicePaid'] # => OpenAPIParser::Schemas::PathItem

Following the permissive-parse strategy agreed in #152,
the parse layer accepts webhooks regardless of the declared OpenAPI version.

SpecValidator rule

WebhooksIn30 reports a violation when a 3.0 document declares root-level webhooks:

OpenAPIParser.load(
  'spec.yaml',
  strict_specification_version: :warn,
)
# [WebhooksIn30] #/webhooks — `webhooks` is a 3.1 root-level addition; 3.0 documents have no such field

OpenAPI root gains a `webhooks` hash-of-PathItem accessor; the parse
layer accepts the field in any version. Rules::WebhooksIn30 reports
the version mismatch when a 3.0 document declares webhooks.
A root-level `webhooks` on a 3.0 document warns and raises (3.1
addition); the same field on a 3.1 document stays clean.
@takayamaki
takayamaki marked this pull request as ready for review August 1, 2026 03:17

@geemus geemus left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm, thanks!

@geemus
geemus merged commit 9ce5d10 into ota42y:master Aug 6, 2026
14 checks passed
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.

2 participants