Warnings for header and cookie serialization (3.0.4)

versions/3.0.4.md

@@ -1044,7 +1044,6 @@ There are four possible parameter locations specified by the `in` field:
 * header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
 * cookie - Used to pass a specific cookie value to the API.
 
-
 ##### Fixed Fields
 
 The rules for serialization of the parameter are specified in one of two ways.
@@ -1063,12 +1062,16 @@ Field Name | Type | Description
 <a name="parameterDeprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
 <a name="parameterAllowEmptyValue"></a> allowEmptyValue | `boolean` | If `true`, clients MAY pass a zero-length string value in place of parameters that would otherwise be omitted entirely, which the server SHOULD interpret as the parameter being unused. Default value is `false`. If [`style`](#parameterStyle) is used, and if behavior is `n/a` (cannot be serialized), the value of `allowEmptyValue` SHALL be ignored. Interactions between this field and the parameter's [Schema Object](#schemaObject) are implementation-defined. This field is valid only for `query` parameters. Use of this property is NOT RECOMMENDED, and it is likely to be removed in a later revision.
 
+Note that while `"Cookie"` as a `name` is not forbidden with `in: header`, the effect of defining a cookie parameter that way is undefined; use `in: cookie` instead.
+
 ###### Fixed Fields for use with `schema`
 
 For simpler scenarios, a [`schema`](#parameterSchema) and [`style`](#parameterStyle) can describe the structure and syntax of the parameter.
 When `example` or `examples` are provided in conjunction with the `schema` object, the example SHOULD match the specified schema and follow the prescribed serialization strategy for the parameter.
 The `example` and `examples` fields are mutually exclusive, and if either is present it SHALL _override_ any `example` in the schema.
 
+Serializing with `schema` is NOT RECOMMENDED for `in: cookie` parameters, `in: header` parameters that use HTTP header parameters (name=value pairs following a `;`) in their values, or `in: header` parameters where values might have non-URL-safe characters; see [Appendix D](#serializingHeadersAndCookies) for details.
+
 Field Name | Type | Description
 ---|:---:|---
 <a name="parameterStyle"></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`.
@@ -1080,14 +1083,16 @@ Field Name | Type | Description
 
 See also [Appendix C: Using RFC6570 Implementations](#usingRFC6570Implementations) for additional guidance.
 
-###### Fixed Fields and considerations for use with `content`
+###### Fixed Fields for use with `content`
 
 For more complex scenarios, the [`content`](#parameterContent) property can define the media type and schema of the parameter, as well as give examples of its use.
+Using `content` with a `text/plain` media type is RECOMMENDED for `in: header` and `in: cookie` parameters where the `schema` strategy is not appropriate.
 
 Field Name | Type | Description
 ---|:---:|---
 <a name="parameterContent"></a>content | Map[`string`, [Media Type Object](#mediaTypeObject)] | A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.
 
+
 ##### Style Values
 
 In order to support common ways of serializing simple parameters, a set of `style` values are defined.
@@ -3941,4 +3946,23 @@ This will expand to the result:
 
 ## <a name="serializingHeadersAndCookies"></a>Appendix D: Serializing Headers and Cookies
 
+RFC6570's percent-encoding behavior is not always appropriate for `in: header` and `in: cookie` parameters.
+In many cases, it is more appropriate to use `content` with a media type such as `text/plain` and require the application to assemble the correct string.
+
+For both cookies ([RFC6265](https://www.rfc-editor.org/rfc/rfc6265)) and HTTP headers using the structured fields ([RFC8941](https://www.rfc-editor.org/rfc/rfc8941)) syntax, non-ASCII content is handled using base64 encoding (`format: byte`).
+Note that the standard base64 encoding alphabet includes non-URL-safe characters that are percent-encoded by RFC6570 expansion; serializing values through both encodings is NOT RECOMMENDED.
+
+Most HTTP headers predate the structured field syntax, and a comprehensive assessment of their syntax and encoding rules is well beyond the scope of this specification.
+While [RFC8187](https://www.rfc-editor.org/rfc/rfc8187) recommends percent-encoding HTTP field (header or trailer) parameters, these parameters appear after a `;` character.
+With `style: simple`, that delimiter would itself be percent-encoded, violating the general HTTP field syntax.
+
+Using `style: form` with `in: cookie` is ambiguous for a single value, and incorrect for multiple values.
+This is true whether the multiple values are the result of using `explode: true` or not.
+
+This style is specified to be equivalent to RFC6570 form expansion which includes the `?` character (see Appendix C for more details), which is not part of the cookie syntax.
+However, examples of this style in past versions of this specification have not included the `?` prefix, suggesting that the comparison is not exact.
+Because implementations that rely on an RFC6570 implementation and those that perform custom serialization based on the style example will produce different results, it is implementation-defined as to which of the two results is correct.
+
+For multiple values, `style: form` is always incorrect as name=value pairs in cookies are delimited by `; ` (a semicolon followed by a space character) rather than `&`.
+
 ## <a name="percentEncodingAndFormMediaTypes"></a>Appendix E: Percent-Encoding and Form Media Types