diff --git a/versions/3.0.4.md b/versions/3.0.4.md
index 30526b2dc5..63689beeb3 100644
--- a/versions/3.0.4.md
+++ b/versions/3.0.4.md
@@ -162,12 +162,20 @@ The formats defined by the OAS are:
`integer` | `int64` | signed 64 bits (a.k.a long)
`number` | `float` | |
`number` | `double` | |
-`string` | `byte` | base64 encoded characters
+`string` | `byte` | base64 encoded characters - [RFC4648](https://www.rfc-editor.org/rfc/rfc4648#section-4)
`string` | `binary` | any sequence of octets
`string` | `date` | As defined by `full-date` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
`string` | `date-time` | As defined by `date-time` - [RFC3339](https://xml2rfc.ietf.org/public/rfc/html/rfc3339.html#anchor14)
`string` | `password` | A hint to UIs to obscure input.
+#### Working With Binary Data
+
+Two formats, `binary` and `byte`, describe different ways to work with binary data:
+
+* `binary` is used where unencoded binary data is allowed, such as when sending a binary payload as an HTTP message body, or as part of a `multipart/*` payload that allows binary parts
+* `byte` is used where binary data is embedded in a text-only format such as `application/json` or `application/x-www-form-urlencoded`
+
+Note that the encoding indicated by `byte`, which inflates the size of data in order to represent it as 7-bit ASCII text, is unrelated to HTTP's `Content-Encoding` header, which indicates whether and how a message body has been compressed.
### Rich Text Formatting
Throughout the specification `description` fields are noted as supporting CommonMark markdown formatting.
@@ -1440,13 +1448,6 @@ application/json:
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
-schema:
- type: string
- format: byte
-```
-
```yaml
# content transferred in binary (octet-stream):
schema:
@@ -1537,6 +1538,7 @@ When passing in `multipart` types, boundaries MAY be used to separate sections o
* 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).
Examples:
@@ -1589,10 +1591,12 @@ This object MAY be extended with [Specification Extensions](#specificationExtens
##### Encoding Object Example
+`multipart/form-data` allows for binary parts:
+
```yaml
requestBody:
content:
- multipart/mixed:
+ multipart/form-data:
schema:
type: object
properties:
@@ -1627,6 +1631,26 @@ requestBody:
type: integer
```
+`application/x-www-form-urlencoded` is a text format, which requires base64-encoding any binary data:
+
+```YAML
+requestBody:
+ content:
+ application/x-www-form-urlencoded:
+ schema:
+ type: object
+ properties:
+ name:
+ type: string
+ icon:
+ # default is text/plain, need to declare an image type only!
+ type: string
+ format: byte
+ encoding:
+ icon:
+ contentType: image/png, image/jpeg
+```
+
#### Responses Object
A container for the expected responses of an operation.