Correct schema $comment for OAD content definition#5289
Open
notEthan wants to merge 1 commit intoOAI:v3.2-devfrom
Open
Correct schema $comment for OAD content definition#5289notEthan wants to merge 1 commit intoOAI:v3.2-devfrom
content definition#5289notEthan wants to merge 1 commit intoOAI:v3.2-devfrom
Conversation
ralfhandl
requested changes
Apr 16, 2026
Comment on lines
+569
to
+573
| $comment: | | ||
| Parameter Object: https://spec.openapis.org/oas/v3.2#fixed-fields-9 | ||
| Request Body Object: https://spec.openapis.org/oas/v3.2#fixed-fields-10 | ||
| Response Object: https://spec.openapis.org/oas/v3.2#fixed-fields-14 | ||
| Header Object: https://spec.openapis.org/oas/v3.2#fixed-fields-17 |
Contributor
There was a problem hiding this comment.
Why not link to the corresponding "Xxx Object" sections instead of the "Fixed Fields" subsections? Those are "close enough", especially for Parameter/Header Object where content is way down in the "Fixed Fields for use with content" subsection.
Contributor
Author
There was a problem hiding this comment.
That does seem better, thanks for the suggestion. Pushed.
…, Request Body, Response, Header (not just Request Body)
notEthan
force-pushed
the
content-object-schema-comment
branch
from
277abba to
d5c847d
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The
contentobject is a property of Parameter, Request Body, Response, and Header. Currently its schema $comment just links to Request Body.I'm targeting this at 3.2 instead of 3.3 because, in the linked anchors "fixed-fields-{n}", the numbers seem likely to end up different by publication. Not sure what to do about that. All of the other $comment spec links use more unique anchors.