multipart clarifications

Author: webron

versions/3.0.md

@@ -1298,7 +1298,7 @@ Field Name | Type | Description
 <a name="mediaTypeSchema"></a>schema | [Schema Object](#schemaObject) \| [Reference Object](#referenceObject) | The schema defining the type used for the request body.
 <a name="mediaTypeExample"></a>example | Any | Example of the media type.  The example object SHOULD be in the correct format as specified by the media type.  The `example` object is mutually exclusive of the `examples` object.  Furthermore, if referencing a `schema` which contains an example, the `example` value SHALL _override_ the example provided by the schema.
 <a name="mediaTypeExamples"></a>examples | Map[ `string`, [Example Object](#exampleObject) \| [Reference Object](#referenceObject)] | Examples of the media type.  Each example object SHOULD  match the media type and specified schema if present.  The `examples` object is mutually exclusive of the `example` object.  Furthermore, if referencing a `schema` which contains an example, the `examples` value SHALL _override_ the example provided by the schema.
-<a name="mediaTypeEncoding"></a>encoding | Map[`string`, [Encoding Object](#encodingObject)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHOULD only apply to `requestBody` objects when the content type is `multipart`.
+<a name="mediaTypeEncoding"></a>encoding | Map[`string`, [Encoding Object](#encodingObject)] | A map between a property name and its encoding information. The key, being the property name, MUST exist in the schema as a property. The encoding object SHALL only apply to `requestBody` objects when the content type is `multipart` or `x-www-form-urlencoded`.
 
 This object can be extended with [Specification Extensions](#specificationExtensions). 
 
@@ -1367,8 +1367,7 @@ application/json:
 
 ##### Considerations for File Uploads
 
-In contrast with the 2.0 specification, `file` input/output content in OpenAPI is 
-described with the same semantics as any other schema type. Specifically:
+In contrast with the 2.0 specification, `file` input/output content in OpenAPI is described with the same semantics as any other schema type. Specifically:
 
 ```yaml
 # content transferred with base64 encoding
@@ -1410,6 +1409,23 @@ requestBody:
         format: binary
 ```
 
+To upload multiple files, a `multipart` media type MUST be used:
+
+```yaml
+requestBody:
+  content:
+    multipart/form-data:
+      schema:
+        properties:
+          # The property name 'file' will be used for all files.
+          file:
+            type: array
+            items:
+              type: string
+              format: binary
+
+```
+
 ##### Support for x-www-form-urlencoded Request Bodies
 
 To submit content using form url encoding via [RFC1866](https://tools.ietf.org/html/rfc1866), the following
@@ -1433,7 +1449,7 @@ requestBody:
 
 In this example, the contents in the `requestBody` MUST be stringified per [RFC1866](https://tools.ietf.org/html/rfc1866/) when passed to the server.  In addition, the `address` field complex object will be stringified.
 
-When passing complex objects in the `x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the `parameterContent` section as `form`.
+When passing complex objects in the `x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the [`Encoding Object`](#encodingObject)'s [`style`](#encodingStyle) property as `form`.
 
 ##### Special Considerations for `multipart` Content
 
@@ -1488,10 +1504,10 @@ A single encoding definition applied to a single schema property.
 Field Name | Type | Description
 ---|:---:|---
 <a name="encodingContentType"></a>contentType | `string` | The Content-Type for encoding a specific property. Default value depends on the property type: for `string` with `format` being `binary` – `application/octet-stream`; for other primitive types – `text/plain`; for `object` - `application/json`; for `array` – the default is defined based on the inner type.
-<a name="encodingHeaders"></a>headers | Map[`string`, [Header Object](#headerObject)] | A string map allowing additional information to be provided as headers, for example `Content-Disposition`.  `Content-Type` is described separately and SHALL be ignored in this section.
-<a name="encodingStyle"></a>style | `string` | Describes how a specific property value will be serialized depending on its type.  See [Parameter Object](#parameterObject) for details on the [`style`](#parameterStyle) property. The behavior follows the same values as `query` parameters, including default values.
-<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`.
-<a name="encodingAllowReserved"></a>allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is `false`.
+<a name="encodingHeaders"></a>headers | Map[`string`, [Header Object](#headerObject)] | A string map allowing additional information to be provided as headers, for example `Content-Disposition`.  `Content-Type` is described separately and SHALL be ignored in this section. This property SHALL be ignored if the request body media type is not a `multipart`.
+<a name="encodingStyle"></a>style | `string` | Describes how a specific property value will be serialized depending on its type.  See [Parameter Object](#parameterObject) for details on the [`style`](#parameterStyle) property. The behavior follows the same values as `query` parameters, including default values. This property SHALL be ignored if the request body media type is not `x-www-form-urlencoded`.
+<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`. This property SHALL be ignored if the request body media type is not `x-www-form-urlencoded`.
+<a name="encodingAllowReserved"></a>allowReserved | `boolean` | Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-2.2) `:/?#[]@!$&'()*+,;=` to be included without percent-encoding. The default value is `false`. This property SHALL be ignored if the request body media type is not `x-www-form-urlencoded`.
 
 This object can be extended with [Specification Extensions](#specificationExtensions).