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

handrews · 2025-05-15T21:36:23Z

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)

Fixes:
- Support for arbitrary query strings #1502 (arbitrary query strings)
- Supporting of one separate 'required' option for query parameters #2347 (re-using parameter schemas independent of required-ness)
- How to disallow unknown query parameter? #2511 (disallow unknown query parameters, could be done with deepObject but now can be done while also using style/explode for individual parameters)
Fixes as much as we can fix without someting much more drastic:
- [Question] Extend/override properties of a parameter #2026 (re-using with differing constraints- this is as much as we can solve this without going to Moonwalk)
- Aliasing query parameters #2298 (aliasing- no special aliasing construct, but using $refs comes pretty close)
Enables fix through registering a media type or defining an out-of-band format for use with in: querystring, content: {text/plain: {...}:

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.

davebelais · 2025-05-16T16:28:48Z

@handrews : I just want to confirm my understanding—so that I can plan for related tooling: when we have a parameter which has a in="querystring"—that operation shouldn't have any other parameters which have a in="query", right?

handrews · 2025-05-16T16:33:32Z

@davebelais replace style with in and then yes. Because querystring consumes the entire part of the URL between ? and # (or the end if no # is present). Trying to come up with rules for how in: querystring and in: query would share that space is way too complex. Plus in: querystring plus the Encoding Object can do everything that a set of in: query parameters can do and more, I believe.

src/oas.md

lornajane

I LOVE this addition!

Co-authored-by: Lorna Jane Mitchell <github@lornajane.net>

Replace "no defined mapping" with "no registered mapping" and link to the section about the registry.

handrews · 2025-05-22T14:35:48Z

This latest commit replaces "no defined mapping" with "no registered mapping" (linking to the section on the registry) in the JSONPath example. It also adds a serialized form to the JSON in: querystring example. (@lornajane I figured your approval got cleared anyway and needs re-adding, so I might as well tweak these).

src/oas.md

miqui · 2025-05-24T11:16:19Z

This latest commit replaces "no defined mapping" with "no registered mapping" (linking to the section on the registry) in the JSONPath example. It also adds a serialized form to the JSON in: querystring example. (@lornajane I figured your approval got cleared anyway and needs re-adding, so I might as well tweak these).

@handrews Hi. When I follow the click path (under the overall media type reg section) with respect to the media registry, I end up with this URL: https://spec.openapis.org/registry/media-type/ which is broken (404).

handrews · 2025-05-24T23:39:29Z

@miqui yeah we still need to put the registry up. It will be published along with 3.2 and 3.1.2, so it's expected to be broken for now.

karenetheridge · 2025-05-26T20:25:44Z

Also worth noting -- this solves the "how do I indicate a relationship or dependency between query parameters" usecase -- as this allows for declaring all query parameters as being decoded to a json object, to let us use more complicated json schema constructs e.g. minProperties, if/then/else, anyOf etc.

Note -- We already could do that today, if you squint at the specification the right way, by specifying the right combination of style, explode, and schema/type, but it's not explicitly spelled out in the spec and probably a lot of implementations don't support that right now. This new mechanism makes the implementation much more explicit, and it is also more adaptable to other serialization styles than just application/x-www-form-urlencoded.

karenetheridge

A few comments, questions and spelling fixes.

karenetheridge · 2025-05-27T19:00:49Z

src/oas.md

+Two avenues are available for supporting such formats with `in: "querystring"`:
+
+* Use `content` and `text/plain` with a schema of `type: "string"` and define the format outside of OpenAPI.  While this requires more work to document and construct or parse the format, which is seen as a plain string from the OpenAPI perspective, it provides the easiest flexible option
+* Define a media type (which need not necessarily be [IANA-registered](https://www.rfc-editor.org/rfc/rfc6838.html)) and submit a registration for how it can be supported (using `in: "querystring"` and the `content` field) to the OpenAPI Initiative's [Media Type Registry](#media-type-registry).


This implies that submitting an entry to the Media Type Registry is required. It of course is not; an implementation could invent its own media type and only support it locally. This would not be interoperable outside of the scope of where the media type is defined, but I could easily see an application or company doing this for "internal" interfaces.

Can we modify this to simply recommend that new media types be submitted to the registry, to facilitate interoperability?

karenetheridge · 2025-05-27T19:04:01Z

src/oas.md

+  example: {
+    "numbers": [1, 2],
+    "flag": null
+  }


I would think this should more properly be:

example: '{"numbers": [1, 2], "flag": null }'

..as the actual content of the querystring value is a literal json string, not a json object.

src/oas.md

Co-authored-by: Karen Etheridge <github@froods.org>

It is not necessary to register a media type to use it with the `content` field.

handrews · 2025-05-27T20:06:41Z

@karenetheridge great catches here! I have updated accordingly- see if this language about the registry works for you. I am happy to try again if it doesn't quite capture what you have in mind.

karenetheridge

LGTM!

handrews · 2025-05-28T15:32:17Z

@lornajane @miqui can you re-approve after these fixes of things that @karenetheridge found?

handrews · 2025-05-28T22:24:47Z

@karenetheridge now that I am thinking more about this, I think the change to example was incorrect, as JSON/YAML examples do not need to be encoded. And in fact just look like strings if they are. It would be shown as a string if we could use the example field next to content one level up.

I'm going to change that one part back. There's a lot of additional debate around examples right now. so we may need to do a follow-up. I'd like to not hold this up on our example confusion if at all possible, as that applies to many things, and if we need to fix it, we can fix it here along with everywhere else if this PR is already merged.

This is at the Media Type Object level, and JSON examples are to be written as inline JSON/YAML. If we were at the Parameter Object level, we would use the URI percent-encoded string form, but the example field is not allowed with the content field.

handrews added this to the v3.2.0 milestone May 15, 2025

handrews requested review from a team as code owners May 15, 2025 21:36

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 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

handrews mentioned this pull request May 16, 2025

Proposal: dotDelimited style for query serialization. #3084

Open

Better formatting

9a7d8ca

lornajane reviewed May 21, 2025

View reviewed changes

src/oas.md Outdated Show resolved Hide resolved

lornajane previously approved these changes May 21, 2025

View reviewed changes

Improved wording

f35f66d

Co-authored-by: Lorna Jane Mitchell <github@lornajane.net>

handrews dismissed lornajane’s stale review via f35f66d May 21, 2025 18:42

Improve querystring examples, link to registry

0b7c42d

Replace "no defined mapping" with "no registered mapping" and link to the section about the registry.

handrews mentioned this pull request May 22, 2025

Open Community (TDC) Meeting, Thursday 22 May 2025 #4584

Open

miqui previously approved these changes May 24, 2025

View reviewed changes

src/oas.md Show resolved Hide resolved

lornajane self-requested a review May 24, 2025 16:35

lornajane previously approved these changes May 24, 2025

View reviewed changes

karenetheridge requested changes May 27, 2025

View reviewed changes

Apply suggestions from code review

ebf9a44

Co-authored-by: Karen Etheridge <github@froods.org>

handrews dismissed stale reviews from lornajane and miqui via ebf9a44 May 27, 2025 19:59

Fix example, optional registry usage

634855e

It is not necessary to register a media type to use it with the `content` field.

karenetheridge previously approved these changes May 27, 2025

View reviewed changes

lornajane mentioned this pull request May 28, 2025

Publish the media types registry #4632

Open

miqui previously approved these changes May 28, 2025

View reviewed changes

Change example back

6370475

This is at the Media Type Object level, and JSON examples are to be written as inline JSON/YAML. If we were at the Parameter Object level, we would use the URI percent-encoded string form, but the example field is not allowed with the content field.

handrews dismissed stale reviews from miqui and karenetheridge via 6370475 May 28, 2025 22:29

handrews mentioned this pull request May 28, 2025

Open Community (TDC) Meeting, Thursday 29 May 2025 #4625

Open

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

Are you sure you want to change the base?

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

Uh oh!

Conversation

handrews commented May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

davebelais commented May 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

handrews commented May 16, 2025

Uh oh!

Uh oh!

lornajane left a comment

Choose a reason for hiding this comment

Uh oh!

handrews commented May 22, 2025

Uh oh!

Uh oh!

miqui commented May 24, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

handrews commented May 24, 2025

Uh oh!

karenetheridge commented May 26, 2025

Uh oh!

karenetheridge left a comment

Choose a reason for hiding this comment

Uh oh!

karenetheridge May 27, 2025

Choose a reason for hiding this comment

Uh oh!

karenetheridge May 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

handrews commented May 27, 2025

Uh oh!

karenetheridge left a comment

Choose a reason for hiding this comment

Uh oh!

handrews commented May 28, 2025

Uh oh!

handrews commented May 28, 2025

Uh oh!

Uh oh!

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

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

handrews commented May 15, 2025 •

edited

Loading

davebelais commented May 16, 2025 •

edited

Loading

miqui commented May 24, 2025 •

edited

Loading