From 17d36668541bc76894aabd3dfff1284e19d15a4a Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 5 Jun 2025 16:11:46 -0400 Subject: [PATCH 1/2] fix: adds missing schema reference as an option of parameter schema and media type schema/item schema Signed-off-by: Vincent Biret --- src/oas.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/oas.md b/src/oas.md index 3df5572368..ef2766b6e8 100644 --- a/src/oas.md +++ b/src/oas.md @@ -993,7 +993,7 @@ Serializing with `schema` is NOT RECOMMENDED for `in: "cookie"` parameters, `in: | 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"`. | | 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 this field has no effect. When [`style`](#parameter-style) is `"form"`, the default value is `true`. For all other styles, the default value is `false`. Note that despite `false` being the default for `deepObject`, the combination of `false` with `deepObject` is undefined. | | 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 Appendices [C](#appendix-c-using-rfc6570-based-serialization) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. The default value is `false`. | -| schema | [Schema Object](#schema-object) | The schema defining the type used for the parameter. | +| schema | [Schema Object](#schema-object) \| [Reference Object](#reference-object) | The schema defining the type used for the parameter. | | example | Any | Example of the parameter's potential value; see [Working With Examples](#working-with-examples). | | examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the parameter's potential value; see [Working With Examples](#working-with-examples). | @@ -1249,8 +1249,8 @@ See [Working With Examples](#working-with-examples) for further guidance regardi | Field Name | Type | Description | | ---- | :----: | ---- | -| schema | [Schema Object](#schema-object) | A schema describing the complete content of the request, response, parameter, or header. | -| itemSchema | [Schema Object](#schema-object) | A schema describing each item within a [sequential media type](#sequential-media-types). | +| schema | [Schema Object](#schema-object) \| [Reference Object](#reference-object) | A schema describing the complete content of the request, response, parameter, or header. | +| itemSchema | [Schema Object](#schema-object) \| [Reference Object](#reference-object) | A schema describing each item within a [sequential media type](#sequential-media-types). | | example | Any | Example of the media type; see [Working With Examples](#working-with-examples). | | examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the media type; see [Working With Examples](#working-with-examples). | | encoding | Map[`string`, [Encoding Object](#encoding-object)] | A map between a property name and its encoding information, as defined under [Encoding Usage and Restrictions](#encoding-usage-and-restrictions). The `encoding` field SHALL only apply when the media type is `multipart` or `application/x-www-form-urlencoded`. If no Encoding Object is provided for a property, the behavior is determined by the default values documented for the Encoding Object. | From dff699ba8bb057d8956fe374e87c5f0bba841c9c Mon Sep 17 00:00:00 2001 From: Vincent Biret Date: Thu, 5 Jun 2025 16:30:38 -0400 Subject: [PATCH 2/2] fix: removes the reference object from headers schema Signed-off-by: Vincent Biret --- src/oas.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/oas.md b/src/oas.md index ef2766b6e8..e1637a1cf0 100644 --- a/src/oas.md +++ b/src/oas.md @@ -993,7 +993,7 @@ Serializing with `schema` is NOT RECOMMENDED for `in: "cookie"` parameters, `in: | 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"`. | | 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 this field has no effect. When [`style`](#parameter-style) is `"form"`, the default value is `true`. For all other styles, the default value is `false`. Note that despite `false` being the default for `deepObject`, the combination of `false` with `deepObject` is undefined. | | 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 Appendices [C](#appendix-c-using-rfc6570-based-serialization) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. The default value is `false`. | -| schema | [Schema Object](#schema-object) \| [Reference Object](#reference-object) | The schema defining the type used for the parameter. | +| schema | [Schema Object](#schema-object) | The schema defining the type used for the parameter. | | example | Any | Example of the parameter's potential value; see [Working With Examples](#working-with-examples). | | examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the parameter's potential value; see [Working With Examples](#working-with-examples). | @@ -1249,8 +1249,8 @@ See [Working With Examples](#working-with-examples) for further guidance regardi | Field Name | Type | Description | | ---- | :----: | ---- | -| schema | [Schema Object](#schema-object) \| [Reference Object](#reference-object) | A schema describing the complete content of the request, response, parameter, or header. | -| itemSchema | [Schema Object](#schema-object) \| [Reference Object](#reference-object) | A schema describing each item within a [sequential media type](#sequential-media-types). | +| schema | [Schema Object](#schema-object) | A schema describing the complete content of the request, response, parameter, or header. | +| itemSchema | [Schema Object](#schema-object) | A schema describing each item within a [sequential media type](#sequential-media-types). | | example | Any | Example of the media type; see [Working With Examples](#working-with-examples). | | examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the media type; see [Working With Examples](#working-with-examples). | | encoding | Map[`string`, [Encoding Object](#encoding-object)] | A map between a property name and its encoding information, as defined under [Encoding Usage and Restrictions](#encoding-usage-and-restrictions). The `encoding` field SHALL only apply when the media type is `multipart` or `application/x-www-form-urlencoded`. If no Encoding Object is provided for a property, the behavior is determined by the default values documented for the Encoding Object. | @@ -2433,7 +2433,7 @@ The `example` and `examples` fields are mutually exclusive, and if either is pre | ---- | :----: | ---- | | style | `string` | Describes how the header value will be serialized. The default (and only legal value for headers) is `"simple"`. | | explode | `boolean` | When this is true, header values of type `array` or `object` generate a single header whose value is a comma-separated list of the array items or key-value pairs of the map, see [Style Examples](#style-examples). For other data types this field has no effect. The default value is `false`. | -| schema | [Schema Object](#schema-object) \| [Reference Object](#reference-object) | The schema defining the type used for the header. | +| schema | [Schema Object](#schema-object) | The schema defining the type used for the header. | | example | Any | Example of the header's potential value; see [Working With Examples](#working-with-examples). | | examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the header's potential value; see [Working With Examples](#working-with-examples). |