You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
Copy file name to clipboardExpand all lines: versions/3.1.1.md
+20-6Lines changed: 20 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1673,6 +1673,8 @@ In both cases, their order is implementation-defined.
1673
1673
1674
1674
See [Appendix E](#percentEncodingAndFormMediaTypes) for a detailed examination of percent-encoding concerns for form media types.
1675
1675
1676
+
##### Fixed Fields
1677
+
1676
1678
###### Common Fixed Fields
1677
1679
1678
1680
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
1699
1701
If `null` values are entirely omitted, then the `contentType` is irrelevant.
1700
1702
See [Appendix B](#dataTypeConversion) for a discussion of data type conversion options.
1701
1703
1702
-
##### Fixed Fields for RFC6570-style Serialization
1704
+
###### Fixed Fields for RFC6570-style Serialization
1703
1705
1704
1706
Field Name | Type | Description
1705
1707
---|:---:|---
@@ -1712,11 +1714,15 @@ See also [Appendix C: Using RFC6570 Implementations](#usingRFC6570Implementation
1712
1714
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.
1713
1715
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.
1714
1716
1717
+
##### Encoding the `x-www-form-urlencoded` Media Type
1718
+
1715
1719
See [Appendix E](#percentEncodingAndFormMediaTypes) for a detailed examination of percent-encoding concerns for form media types.
1716
1720
1717
1721
To submit content using form url encoding via [RFC1866](https://tools.ietf.org/html/rfc1866), the following
1718
1722
definition may be used:
1719
1723
1724
+
###### Example: URL Encoded Form with JSON Values
1725
+
1720
1726
```yaml
1721
1727
requestBody:
1722
1728
content:
@@ -1763,6 +1769,8 @@ Here is the `id` parameter (without `address`) serialized as `application/json`
1763
1769
id=%22f81d4fae-7dec-11d0-a765-00a0c91e6bf6%22
1764
1770
```
1765
1771
1772
+
###### Example: URL Encoded Form with Binary Values
1773
+
1766
1774
`application/x-www-form-urlencoded` is a text format, which requires base64-encoding any binary data:
1767
1775
1768
1776
```YAML
@@ -1784,7 +1792,7 @@ requestBody:
1784
1792
contentType: image/png, image/jpeg
1785
1793
```
1786
1794
1787
-
###### Encoding `multipart` Media Types
1795
+
##### Encoding `multipart` Media Types
1788
1796
1789
1797
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.
1790
1798
@@ -1815,7 +1823,7 @@ If `contentEncoding` is used along with setting a different `Content-Transfer-En
1815
1823
1816
1824
See [Appendix E](#percentEncodingAndFormMediaTypes) for a detailed examination of percent-encoding concerns for form media types.
1817
1825
1818
-
##### Encoding Object Example
1826
+
###### Example: Basic Multipart Form
1819
1827
1820
1828
Examples:
1821
1829
@@ -1854,6 +1862,8 @@ requestBody:
1854
1862
$ref: '#/components/schemas/Address'
1855
1863
```
1856
1864
1865
+
###### Example: Multipart Form with Encoding Objects
1866
+
1857
1867
`multipart/form-data` allows for binary parts:
1858
1868
1859
1869
```yaml
@@ -1891,6 +1901,8 @@ requestBody:
1891
1901
type: integer
1892
1902
```
1893
1903
1904
+
###### Example: Multipart Form with Multiple Files
1905
+
1894
1906
To upload multiple files, a `multipart` media type MUST be used:
1895
1907
1896
1908
```yaml
@@ -2566,7 +2578,9 @@ The Header Object follows the structure of the [Parameter Object](#parameterObje
2566
2578
1.`in` MUST NOT be specified, it is implicitly in `header`.
2567
2579
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`.
2568
2580
2569
-
##### Common Fixed Fields
2581
+
##### Fixed Fields
2582
+
2583
+
###### Common Fixed Fields
2570
2584
2571
2585
These fields MAY be used with either `content` or `schema`.
2572
2586
@@ -2578,7 +2592,7 @@ Field Name | Type | Description
2578
2592
2579
2593
This object MAY be extended with [Specification Extensions](#specificationExtensions).
2580
2594
2581
-
##### Fixed Fields for use with `schema`
2595
+
######Fixed Fields for use with `schema`
2582
2596
2583
2597
For simpler scenarios, a [`schema`](#headerSchema) and [`style`](#headerStyle) can describe the structure and syntax of the header.
2584
2598
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
2598
2612
2599
2613
See also [Appendix C: Using RFC6570 Implementations](#usingRFC6570Implementations) for additional guidance.
2600
2614
2601
-
##### Fixed Fields for use with `content`
2615
+
######Fixed Fields for use with `content`
2602
2616
2603
2617
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.
2604
2618
Using `content` with a `text/plain` media type is RECOMMENDED for headers where the `schema` strategy is not appropriate.
0 commit comments