Port remaining 3.0.4 fixes with adjustments for 3.1.1

versions/3.1.1.md

@@ -1751,17 +1751,20 @@ requestBody:
             type: object
             properties: {}
           profileImage:
-            # Content-Type for properties with type string and contentEncoding is `application/octet-stream`
+            # default Content-Type for properties with type string and a contentEncoding
+            # is `application/octet-stream`, so `image/png` must be set using contentMediaType
             type: string
             contentMediaType: image/png
             contentEncoding: base64
           children:
-            # default Content-Type for arrays is based on the _inner_ type (`text/plain` here)
+            # default Content-Type for arrays is based on the items subschema type, which
+            # is a string, producing a default of `text/plain`
             type: array
             items:
               type: string
           addresses:
-            # default Content-Type for arrays is based on the _inner_ type (object shown, so `application/json` in this example)
+            # default Content-Type for arrays is based on the items subschema type, which
+            # is an object, producing a default of `application/json`
             type: array
             items:
               type: object
@@ -1791,17 +1794,18 @@ Field Name | Type | Description
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
-The default values for `contentType` are as follows, where an _n/a_ in the `format` column means that the presence or value of `format` is irrelevant:
+The default values for `contentType` are as follows, where an _n/a_ in the `contentEncoding` column means that the presence or value of `contentEncoding` is irrelevant:
 
-Property `type` | Property `format` | Default `contentType`
-------------- | --------------- | ---------------------
-`string` | `binary` | `application/octet-stream`
-`string` | _none, or any except `binary`_ | `text/plain`
+Property `type` | Property `contentEncoding` | Default `contentType`
+--------------- | -------------------------- | ---------------------
+_absent_ | _n/a_ | `application/octet-stream`
+`string` | _present_ | `application/octet-stream`
+`string` | _absent_ | `text/plain`
 `number`, `integer`, or `boolean` | _n/a_ | `text/plain`
 `object` | _n/a_ | `application/json`
-`array` | _n/a_ | according to the `type` and `format` of the `items` schema
+`array` | _n/a_ | according to the `type` of the `items` schema
 
-Determining how to handle `null` values if `nullable: true` is present depends on how `null` values are being serialized.
+Determining how to handle a `type` value of `null` depends on how `null` values are being serialized.
 If `null` values are entirely omitted, then the `contentType` is irrelevant.
 See [Appendix B](#dataTypeConversion) for a discussion of data type conversion options.
 
@@ -1813,20 +1817,10 @@ Field Name | Type | Description
 <a name="encodingExplode"></a>explode | `boolean` | When this is true, property 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 properties this property has no effect. When [`style`](#encodingStyle) 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. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encodingContentType) (implicit or explicit) SHALL be ignored.
 <a name="encodingAllowReserved"></a>allowReserved | `boolean` | When this is true, parameter values are serialized  using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#autoid-20), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#autoid-13), 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 in the query string](https://datatracker.ietf.org/doc/html/rfc3986#autoid-24) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#usingRFC6570Implementations) and [E](#percentEncodingAndFormMediaTypes) for details. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded` or `multipart/form-data`. If a value is explicitly defined, then the value of [`contentType`](#encodingContentType) (implicit or explicit) SHALL be ignored.
 
-See also [Appendix C: Using RFC6570 Implementations](#usingRFC6570Implementations) for additional guidance.
-
-The role of `contentType` with `application/x-www-form-urlencoded` request bodies was not described in detail in version 3.0.3 and earlier of this specification.
-To match the intent of these fields and be compatible with version 3.1 of this specification, it is RECOMMENDED that whenever any of `style`, `explode`, or `allowReserved` are present with an explicit value:
-
-* The value of `contentType`, whether it is explicitly defined or has the default value, is to be ignored
-* If any of `style`, `explode`, or `allowReserved` are _not_ present with explicit values, then they are to be treated as if they were present with their default values
+See also [Appendix C: Using RFC6570 Implementations](#usingRFC6570Implementations) for additional guidance, including on difficulties caused by the interaction between RFC6570's percent-encoding rules and the `multipart/form-data` media type.
 
-However, if all three of `style`, `explode`, and `allowReserved` fields are absent, it is RECOMMENDED that:
-
-* All three keywords are to be entirely ignored, rather than treated as having their default values
-* Encoding is to be based on `contentType` alone, whether it is present with an explicit value or absent and treated as having its default value
-
-This makes the presence of at least one of `style`, `explode`, or `allowReserved` with an explicit value equivalent to using `schema` with `in: query` Parameter Objects, and their absence the equivalent of using `content`, but with the media type specified in `contentType` rather than through a Media Type Object.
+Note that the presence of at least one of `style`, `explode`, or `allowReserved` with an explicit value is equivalent to using `schema` with `in: query` Parameter Objects.
+The absence of all three of those fields is the equivalent of using `content`, but with the media type specified in `contentType` rather than through a Media Type Object.
 
 ###### Encoding `multipart` Media Types
 
@@ -1840,8 +1834,8 @@ It is not currently possible to correlate schema properties with unnamed, ordere
 Note that there are significant restrictions on what headers can be used with `multipart` media types in general ([RFC2046 §5.1](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1)) and `multi-part/form-data` in particular ([RFC7578 §4.8](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.8)).
 
 Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578 §4.7](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP.
-Using `format: byte` for a multipart field is equivalent to setting `Content-Transfer-Encoding: base64`.
-If `format: byte` is used along with setting a different `Content-Transfer-Encoding` value with the `headers` field, the result is undefined.
+Using `contentEncoding` is equivalent to setting `Content-Transfer-Encoding` to the same value.
+If `contentEncoding` is used along with setting a different `Content-Transfer-Encoding` value with the `headers` field, the result is undefined.
 
 ##### Encoding Object Example
 
@@ -4210,7 +4204,7 @@ To control the serialization of numbers, booleans, and `null` (or other values R
 The resulting strings would not require any further type conversion.
 
 The `format` keyword can assist in serialization.
-Some formats (such as `date-time` or `byte`) are unambiguous, while others (such as [`decimal`](https://spec.openapis.org/registry/format/decimal.html) in the [Format Registry](https://spec.openapis.org/registry/format/)) are less clear.
+Some formats (such as `date-time`) are unambiguous, while others (such as [`decimal`](https://spec.openapis.org/registry/format/decimal.html) in the [Format Registry](https://spec.openapis.org/registry/format/)) are less clear.
 However, care must be taken with `format` to ensure that the specific formats are supported by all relevant tools as unrecognized formats are ignored.
 
 Requiring input as pre-formatted, schema-validated strings also improves round-trip interoperability as not all programming languages and environments support the same data types.
@@ -4228,6 +4222,10 @@ Implementations of this specification MAY use an implementation of RFC6570 to pe
 
 Note that when using `style: form` RFC6570 expansion to produce an `application/x-www-form-urlencoded` HTTP message body, it is necessary to remove the `?` prefix that is produced to satisfy the URI query string syntax.
 
+When using `style` and similar keywords to produce a `multipart/form-data` body, the query string names are placed in the `name` parameter to the `Content-Disposition` part header, and the values are placed in the corresponding part body; the `?`, `=`, and `&` characters are not used.
+Note that while [RFC7578](https://datatracker.ietf.org/doc/html/rfc7578) allows using RFC3986 percent-encoding in "file names", it does not otherwise address the use of percent-encoding within the format.
+RFC7578 discusses character set and encoding issues for `multipart/form-data` in detail, and it is RECOMMENDED that OpenAPI Description authors read this guidance carefully before deciding to use RFC6570-based serialization with this media type.
+
 Note also that not all RFC6570 implementations support all four levels of operators, all of which are needed to fully support the OpenAPI Specification's usage.
 Using an implementation with a lower level of support will require additional manual construction of URI Templates to work around the limitations.
 
@@ -4459,8 +4457,9 @@ This will expand to the result:
 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`).
+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 (`contentEncoding: base64`).
 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.
+While `contentEncoding` also supports the `base64url` encoding, which is URL-safe, the header and cookie RFCs do not mention this encoding.
 
 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.