Skip to content

v3.1.2: Style examples cannot include ? - #4627

Closed
handrews wants to merge 1 commit into
OAI:v3.1-devfrom
handrews:style-examples
Closed

v3.1.2: Style examples cannot include ?#4627
handrews wants to merge 1 commit into
OAI:v3.1-devfrom
handrews:style-examples

Conversation

@handrews

@handrewshandrews commented May 27, 2025•
edited
Loading

Copy link
Copy Markdown
Member

[EDIT: Due to the complex and confusing history, it would be far better to go with #4647 which aligns this table with new example fields that have well-defined behavior.]

We say that the example table is "as would be shown with the example or examples keywords", but then we include the ? which is not correct for a single parameter with in: query.

  • schema changes are included in this pull request
  • schema changes are needed for this pull request but not done yet
  • no schema changes are needed for this pull request

@handrews
The "?" is not part of individual parameter serializations
10f1810
We say that the example table is "as would be shown with the
`example` or `examples` keywords", but then we include the `?`
which is not correct for a single parameter with `in: query`.
Even with `in: querystring`, it would not be correct because the
parameter describes the `application/x-www-form-urlencoded` document,
which does not include the `?` delimiter.
@handrews
handrews requested review from a team as code ownersMay 27, 2025 19:12
@handrewshandrews added bug param serialization Issues related to parameter and/or header serialization media and encoding Issues regarding media type support and how to encode data (outside of query/path params) example obj/keywords Issues with the Example Object or exampel(s) keywords labels May 27, 2025
@handrewshandrews added this to the v3.1.2 milestone May 27, 2025
lornajane
lornajane approved these changes May 28, 2025
View reviewed changes

@lornajanelornajane left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

This does make more sense now, thank you!

@lornajane
lornajane requested a review from a teamMay 28, 2025 09:00
@handrews

handrews commented May 28, 2025

Copy link
Copy Markdown
MemberAuthor

I want to acknowledge that we did debate this for 3.0.4/3.1.1, but we did not put it in consistently and think we got it wrong.

We said the ? would be consistent with how other styles (e.g. matrix with the ; delimiter, including at the beginning) are shown. But this is not correct. the ; for matrix (and similar delimiters for other styles) are analogous to & and =, which are the internal value delimiters with the form style. Those other styles do not have an analogue to ? which is part of the URI specification.

@handrews

handrews commented May 28, 2025

Copy link
Copy Markdown
MemberAuthor

I'm going to put this in draft b/c I want to make a more coherent proposal after discussions in #4622. We may or may not need this separate PR after that.

@handrews
handrews marked this pull request as draft May 28, 2025 21:52
@handrews

handrews commented Jun 2, 2025

Copy link
Copy Markdown
MemberAuthor

See PR #4647 for a much more thorough treatment that describes what is going on much better. Even if we do this PR instead, I need to update it a bit based on what I learned doing the other one.

@handrews

handrews commented Jun 5, 2025

Copy link
Copy Markdown
MemberAuthor

I'm closing this in favor of #4647 given that PRs positive reception in this morning's call

@handrewshandrews closed this Jun 5, 2025
@handrews
handrews deleted the style-examples branch June 19, 2025 18:19
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@lornajanelornajanelornajane approved these changes

Assignees

No one assigned

Labels

bugexample obj/keywordsIssues with the Example Object or exampel(s) keywordsmedia and encodingIssues regarding media type support and how to encode data (outside of query/path params)param serializationIssues related to parameter and/or header serialization

Projects

None yet

Milestone

v3.1.2

Development

Successfully merging this pull request may close these issues.

2 participants

@handrews@lornajane