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

Reorganize and streamline form media type guidance (3.0.4) #3923

Merged
merged 7 commits into from
Jun 23, 2024
Merged
Changes from 1 commit
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
Prev Previous commit
Next Next commit
Add section titles, fix levels
Make the Parameter, Encoding, and Header Object fixed fields
section organization the same in all three places, with the
same levels of indentation.

Add more headings under the Encoding Object for guidance on
each form media type, and sub-headings for each example in
each of those sections.

This will make the diff for the next commit much more legible.
  • Loading branch information
handrews committed Jun 19, 2024
commit 7636fbf75c1d467aa7193c12e09d5cb9a83a3095
26 changes: 20 additions & 6 deletions versions/3.0.4.md
Original file line number Diff line number Diff line change
Expand Up @@ -1594,6 +1594,8 @@ In both cases, their order is implementation-defined.

See [Appendix E](#percentEncodingAndFormMediaTypes) for a detailed examination of percent-encoding concerns for form media types.

##### Fixed Fields

###### Common Fixed Fields

These fields MAY be used either with or without the RFC6570-style serialization fields defined in the next section below.
Expand All @@ -1619,7 +1621,7 @@ Determining how to handle `null` values if `nullable: true` is present depends o
If `null` values are entirely omitted, then the `contentType` is irrelevant.
See [Appendix B](#dataTypeConversion) for a discussion of data type conversion options.

##### Fixed Fields for RFC6570-style Serialization
###### Fixed Fields for RFC6570-style Serialization

Field Name | Type | Description
---|:---:|---
Expand All @@ -1642,11 +1644,15 @@ However, if all three of `style`, `explode`, and `allowReserved` fields are abse

This makes the presence of at least one of `style`, `explode`, or `allowReserved` with an explicit value equivalent to using `schema` with `in: query` Parameter Objects, and their absence the equivalent of using `content`, but with the media type specified in `contentType` rather than through a Media Type Object.

##### Encoding the `x-www-form-urlencoded` Media Type

See [Appendix E](#percentEncodingAndFormMediaTypes) for a detailed examination of percent-encoding concerns for form media types.

To submit content using form url encoding via [RFC1866](https://tools.ietf.org/html/rfc1866), the following
definition may be used:

###### Example: URL Encoded Form with JSON Values

```yaml
requestBody:
content:
Expand Down Expand Up @@ -1693,6 +1699,8 @@ Here is the `id` parameter (without `address`) serialized as `application/json`
id=%22f81d4fae-7dec-11d0-a765-00a0c91e6bf6%22
```

###### Example: URL Encoded Form with Binary Values

`application/x-www-form-urlencoded` is a text format, which requires base64-encoding any binary data:

```YAML
Expand All @@ -1713,7 +1721,7 @@ requestBody:
contentType: image/png, image/jpeg
```

###### Encoding `multipart` Media Types
##### 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.

Expand All @@ -1740,7 +1748,7 @@ If `format: byte` is used along with setting a different `Content-Transfer-Encod

See [Appendix E](#percentEncodingAndFormMediaTypes) for a detailed examination of percent-encoding concerns for form media types.

##### Encoding Object Example
###### Example: Basic Multipart Form

Examples:

Expand Down Expand Up @@ -1774,6 +1782,8 @@ requestBody:
$ref: '#/components/schemas/Address'
```

###### Example: Multipart Form with Encoding Objects

`multipart/form-data` allows for binary parts:

```yaml
Expand Down Expand Up @@ -1814,6 +1824,8 @@ requestBody:
type: integer
```

###### Example: Multipart Form with Multiple Files

To upload multiple files, a `multipart` media type MUST be used:

```yaml
Expand Down Expand Up @@ -2487,7 +2499,9 @@ The Header Object follows the structure of the [Parameter Object](#parameterObje
1. `in` MUST NOT be specified, it is implicitly in `header`.
1. All traits that are affected by the location MUST be applicable to a location of `header` (for example, [`style`](#parameterStyle)). This means that `allowEmptyValue` and `allowReserved` MUST NOT be used, and `style`, if used, MUST be limited to `simple`.

##### Common Fixed Fields
##### Fixed Fields

###### Common Fixed Fields

These fields MAY be used with either `content` or `schema`.

Expand All @@ -2499,7 +2513,7 @@ Field Name | Type | Description

This object MAY be extended with [Specification Extensions](#specificationExtensions).

##### Fixed Fields for use with `schema`
###### Fixed Fields for use with `schema`

For simpler scenarios, a [`schema`](#headerSchema) and [`style`](#headerStyle) can describe the structure and syntax of the header.
When `example` or `examples` are provided in conjunction with the `schema` object, the example MUST follow the prescribed serialization strategy for the header.
Expand All @@ -2519,7 +2533,7 @@ Field Name | Type | Description

See also [Appendix C: Using RFC6570 Implementations](#usingRFC6570Implementations) for additional guidance.

##### Fixed Fields for use with `content`
###### Fixed Fields for use with `content`

For more complex scenarios, the [`content`](#headerContent) property can define the media type and schema of the header, as well as give examples of its use.
Using `content` with a `text/plain` media type is RECOMMENDED for headers where the `schema` strategy is not appropriate.
Expand Down