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.

If we're going to switch that terminology, I would rather discuss it in its own GitHub discussion and come to something resembling a consensus, and then make that change across the document. We have enough consistency problems without doing this piecemeal. I would feel the same way about changing any existing "deserialize" wording. Let's make an intentional, group-approved choice of terminology and then implement it. But in this PR, let's keep the exising terminology.

It's not changing terminology; it's adding it -- the main intent here is to make clear that parameter declarations are used both in serializing, and in parsing/deserializing. I am mostly indifferent as to which of these two terms are used, but the point is that there is more going on than just serializing.

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

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.

src/oas.md

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

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

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

..such as an empty array or object

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

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

remove unneeded span markup

83ef7a0

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

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 3 times, most recently from 185f7d4 to 6603f70 Compare January 27, 2026 01:52

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

src/oas.md Outdated Show resolved Hide resolved

tests/schema/pass/parameter-object-examples.yaml Show resolved Hide resolved

ralfhandl reviewed Jan 30, 2026

View reviewed changes

tests/schema/fail/header-object-allowReserved.yaml Show resolved Hide resolved

tests/schema/pass/parameter-object-examples.yaml Show resolved Hide resolved

karenetheridge dismissed miqui’s stale review via fc13271 January 30, 2026 23:43

karenetheridge added 4 commits January 30, 2026 15:46

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

6ceabbe

..such as an empty array or object

the schema isn't just for specifying the expected type

ddcbf23

as per section 4.8.2, path parameter names cannot contain braces

5a50cf6

karenetheridge force-pushed the ether/3.3-parameter-styles-more branch from fc13271 to 5d3944f Compare January 30, 2026 23:48

karenetheridge requested review from handrews and ralfhandl January 30, 2026 23:49

karenetheridge requested a review from miqui January 30, 2026 23:49

karenetheridge added 5 commits January 31, 2026 10:59

fix broken examples

c6fcc2a

mention deserialization too

d1f6f7d

specify how query parameters are added to the URL

e332c52

..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 5d3944f to e332c52 Compare January 31, 2026 19:00

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!

handrews Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

karenetheridge Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

karenetheridge Jan 27, 2026

Choose a reason for hiding this comment

Uh oh!

handrews Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

karenetheridge Jan 31, 2026

Choose a reason for hiding this comment

Uh oh!

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!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

karenetheridge commented Nov 15, 2025 •

edited

Loading