Reorganize multipart/form-data guidance (3.1.1 port of 3923 6/6, 3929)

This organizes and streamlines the guidance on multipart
that was incorporated from the Media Type Object.

Lots of duplication has been removed, and the examples
reworked to show distinct use cases.

Author: handrews

versions/3.1.1.md

@@ -1805,19 +1805,7 @@ However, this is not guaranteed, so it may be more interoperable to keep the pad
 
 ##### Encoding `multipart` Media Types
 
-It is common to use `multipart/form-data` as a `Content-Type` when transferring request bodies to operations.  In contrast to 2.0, a `schema` is REQUIRED to define the input parameters to the operation when using `multipart` content.  This supports complex structures as well as supporting mechanisms for multiple file uploads.
-
-In a `multipart/form-data` request body, each schema property, or each element of a schema array property, takes a section in the payload with an internal header as defined by [RFC7578](https://tools.ietf.org/html/rfc7578). The serialization strategy for each property of a `multipart/form-data` request body can be specified in an associated [`Encoding Object`](#encodingObject).
-
-When passing in `multipart` types, boundaries MAY be used to separate sections of the content being transferred – thus, the following default `Content-Type`s are defined for `multipart`:
-
-* If the property is a primitive, or an array of primitive values, the default Content-Type is `text/plain`
-* If the property is complex, or an array of complex values, the default Content-Type is `application/json`
-* If the property is a `type: string` with a `contentEncoding`, the default Content-Type is `application/octet-stream`
-
-Per the JSON Schema specification, `contentMediaType` without `contentEncoding` present is treated as if `contentEncoding: identity` were present.  While useful for embedding text documents such as `text/html` into JSON strings, it is not useful for a `multipart/form-data` part, as it just causes the document to be treated as `text/plain` instead of its actual media type.  Use the Encoding Object without `contentMediaType` if no `contentEncoding` is required.
-
-Note that only `multipart/*` media types with named parts can be described as shown here.  Note also that while `multipart/form-data` originally defined a per-part `Content-Transfer-Encoding` header that could indicate base64 encoding (`contentEncoding: base64`), it has been deprecated for use with HTTP as of [RFC7578](https://www.rfc-editor.org/rfc/rfc7578#section-4.7).
+It is common to use `multipart/form-data` as a `Content-Type` when transferring forms as request bodies.  In contrast to 2.0, a `schema` is REQUIRED to define the input parameters to the operation when using `multipart` content.  This supports complex structures as well as supporting mechanisms for multiple file uploads.
 
 The `form-data` disposition and its `name` parameter are mandatory for `multipart/form-data` ([RFC7578 §4.2](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.2)).
 Array properties are handled by applying the same `name` to multiple parts, as is recommended by [RFC7578 §4.3](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3) for supplying multiple values per form field.
@@ -1829,14 +1817,18 @@ 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 `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.
+
++Using `contentEncoding` for a multipart field is equivalent to specifying an [Encoding Object](#encodingObject) with a `headers` field containing `Content-Transfer-Encoding` with a schema that requires the value used in `contentEncoding`.
++If `contentEncoding` is used for a multipart field that has an Encoding Object with a `headers` field containing `Content-Transfer-Encoding` with a schema that disallows the value from `contentEncoding`, the result is undefined for serialization and parsing.
+
+Note that as stated in [Working with Binary Data](#binaryData), if the Encoding Object's `contentType`, whether set explicitly or implicitly through its default value rules, disagrees with the `contentMediaType` in a Schema Object, the `contentMediaType` SHALL be ignored.
+Because of this, and because the Encoding Object's `contentType` defaulting rules do not take the Schema Object's` contentMediaType` into account, the use of `contentMediaType` with an Encoding Object is NOT RECOMMENDED.
 
 See [Appendix E](#percentEncodingAndFormMediaTypes) for a detailed examination of percent-encoding concerns for form media types.
 
 ###### Example: Basic Multipart Form
 
-Examples:
+When the `encoding` attribute is _not_ used, the encoding is determined by the Encoding Object's defaults:
 
 ```yaml
 requestBody:
@@ -1846,27 +1838,16 @@ requestBody:
         type: object
         properties:
           id:
+            # default for primitives without a special format is text/plain
             type: string
             format: uuid
-          address:
-            # default Content-Type for objects is `application/json`
-            type: object
-            properties: {}
           profileImage:
-            # default Content-Type for properties with type string and a contentEncoding
-            # is `application/octet-stream`, so `image/png` must be set using contentMediaType
+            # default for string with binary format is `application/octet-stream`
             type: string
-            contentMediaType: image/png
-            contentEncoding: base64
-          children:
-            # 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
+            format: binary
           addresses:
-            # default Content-Type for arrays is based on the items subschema type, which
-            # is an object, producing a default of `application/json`
+            # default for arrays is based on the type in the `items`
+            # subschema, which is an object, so `application/json`
             type: array
             items:
               type: object
@@ -1875,7 +1856,8 @@ requestBody:
 
 ###### Example: Multipart Form with Encoding Objects
 
-`multipart/form-data` allows for binary parts:
+Using `encoding`, we can set more specific types for binary data, or non-JSON formats for complex values.
+We can also describe headers for each part:
 
 ```yaml
 requestBody:
@@ -1885,25 +1867,30 @@ requestBody:
         type: object
         properties:
           id:
-            # default is text/plain
+            # default is `text/plain`
             type: string
             format: uuid
-          address:
-            # default is application/json
-            type: object
-            properties: {}
-          historyMetadata:
-            # need to declare XML format!
-            description: metadata in XML format
-            type: object
-            properties: {}
-          profileImage: {}
+          addresses:
+            # default based on the `items` subschema would be
+            # `application/json`, but we want these address objects
+            # serialized as `application/xml` instead
+            description: addresses in XML format
+            type: array
+            items:
+                $ref: '#/components/schemas/Address'
+          profileImage:
+            # default is application/octet-stream, but we can declare
+            # a more specific image type or types
+            type: string
+            format: binary
       encoding:
-        historyMetadata:
+        addresses:
           # require XML Content-Type in utf-8 encoding
+          # This is applied to each address part corresponding
+          # to each address in he array
           contentType: application/xml; charset=utf-8
         profileImage:
-          # only accept png/jpeg
+          # only accept png or jpeg
           contentType: image/png, image/jpeg
           headers:
             X-Rate-Limit-Limit:
@@ -1914,7 +1901,7 @@ requestBody:
 
 ###### Example: Multipart Form with Multiple Files
 
-To upload multiple files, a `multipart` media type MUST be used:
+In accordance with [RFC7578 §4.3](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3), multiple files for a single form field are uploaded using the same name (`file` in this example) for each file's part:
 
 ```yaml
 requestBody: