v3.3: edits to parameter sections #5122

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

draft, as I may be adding more commits.

schema changes are included in this pull request

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

…rence

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.

handrews · 2025-11-17T17:46:15Z

src/oas.md


 * path - Used together with [Path Templating](#path-templating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`.
-* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`; MUST NOT appear in the same operation (or in the operation's path-item) as an `in: "querystring"` parameter.
+* query - Parameters that are appended to the URL with the `?` character (or to existing query parameters with the `&` character), as described by [RFC3986 section 3.4](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4);


Why the RFC3986 reference? That section does define the query component, but only vaguely alludes to key-value pairs and does not mention the & character at all. Technically RFC6570 is the most relevant specification defining the query string as produced by in: query, although not as produces by in: querystring, for which WHATWG URL is more relevant.

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.

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?

handrews · 2025-11-17T21:56:19Z

src/oas.md

 When inspecting schemas, given a starting point schema, implementations MUST examine that schema and all schemas that can be reached from it by following only `$ref` and `allOf` keywords.
 These schemas are guaranteed to apply to any instance.
-When searching schemas for `type`, if the `type` keyword's value is a list of types and the serialized value can be successfully parsed as more than one of the types in the list, and no other findable `type` keyword disambiguates the actual required type, the behavior is implementation-defined.
+When searching schemas for `type`, if the `type` keyword's value is a list of types and the serialized value can be successfully parsed as more than one of the types in the list, and no other findable `type` keyword disambiguates the actual required type, the behavior is implementation-defined and must be documented.


There was a debate in the Thursday meeting over documentation requirements like this, which I had put in a lot of places, and the consensus was not to include it. So I had to take it out, and we can only have language like this if we want to re-open that discussion in the Thursday call.

handrews · 2025-11-17T21:58:30Z

src/oas.md

    type: object
    additionalProperties:
      type: string
-  explode: true


Here I was trying to be unambiguous about the explode value rather than leaving it as the default, which can be confusing. I don't know that we need to keep what I was doing, I'm just explaining why it was there.

handrews · 2025-11-17T21:59:00Z

src/oas.md

-  explode: true
-  allowReserved: true
 - name: words
  in: query
  style: spaceDelimited
-  explode: false


Likewise here I was trying to show the explicit lack of difference between explode values that was clarified in 3.2. Likewise this is more of an explanation than a real objection.

handrews · 2025-11-17T22:49:28Z

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 (or the object has no properties), the result will be an invalid URI.


I remember wrestling with whether to get into this when I wrote this part. RFC6570's actual requirements are even more complex:

A variable defined as a list value is considered undefined if the
list contains zero members. A variable defined as an associative
array of (name, value) pairs is considered undefined if the array
contains zero members or if all member names in the array are
associated with undefined values.

I think I decided to not get into it here because of this normative reference in the Parameter Object section:

The undefined column replaces the empty column in previous versions of this specification in order to better align with [RFC6570] Section 2.3 terminology, which describes certain values including but not limited to null as “undefined” values with special handling; notably, the empty string is not undefined.

Perhaps a more general "see RFC6570 §3.2 for details on what is considered undefined" rather than trying to enumerate the conditions would be better? I do like the idea of making some note here that "undefined" is a complex concept.

handrews · 2025-11-17T22:53:47Z

src/schemas/validation/schema.yaml

            then:
              properties:
+                name:
+                  pattern: '^[^{}]+$'


Good catch on the braces. I don't think we actually forbid the empty string, though, so * instead of +? (We probably should forbid it, but I don't think we do).

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 2 times, most recently from 4f1638a to 490500a Compare November 15, 2025 23:28

karenetheridge added 8 commits November 15, 2025 15:29

remove unneeded span markup

eb5f7af

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

add mention of an empty object here

1a4f571

for in: query, style: form, explode: true is the default

9579b6f

specify how query parameters are added to the URL, and include a refe…

5e186ee

…rence

mention deserialization too

669a44e

the schema isn't just for specifying the expected type

714ca48

require documenting the implemented behaviour here

2152476

as per section 4.8.2, path parameter names cannot contain braces

2eed149

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

fix typo in example

6050bd6

handrews reviewed Nov 17, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

v3.3: edits to parameter sections #5122

v3.3: edits to parameter sections #5122

Uh oh!

karenetheridge commented Nov 15, 2025 •

edited

Loading

Uh oh!

handrews left a comment

Uh oh!

handrews Nov 17, 2025

Uh oh!

handrews Nov 17, 2025

Uh oh!

handrews Nov 17, 2025

Uh oh!

handrews Nov 17, 2025

Uh oh!

handrews Nov 17, 2025

Uh oh!

handrews Nov 17, 2025

Uh oh!

handrews Nov 17, 2025

Uh oh!

handrews Nov 17, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

v3.3: edits to parameter sections #5122

Are you sure you want to change the base?

v3.3: edits to parameter sections #5122

Uh oh!

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!

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!

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!

2 participants

karenetheridge commented Nov 15, 2025 •

edited

Loading