From eb5f7afe595291271eb19048d65e820626d31fb5 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Fri, 31 Oct 2025 14:02:15 -0700 Subject: [PATCH 1/9] remove unneeded span markup this was added in commit 9739dfe5afa8, but now that the leading "?" has been removed, this is no longer needed --- src/oas.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/src/oas.md b/src/oas.md index da5374a3c3..0c4207a42c 100644 --- a/src/oas.md +++ b/src/oas.md @@ -923,15 +923,15 @@ The following table shows serialized examples, as would be shown with the `seria | label | true | _empty_ | .blue | .blue.black.brown | .R=100.G=200.B=150 | | simple | false | _empty_ | blue | blue,black,brown | R,100,G,200,B,150 | | simple | true | _empty_ | blue | blue,black,brown | R=100,G=200,B=150 | -| 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 | +| 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 | | spaceDelimited | true | _n/a_ | _n/a_ | _n/a_ | _n/a_ | -| pipeDelimited | false | _n/a_ | _n/a_ | color=blue%7Cblack%7Cbrown | color=R%7C100%7CG%7C200%7CB%7C150 | +| pipeDelimited | false | _n/a_ | _n/a_ | color=blue%7Cblack%7Cbrown | color=R%7C100%7CG%7C200%7CB%7C150 | | pipeDelimited | true | _n/a_ | _n/a_ | _n/a_ | _n/a_ | -| deepObject | _n/a_ | _n/a_ | _n/a_ | _n/a_ | color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150 | -| cookie | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 | -| cookie | true | color= | color=blue | color=blue; color=black; color=brown | R=100; G=200; B=150 | +| deepObject | _n/a_ | _n/a_ | _n/a_ | _n/a_ | color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150 | +| cookie | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 | +| cookie | true | color= | color=blue | color=blue; color=black; color=brown | R=100; G=200; B=150 | #### Extending Support for Querystring Formats From 1a4f571b6385a532aedc83b65932be1003ab709d Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Sat, 15 Nov 2025 14:24:44 -0800 Subject: [PATCH 2/9] add mention of an empty object here --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 0c4207a42c..0d7f0faf84 100644 --- a/src/oas.md +++ b/src/oas.md @@ -4909,7 +4909,7 @@ parameters: type: string ``` -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. The `&` prefix operator has no equivalent in the Parameter Object. Note that RFC6570 does not specify behavior for compound values beyond the single level addressed by `explode`. The result of using objects or arrays where no behavior is clearly specified for them is implementation-defined. From 9579b6f747714452969ce91a05f3f364f7fe073c Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Sat, 15 Nov 2025 14:25:30 -0800 Subject: [PATCH 3/9] for `in: query, style: form`, `explode: true` is the default --- src/oas.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/src/oas.md b/src/oas.md index 0d7f0faf84..c0fad87331 100644 --- a/src/oas.md +++ b/src/oas.md @@ -4964,9 +4964,9 @@ parameters: type: object additionalProperties: type: string - explode: true - name: words in: query + explode: false schema: type: array items: @@ -4994,16 +4994,14 @@ To do that, we'll add `allowReserved: true` to `formulas`, and change to `style: parameters: - name: formulas in: query + allowReserved: true schema: type: object additionalProperties: type: string - explode: true - allowReserved: true - name: words in: query style: spaceDelimited - explode: false schema: type: array items: From 5e186eec2e2ed4390677e3c9c8a577e6f0017a16 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Sat, 15 Nov 2025 14:30:33 -0800 Subject: [PATCH 4/9] specify how query parameters are added to the URL, and include a reference --- src/oas.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index c0fad87331..0ad6404f9d 100644 --- a/src/oas.md +++ b/src/oas.md @@ -769,7 +769,8 @@ See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detail There are five possible parameter locations specified by the `in` field: * 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); +MUST NOT appear in the same operation (or in the operation's path-item) as an `in: "querystring"` parameter. * querystring - A parameter that treats the entire URL query string as a value which MUST be specified using the `content` field, most often with media type `application/x-www-form-urlencoded` using [Encoding Objects](#encoding-object) in the same way as with request bodies of that media type; MUST NOT appear more than once, and MUST NOT appear in the same operation (or in the operation's path-item) as any `in: "query"` parameters. * header - Custom headers that are expected as part of the request. Note that [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-5.1) states header names are case-insensitive. * cookie - Used to pass a specific cookie value to the API. From 669a44eb5d2e26c25d0cb9669240c47a1960cdbf Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Sat, 15 Nov 2025 14:31:04 -0800 Subject: [PATCH 5/9] mention deserialization too --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 0ad6404f9d..b92d0db3a8 100644 --- a/src/oas.md +++ b/src/oas.md @@ -777,7 +777,7 @@ MUST NOT appear in the same operation (or in the operation's path-item) as an `i #### 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. Parameter Objects MUST include either a `content` field or a `schema` field, but not both. See [Appendix B](#appendix-b-data-type-conversion) for a discussion of converting values of various types to string representations. From 714ca48fd9054e1eee5c2025e26b0db1b139ec0f Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Sat, 15 Nov 2025 14:31:14 -0800 Subject: [PATCH 6/9] the schema isn't just for specifying the expected type --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index b92d0db3a8..3b835efcc3 100644 --- a/src/oas.md +++ b/src/oas.md @@ -821,7 +821,7 @@ In these cases, implementations MUST pass values through unchanged rather than a | style | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `"query"` - `"form"`; for `"path"` - `"simple"`; for `"header"` - `"simple"`; for `"cookie"` - `"form"` (for compatibility reasons; note that `style: "cookie"` SHOULD be used with `in: "cookie"`; see [Appendix D](#appendix-d-serializing-headers-and-cookies) for details). | | explode | `boolean` | When this is true, parameter values of type `array` or `object` generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters, or when [`style`](#parameter-style) is `"deepObject"`, this field has no effect. When `style` is `"form"` or `"cookie"`, the default value is `true`. For all other styles, the default value is `false`. | | allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are not allowed by the rules of the `in` destination or media type, or are [not allowed in the path by this specification](#path-templating); see [URL Percent-Encoding](#url-percent-encoding) for details. The default value is `false`. This field only applies to `in` and `style` values that automatically percent-encode. | -| schema | [Schema Object](#schema-object) | The schema defining the type used for the parameter. | +| schema | [Schema Object](#schema-object) | The schema defining the type and other constraints used for the parameter. | See also [Appendix C: Using RFC6570-Based Serialization](#appendix-c-using-rfc6570-based-serialization) for additional guidance. From 2152476f5f4fb8d3caf29c90ea3b75526381ea3e Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Sat, 15 Nov 2025 14:32:01 -0800 Subject: [PATCH 7/9] require documenting the implemented behaviour here --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 3b835efcc3..804486ea18 100644 --- a/src/oas.md +++ b/src/oas.md @@ -3073,7 +3073,7 @@ Serializing data into such formats requires either examining the schema-validate 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. Schema Objects that do not contain `type` MUST be considered to allow all types, regardless of which other keywords are present (e.g. `maximum` applies to numbers, but _does not_ require the instance to be a number). Implementations MAY inspect subschemas or possible reference targets of other keywords such as `oneOf` or `$dynamicRef`, but MUST NOT attempt to resolve ambiguities. From 2eed14926f3733087b21b6dcb14820dbcd438272 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Sat, 15 Nov 2025 14:34:08 -0800 Subject: [PATCH 8/9] as per section 4.8.2, path parameter names cannot contain braces --- src/schemas/validation/schema.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index bdc429c078..3f8976bb1f 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -439,6 +439,8 @@ $defs: const: path then: properties: + name: + pattern: '^[^{}]+$' style: default: simple enum: From 6050bd69abc606fb455cd9952d8f1e564bec2777 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Sat, 15 Nov 2025 21:19:24 -0800 Subject: [PATCH 9/9] fix typo in example --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 804486ea18..53ae8da532 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1071,7 +1071,7 @@ examples: dataValue: page: 4 pageSize: 50 - serializeValue: page=4&pageSize=50 + serializedValue: page=4&pageSize=50 ``` A complex parameter using `content` to define serialization, with multiple levels and types of examples shown to make the example usage options clear — note that `dataValue` is the same at both levels and does not need to be shown in both places in normal usage, but `serializedValue` is different: