Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify the use of "binary" and "byte" formats #3187

Merged
merged 1 commit into from
Mar 11, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 33 additions & 9 deletions versions/3.0.4.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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:

Expand Down Expand Up @@ -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:
Expand Down Expand Up @@ -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.
Expand Down