Skip to content

v3.1.2: Style examples cannot include ? #4627

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Closed
wants to merge 1 commit into from
Closed

v3.1.2: Style examples cannot include ? #4627

wants to merge 1 commit into from

Conversation

handrews
Copy link
Member

@handrews handrews commented May 27, 2025 •
edited
Loading

[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 owners May 27, 2025 19:12
@handrews handrews 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
@handrews handrews added this to the v3.1.2 milestone May 27, 2025
lornajane
lornajane approved these changes May 28, 2025
View reviewed changes
Copy link
Contributor

@lornajane lornajane left a comment

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 team May 28, 2025 09:00
@handrews
Copy link
Member Author

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
Copy link
Member Author

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
Copy link
Member Author

handrews commented Jun 2, 2025

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
Copy link
Member Author

handrews commented Jun 5, 2025

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

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

@lornajane lornajane lornajane approved these changes

Assignees
No one assigned
Labels
bug example obj/keywords Issues with the Example Object or exampel(s) keywords media and encoding Issues regarding media type support and how to encode data (outside of query/path params) param serialization Issues 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