Skip to content

Commit 9e07940

Browse files
committed
Add section titles, fix levels (3.1.1 port of 3923 2/6)
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.
1 parent 34cc0cb commit 9e07940

1 file changed

Lines changed: 20 additions & 6 deletions

File tree

versions/3.1.1.md

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1673,6 +1673,8 @@ In both cases, their order is implementation-defined.
16731673

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

1676+
##### Fixed Fields
1677+
16761678
###### Common Fixed Fields
16771679

16781680
These fields MAY be used either with or without the RFC6570-style serialization fields defined in the next section below.
@@ -1699,7 +1701,7 @@ Determining how to handle a `type` value of `null` depends on how `null` values
16991701
If `null` values are entirely omitted, then the `contentType` is irrelevant.
17001702
See [Appendix B](#dataTypeConversion) for a discussion of data type conversion options.
17011703

1702-
##### Fixed Fields for RFC6570-style Serialization
1704+
###### Fixed Fields for RFC6570-style Serialization
17031705

17041706
Field Name | Type | Description
17051707
---|:---:|---
@@ -1712,11 +1714,15 @@ See also [Appendix C: Using RFC6570 Implementations](#usingRFC6570Implementation
17121714
Note that the presence of at least one of `style`, `explode`, or `allowReserved` with an explicit value is equivalent to using `schema` with `in: query` Parameter Objects.
17131715
The absence of all three of those fields is the equivalent of using `content`, but with the media type specified in `contentType` rather than through a Media Type Object.
17141716

1717+
##### Encoding the `x-www-form-urlencoded` Media Type
1718+
17151719
See [Appendix E](#percentEncodingAndFormMediaTypes) for a detailed examination of percent-encoding concerns for form media types.
17161720

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

1724+
###### Example: URL Encoded Form with JSON Values
1725+
17201726
```yaml
17211727
requestBody:
17221728
content:
@@ -1763,6 +1769,8 @@ Here is the `id` parameter (without `address`) serialized as `application/json`
17631769
id=%22f81d4fae-7dec-11d0-a765-00a0c91e6bf6%22
17641770
```
17651771

1772+
###### Example: URL Encoded Form with Binary Values
1773+
17661774
`application/x-www-form-urlencoded` is a text format, which requires base64-encoding any binary data:
17671775

17681776
```YAML
@@ -1784,7 +1792,7 @@ requestBody:
17841792
contentType: image/png, image/jpeg
17851793
```
17861794

1787-
###### Encoding `multipart` Media Types
1795+
##### Encoding `multipart` Media Types
17881796

17891797
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.
17901798

@@ -1815,7 +1823,7 @@ If `contentEncoding` is used along with setting a different `Content-Transfer-En
18151823

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

1818-
##### Encoding Object Example
1826+
###### Example: Basic Multipart Form
18191827

18201828
Examples:
18211829

@@ -1854,6 +1862,8 @@ requestBody:
18541862
$ref: '#/components/schemas/Address'
18551863
```
18561864
1865+
###### Example: Multipart Form with Encoding Objects
1866+
18571867
`multipart/form-data` allows for binary parts:
18581868

18591869
```yaml
@@ -1891,6 +1901,8 @@ requestBody:
18911901
type: integer
18921902
```
18931903

1904+
###### Example: Multipart Form with Multiple Files
1905+
18941906
To upload multiple files, a `multipart` media type MUST be used:
18951907

18961908
```yaml
@@ -2566,7 +2578,9 @@ The Header Object follows the structure of the [Parameter Object](#parameterObje
25662578
1. `in` MUST NOT be specified, it is implicitly in `header`.
25672579
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`.
25682580

2569-
##### Common Fixed Fields
2581+
##### Fixed Fields
2582+
2583+
###### Common Fixed Fields
25702584

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

@@ -2578,7 +2592,7 @@ Field Name | Type | Description
25782592

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

2581-
##### Fixed Fields for use with `schema`
2595+
###### Fixed Fields for use with `schema`
25822596

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

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

2601-
##### Fixed Fields for use with `content`
2615+
###### Fixed Fields for use with `content`
26022616

26032617
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.
26042618
Using `content` with a `text/plain` media type is RECOMMENDED for headers where the `schema` strategy is not appropriate.

0 commit comments

Comments
 (0)