Skip to content

v3.2: Add in: "querystring" parameter location treating the entire query string as one chunk of content #4590

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.

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

Open
wants to merge 2 commits into
base: v3.2-dev
Choose a base branch
from

Conversation

handrews
Copy link
Member

@handrews handrews commented May 15, 2025

NOTE: This change was tentativley approved for 3.2 a long time ago, then punted to 3.3 when we thought we'd need to defer larger data modeling changes to that release. However, several things have changed that makes this suitable for 3.2 now:

  • All this really does is allow using the Encoding Object in a new place, which we are already doing with PRs v3.2 Respect encoding in all Media Type Objects #4559 and v3.2: Support ordered multipart including streaming #4589. We should really include all of the "use the Encoding Object in more places" changes in one release!
  • We already decided to add the media type registry in 3.2, when at one point we weren't going to do that until 3.3
  • I realized that limiting in: querystring to using content avoids all of the confusing problems of how to deal with the Parameter Object's style/explode/etc. in an environment where they do not make sense (and duplicate the fields in the Encoding Object)


This allows treating the entire query string as a single parameter, which for application/x-www-form-urlencoded results in it being handled exactly as request bodies of that media type are handled.

Only one in: "querystring" is allowed per operation, and if it is present, no in: "query" parameters are allowed.

The content field MUST be used for in: "querystring", as the style and related fields are handled in the Encoding Object.

This also includes a recommendation that implementors design media types for complex query string formats such as those defined by various frameworks, and register a procedure for supporting them in our media type registry. This is intended to address a slow but steady trickle of requests to support various complex and often contradictory query string formats.

  • 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

This allows treating the entire query string as a single parameter,
which for `application/x-www-form-urlencoded` results in it being
handled exactly as request bodies of that media type are handled.

Only one `in: "querystring"` is allowed per operation, and if it
is present, no `in: "query"` parameters are allowed.

The `content` field MUST be used for `in: "querystring"`, as the
`style` and related fields are handled in the Encoding Object.

This also includes a recommendation that implementors design
media types for complex query string formats such as those defined
by various frameworks, and register a procedure for supporting
them in our media type registry.  This is intended to address
a slow but steady trickle of requests to support various complex
and often contradictory query string formats.
@handrews handrews added this to the v3.2.0 milestone May 15, 2025
@handrews handrews requested review from a team as code owners May 15, 2025 21:36
@handrews handrews added enhancement 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) labels May 15, 2025
@handrews handrews changed the title Add in: "querystring" parameter location treating the entire query string as one chunk of content v3.2: Add in: "querystring" parameter location treating the entire query string as one chunk of content May 15, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement 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
Development

Successfully merging this pull request may close these issues.

1 participant