v3.3: edits to parameter sections #5122

karenetheridge · 2025-11-15T22:47:33Z

Various fixes and wording clarifications to the sections discussing parameters.

schema changes are included in this pull request

handrews

@karenetheridge thanks for continuing to work through all of these details! Some good catches here. I hope you don't mind me commenting on the draft as it sounds like you are adding more rather than likely to change what you have already posted. Let me know if you would prefer me to wait in the future.

I have a few questions and possible suggestions, and one very reluctant "it's not what I would do but it's what was decided" objection.

src/oas.md

handrews · 2025-11-17T21:35:25Z

src/oas.md

 #### Fixed Fields

-The rules for serialization of the parameter are specified in one of two ways.
+The rules for serialization and deserialization of the parameter are specified in one of two ways.


I think in other places we have used "serialization and parsing" or "parsing and serialization." Do you think "deserialization" is a better term here? Is there a distinction between that and "parsing"? I have no idea what the answer is, I either copied "parsing" or picked it without much thought, so I'm open to changing it as long as we're consistent.

I searched the document and found that "deserialize" was used more often than "parse". I've standardized on the former in my implementation (after waffling a few times) as I think the symmetry makes more sense. Also I think "parse" is a little more vague -- you parse a string for any number of reasons, but what we're really doing here when we parse a parameter string is deserializing it into the json document model so we can then validate it against a json schema, or pass it to the user application in a format closer to its final form.

I searched the document and found that "deserialize" was used more often than "parse".

I doublechecked this assertion and it's false. We talk a lot about "parsing an OAD", and that's definitely the correct language there, but we say both "parse a parameter" and "deserialize a parameter".

I think I still prefer "deserialize" for its extra specificity though, when it is applicable -- an OAD is parsed to interpret its rules, and parts of an HTTP message are deserialized to be applied against the OAD rules.

handrews · 2025-11-17T21:55:25Z

src/oas.md

-| form | false | <span style="white-space: nowrap;">color=</span> | <span style="white-space: nowrap;">color=blue</span> | <span style="white-space: nowrap;">color=blue,black,brown</span> | <span style="white-space: nowrap;">color=R,100,G,200,B,150</span> |
-| form | true | <span style="white-space: nowrap;">color=</span> | <span style="white-space: nowrap;">color=blue</span> | <span style="white-space: nowrap;">color=blue&color=black&color=brown</span> | <span style="white-space: nowrap;">R=100&G=200&B=150</span> |
-| spaceDelimited</span> | false | _n/a_ | _n/a_ | <span style="white-space: nowrap;">color=blue%20black%20brown</span> | <span style="white-space: nowrap;">color=R%20100%20G%20200%20B%20150</span> |
+| form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 |
+| form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150 |
+| spaceDelimited | false | _n/a_ | _n/a_ | color=blue%20black%20brown | color=R%20100%20G%20200%20B%20150 |


My recollection is that we need these because otherwise the text will wrap at = and/or & without this, but I'm not at all certain. I tried to build locally to check but I'm having problems with that. Have you verified that it won't wrap without this?

It doesn't appear that there are any characters in the examples that would cause a wrap now, but a check should be done on the final copy before merging -- what's the process for that? I can look at the rendered document on github but that's not the same processing that our publication process uses for html generation.

src/oas.md

src/schemas/validation/schema.yaml

this was added in commit 9739dfe, but now that the leading "?" has been removed, this is no longer needed

..such as an empty array or object

karenetheridge · 2026-01-27T00:39:51Z

Force-pushing a new version after checking all commits; more test cases have been added for the schema changes.

karenetheridge · 2026-01-27T01:13:05Z

As this PR contains some fixes to things that are incorrect, IMO those commits at least should be backported to 3.2 and 3.1.

namely: in=path, in=query, in=cookie+style=form, but not in=header, in=querystring or in=cookie+style=cookie and not in encoding objects where contentType is used (none of style, explode, allowReserved are present) this brings in some work that didn't get merged in OAI#4904 ..and also fixes a bad $ref URI

… objects - explode defaults were wrong for in: cookie, style: cookie, and for encoding object - allowReserved defaults were wrong for encoding object in parameter objects: - explode: always false for "in: path", "in: header" - explode: always true for "in: cookie" (both "style: form" and "style: cookie" default to "explode: true") - explode: only true for "in: query" when "style: form" (the default style for this location) in encoding objects: - style: default is "form", but only when "explode" or "allowReserved" are present - explode: default is true when "style: form" (the default style) and otherwise false, and not included at all unless "style" or "allowReserved" are present - allowReserved: default is false, but only when "style" or "explode" are present that is: when none of style, explode or allowReserved are present, "contentType" is used (or a default is calculated), so none of style, explode or allowReserved shall have default values

…ll defaults omitted tested with: $ openapi-validate --with-defaults tests/schema/pass/style-defaults.yaml { "defaults" : { "/components/mediaTypes/encoding_object_defaults/encoding/allowReserved/explode" : true, "/components/mediaTypes/encoding_object_defaults/encoding/allowReserved/style" : "form", "/components/mediaTypes/encoding_object_defaults/encoding/explode/allowReserved" : false, "/components/mediaTypes/encoding_object_defaults/encoding/explode/style" : "form", "/components/mediaTypes/encoding_object_defaults/encoding/style_form/allowReserved" : false, "/components/mediaTypes/encoding_object_defaults/encoding/style_form/explode" : true, "/components/mediaTypes/encoding_object_defaults/encoding/style_spaceDelimited/allowReserved" : false, "/components/mediaTypes/encoding_object_defaults/encoding/style_spaceDelimited/explode" : false, "/components/parameters/cookie_cookie/deprecated" : false, "/components/parameters/cookie_cookie/explode" : true, "/components/parameters/cookie_cookie/required" : false, "/components/parameters/cookie_form/allowReserved" : false, "/components/parameters/cookie_form/deprecated" : false, "/components/parameters/cookie_form/explode" : true, "/components/parameters/cookie_form/required" : false, "/components/parameters/cookie_form/style" : "form", "/components/parameters/cookie_media_type/deprecated" : false, "/components/parameters/cookie_media_type/required" : false, "/components/parameters/header/allowReserved" : false, "/components/parameters/header/deprecated" : false, "/components/parameters/header/explode" : false, "/components/parameters/header/style" : "simple", "/components/parameters/path_label/allowReserved" : false, "/components/parameters/path_label/deprecated" : false, "/components/parameters/path_label/explode" : false, "/components/parameters/path_matrix/allowReserved" : false, "/components/parameters/path_matrix/deprecated" : false, "/components/parameters/path_matrix/explode" : false, "/components/parameters/path_media_type/deprecated" : false, "/components/parameters/path_simple/allowReserved" : false, "/components/parameters/path_simple/deprecated" : false, "/components/parameters/path_simple/explode" : false, "/components/parameters/path_simple/style" : "simple", "/components/parameters/query_deepObject/allowEmptyValue" : false, "/components/parameters/query_deepObject/allowReserved" : false, "/components/parameters/query_deepObject/deprecated" : false, "/components/parameters/query_deepObject/explode" : false, "/components/parameters/query_deepObject/required" : false, "/components/parameters/query_form/allowEmptyValue" : false, "/components/parameters/query_form/allowReserved" : false, "/components/parameters/query_form/deprecated" : false, "/components/parameters/query_form/explode" : true, "/components/parameters/query_form/required" : false, "/components/parameters/query_form/style" : "form", "/components/parameters/query_media_type/allowEmptyValue" : false, "/components/parameters/query_media_type/deprecated" : false, "/components/parameters/query_media_type/required" : false, "/components/parameters/query_pipeDelimited/allowEmptyValue" : false, "/components/parameters/query_pipeDelimited/allowReserved" : false, "/components/parameters/query_pipeDelimited/deprecated" : false, "/components/parameters/query_pipeDelimited/explode" : false, "/components/parameters/query_pipeDelimited/required" : false, "/components/parameters/query_spaceDelimited/allowEmptyValue" : false, "/components/parameters/query_spaceDelimited/allowReserved" : false, "/components/parameters/query_spaceDelimited/deprecated" : false, "/components/parameters/query_spaceDelimited/explode" : false, "/components/parameters/query_spaceDelimited/required" : false, "/jsonSchemaDialect" : "https://spec.openapis.org/oas/3.2/dialect/WORK-IN-PROGRESS", "/servers" : [ { "url" : "/" } ] }, "valid" : true } (executable is part of https://github.com/karenetheridge/OpenAPI-Modern)

..and remove example that is specific to a particular style, explode and schema type configuration

ralfhandl · 2026-01-29T08:58:24Z

src/oas.md

 ```

-This example is equivalent to RFC6570's `{?foo*,bar}`, and **NOT** `{?foo*}{&bar}`. The latter is problematic because if `foo` is not defined, the result will be an invalid URI.
+This example is equivalent to RFC6570's `{?foo*,bar}`, and **NOT** `{?foo*}{&bar}`. The latter is problematic because if `foo` is not defined (see [RFC6570 §3.2](https://www.rfc-editor.org/rfc/rfc6570#section-3.2) ) for details on what is considered undefined), the result will be an invalid URI.


Suggested change

This example is equivalent to RFC6570's `{?foo*,bar}`, and **NOT** `{?foo*}{&bar}`. The latter is problematic because if `foo` is not defined (see [RFC6570 §3.2](https://www.rfc-editor.org/rfc/rfc6570#section-3.2) ) for details on what is considered undefined), the result will be an invalid URI.

This example is equivalent to RFC6570's `{?foo*,bar}`, and **NOT** `{?foo*}{&bar}`. The latter is problematic because if `foo` is not defined (see [RFC6570 §3.2](https://www.rfc-editor.org/rfc/rfc6570#section-3.2) for details on what is considered undefined), the result will be an invalid URI.

ralfhandl · 2026-01-29T09:08:27Z

tests/schema/pass/parameter-object-examples.yaml

        in: header
        description: token to be passed as a header
        required: true
+        explode: false


Is there another test case showing that explode is not suddenly required here?

In general I would prefer not changing existing "pass" test cases and instead add new ones for testing additional allowed variations.

Refactorings combined with changes to existing test cases make me very uneasy.

I'll check why I added these; they are not required. I think it was to show that they were permitted (did not cause an error).

Pass test cases both with and without explode would be nice.

ralfhandl · 2026-01-29T09:13:41Z

tests/schema/fail/header-object-allowReserved.yaml

+      schema:
+        type: array
+      style: simple
+      explode: true


Suggested change

explode: true

I recommend removing this line: just the bare required minimum plus one forbidden thing to make the test case fail.

ralfhandl · 2026-01-30T07:21:01Z

tests/schema/pass/parameter-object-examples.yaml

        in: header
        description: token to be passed as a header
        required: true
+        explode: false


Pass test cases both with and without explode would be nice.

karenetheridge requested review from a team as code owners November 15, 2025 22:47

karenetheridge marked this pull request as draft November 15, 2025 22:47

karenetheridge force-pushed the ether/3.3-parameter-styles-more branch 3 times, most recently from 490500a to 2eed149 Compare November 15, 2025 23:29

handrews reviewed Nov 17, 2025

View reviewed changes

karenetheridge mentioned this pull request Dec 25, 2025

Fix typos and formatting #5170

Merged

1 task

karenetheridge mentioned this pull request Jan 26, 2026

Parsing of "in: query" parameters not clearly described #5188

Open

karenetheridge added 4 commits January 26, 2026 16:16

remove unneeded span markup

83ef7a0

this was added in commit 9739dfe, but now that the leading "?" has been removed, this is no longer needed

"undefined" in URI Templates is not just null, but can be other things

37b058d

..such as an empty array or object

the schema isn't just for specifying the expected type

b55b141

as per section 4.8.2, path parameter names cannot contain braces

bcdfd40

karenetheridge force-pushed the ether/3.3-parameter-styles-more branch from 6050bd6 to 423d8d3 Compare January 27, 2026 00:40

karenetheridge marked this pull request as ready for review January 27, 2026 00:40

karenetheridge force-pushed the ether/3.3-parameter-styles-more branch from 423d8d3 to 1372357 Compare January 27, 2026 01:02

karenetheridge force-pushed the ether/3.3-parameter-styles-more branch 2 times, most recently from 685302e to 7de9fda Compare January 27, 2026 01:31

karenetheridge added 6 commits January 26, 2026 17:50

fix broken examples

c564b80

mention deserialization too

e6cc2e0

specify how query parameters are added to the URL

6603f70

..and remove example that is specific to a particular style, explode and schema type configuration

karenetheridge force-pushed the ether/3.3-parameter-styles-more branch from 185f7d4 to 6603f70 Compare January 27, 2026 01:52

miqui approved these changes Jan 27, 2026

View reviewed changes

karenetheridge mentioned this pull request Jan 28, 2026

Open Community (TDC) Meeting, Thursday 29 January 2026 #5182

Open

ralfhandl requested changes Jan 29, 2026

View reviewed changes

ralfhandl reviewed Jan 30, 2026

View reviewed changes

	This example is equivalent to RFC6570's `{?foo,bar}`, and NOT* `{?foo*}{&bar}`. The latter is problematic because if `foo` is not defined (see [RFC6570 §3.2](https://www.rfc-editor.org/rfc/rfc6570#section-3.2) ) for details on what is considered undefined), the result will be an invalid URI.
	This example is equivalent to RFC6570's `{?foo,bar}`, and NOT* `{?foo*}{&bar}`. The latter is problematic because if `foo` is not defined (see [RFC6570 §3.2](https://www.rfc-editor.org/rfc/rfc6570#section-3.2) for details on what is considered undefined), the result will be an invalid URI.

v3.3: edits to parameter sections #5122

Are you sure you want to change the base?

v3.3: edits to parameter sections #5122

Conversation

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

Uh oh!

Uh oh!

handrews left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

karenetheridge commented Jan 27, 2026

Uh oh!

karenetheridge commented Jan 27, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ralfhandl Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

karenetheridge commented Nov 15, 2025 •

edited

Loading

ralfhandl Jan 29, 2026 •

edited

Loading