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
This does a few section name and indentation level changes
to improve the organization of the new section. It also adds
links from the old locations to the new.
Copy file name to clipboardExpand all lines: src/oas.md
+27-9Lines changed: 27 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1548,6 +1548,8 @@ application/json:
1548
1548
$ref: '#/components/examples/frog-example'
1549
1549
```
1550
1550
1551
+
For additional techniques and examples, see [Modeling Non-JSON Data](#modeling-non-json-data).
1552
+
1551
1553
#### Encoding Object
1552
1554
1553
1555
A single encoding definition applied to a single schema property.
@@ -1599,6 +1601,8 @@ See also [Appendix C: Using RFC6570 Implementations](#appendix-c-using-rfc6570-b
1599
1601
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.
1600
1602
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.
1601
1603
1604
+
For additional techniques and examples, see [Modeling Non-JSON Data](#modeling-non-json-data).
1605
+
1602
1606
#### Responses Object
1603
1607
1604
1608
A container for the expected responses of an operation.
@@ -2512,6 +2516,8 @@ JSON Schema implementations MAY choose to treat keywords defined by the OpenAPI
2512
2516
2513
2517
This object MAY be extended with [Specification Extensions](#specification-extensions), though as noted, additional properties MAY omit the `x-` prefix within this object.
2514
2518
2519
+
For additional techniques and examples, see [Schema Modeling Techniques](#schema-modeling-techniques).
2520
+
2515
2521
##### Extended Validation with Annotations
2516
2522
2517
2523
JSON Schema Draft 2020-12 supports [collecting annotations](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-7.7.1), including [treating unrecognized keywords as annotations](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-00#section-6.5).
@@ -2548,6 +2554,8 @@ However, for maximum interoperability, it is RECOMMENDED that OpenAPI descriptio
2548
2554
2549
2555
##### Schema Object Examples
2550
2556
2557
+
For additional techniques and examples, see [Schema Modeling Techniques](#schema-modeling-techniques).
2558
+
2551
2559
###### Primitive Example
2552
2560
2553
2561
```json
@@ -3531,6 +3539,8 @@ Two examples of this:
3531
3539
3532
3540
## Modeling Data
3533
3541
3542
+
This section collects guidance on various data modeling and encoding scenarios that are either very genearl, or are more complex than those needed to illustrate basic Object usage.
3543
+
3534
3544
### Data Types
3535
3545
3536
3546
Data types in the OAS are based on the types defined by the [JSON Schema Validation Specification Draft 2020-12](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-6.1.1):
@@ -3599,7 +3609,9 @@ The following table shows how to migrate from OAS 3.0 binary data descriptions,
3599
3609
| <code style="white-space:nowrap">type: string</code><br /><code style="white-space:nowrap">format: binary</code> | <code style="white-space:nowrap">contentMediaType: image/png</code> | if redundant, can be omitted, often resulting in an empty [Schema Object](#schema-object) |
3600
3610
| <code style="white-space:nowrap">type: string</code><br /><code style="white-space:nowrap">format: byte</code> | <code style="white-space:nowrap">type: string</code><br /><code style="white-space:nowrap">contentMediaType: image/png</code><br /><code style="white-space:nowrap">contentEncoding: base64</code> | note that `base64url` can be used to avoid re-encoding the base64 string to be URL-safe |
3601
3611
3602
-
### Data Modeling Techniques
3612
+
### Schema Modeling Techniques
3613
+
3614
+
These techniques are all based on the [Schema Object](#schema-object).
3603
3615
3604
3616
#### Composition and Inheritance (Polymorphism)
3605
3617
@@ -4002,12 +4014,18 @@ oneOf:
4002
4014
description: Specify colors with the cyan, magenta, yellow, and black subtractive color model
4003
4015
```
4004
4016
4017
+
### Modeling Non-JSON Data
4018
+
4019
+
This section describes how to model non-JSON formats, either by mapping the format into the
4020
+
[JSON Schema data model](https://www.ietf.org/archive/id/draft-bhutton-json-schema-01.html#name-instance-data-model)
4021
+
or by using additional Objects such as the [Encoding Object](#encoding-object).
4022
+
4005
4023
#### XML Modeling
4006
4024
4007
4025
The [xml](#schema-xml) field allows extra definitions when translating the JSON definition to XML.
4008
4026
The [XML Object](#xml-object) contains additional information about the available options.
4009
4027
4010
-
### Considerations for File Uploads
4028
+
#### Considerations for File Uploads
4011
4029
4012
4030
In contrast to OpenAPI 2.0, `file` input/output content in OAS 3.x is described with the same semantics as any other schema type.
4013
4031
@@ -4058,14 +4076,14 @@ requestBody:
4058
4076
4059
4077
To upload multiple files, a `multipart` media type MUST be used as shown under [Example: Multipart Form with Multiple Files](#example-multipart-form-with-multiple-files).
4060
4078
4061
-
### Encoding the `x-www-form-urlencoded` Media Type
4079
+
#### Encoding the `x-www-form-urlencoded` Media Type
4062
4080
4063
4081
To submit content using form url encoding via [RFC1866](https://tools.ietf.org/html/rfc1866), use the `application/x-www-form-urlencoded` media type in the [Media Type Object](#media-type-object) under the [Request Body Object](#request-body-object).
4064
4082
This configuration means that the request body MUST be encoded per [RFC1866](https://tools.ietf.org/html/rfc1866) when passed to the server, after any complex objects have been serialized to a string representation.
4065
4083
4066
4084
See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detailed examination of percent-encoding concerns for form media types.
4067
4085
4068
-
#### Example: URL Encoded Form with JSON Values
4086
+
##### Example: URL Encoded Form with JSON Values
4069
4087
4070
4088
When there is no [`encoding`](#media-type-encoding) field, the serialization strategy is based on the Encoding Object's default values:
4071
4089
@@ -4111,7 +4129,7 @@ Here is the `id` parameter (without `address`) serialized as `application/json`
4111
4129
id=%22f81d4fae-7dec-11d0-a765-00a0c91e6bf6%22
4112
4130
```
4113
4131
4114
-
#### Example: URL Encoded Form with Binary Values
4132
+
##### Example: URL Encoded Form with Binary Values
4115
4133
4116
4134
Note that `application/x-www-form-urlencoded` is a text format, which requires base64-encoding any binary data:
4117
4135
@@ -4145,7 +4163,7 @@ Note that the `=` padding characters at the end need to be percent-encoded, even
4145
4163
Some base64-decoding implementations may be able to use the string without the padding per [RFC4648](https://datatracker.ietf.org/doc/html/rfc4648#section-3.2).
4146
4164
However, this is not guaranteed, so it may be more interoperable to keep the padding and rely on percent-decoding.
4147
4165
4148
-
### Encoding `multipart` Media Types
4166
+
#### Encoding `multipart` Media Types
4149
4167
4150
4168
It is common to use `multipart/form-data` as a `Content-Type` when transferring forms as request bodies. In contrast to OpenAPI 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.
4151
4169
@@ -4168,7 +4186,7 @@ Because of this, and because the Encoding Object's `contentType` defaulting rule
4168
4186
4169
4187
See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detailed examination of percent-encoding concerns for form media types.
4170
4188
4171
-
#### Example: Basic Multipart Form
4189
+
##### Example: Basic Multipart Form
4172
4190
4173
4191
When the `encoding` field is _not_ used, the encoding is determined by the Encoding Object's defaults:
4174
4192
@@ -4195,7 +4213,7 @@ requestBody:
4195
4213
$ref: '#/components/schemas/Address'
4196
4214
```
4197
4215
4198
-
#### Example: Multipart Form with Encoding Objects
4216
+
##### Example: Multipart Form with Encoding Objects
4199
4217
4200
4218
Using `encoding`, we can set more specific types for binary data, or non-JSON formats for complex values.
4201
4219
We can also describe headers for each part:
@@ -4240,7 +4258,7 @@ requestBody:
4240
4258
type: integer
4241
4259
```
4242
4260
4243
-
#### Example: Multipart Form with Multiple Files
4261
+
##### Example: Multipart Form with Multiple Files
4244
4262
4245
4263
In accordance with [RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3), multiple files for a single form field are uploaded using the same name (`file` in this example) for each file's part:
0 commit comments