From 0a28d2db97a5d68871f5f458f13f23588a7ed205 Mon Sep 17 00:00:00 2001
From: "Henry H. Andrews" <andrews_henry@yahoo.com>
Date: Thu, 2 Mar 2023 11:01:53 -0800
Subject: [PATCH] Clarify the use of "binary" and "byte" formats

Add a brief explanation as a subsection of Data Types, and
update the relevant examples.  Specifically:

* Don't use `format: byte` for a whole message body
* Fix `multipart/mixed` example to be `multipart/form-data`
  (because `multipart/mixed` does not name its parts and
  therefore cannot be represented with an object schema)
* Add an `application/x-www-form-urlencoded` example,
  which is where `format: byte` needs to be used
---
 versions/3.0.4.md | 42 +++++++++++++++++++++++++++++++++---------
 1 file changed, 33 insertions(+), 9 deletions(-)

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.
 
+#### <a name="binaryData"></a>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.
 
 ### <a name="richText"></a>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
+```
+
 #### <a name="responsesObject"></a>Responses Object
 
 A container for the expected responses of an operation.