Reorganize multipart/form-data guidance

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.0.4.md

@@ -1731,15 +1731,7 @@ name=example&icon=iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAYAAABytg0kAAAAEklEQVQIW2P8z8
 
 ##### 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.
-
-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 `format: binary` or `format: byte` (aka a file object), the default Content-Type is `application/octet-stream`
-
-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 (`format: byte`), 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.
@@ -1758,7 +1750,7 @@ See [Appendix E](#percentEncodingAndFormMediaTypes) for a detailed examination o
 
 ###### Example: Basic Multipart Form
 
-Examples:
+When the `encoding` attribute is _not_ used, the encoding is determined by the Encoding Object's defaults:
 
 ```yaml
 requestBody:
@@ -1768,31 +1760,25 @@ 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 string/binary is `application/octet-stream`
+            # default for string with binary format is `application/octet-stream`
             type: string
             format: binary
-          children:
-            # default Content-Type for arrays is based on the `inner` type (text/plain here)
-            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 for arrays is based on the type in the `items`
+            # subschema, which is an object, so `application/json`
             type: array
             items:
               $ref: '#/components/schemas/Address'
 ```
 
 ###### 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:
@@ -1802,28 +1788,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: {}
+          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, need to declare an image type only!
+            # 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:
@@ -1834,7 +1822,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: