Skip to content

Commit b54f8e5

Browse files
committed
Minor streamline of Modeling Data section
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.
1 parent 9411a81 commit b54f8e5

File tree

1 file changed

+27
-9
lines changed

1 file changed

+27
-9
lines changed

src/oas.md

Lines changed: 27 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1548,6 +1548,8 @@ application/json:
15481548
$ref: '#/components/examples/frog-example'
15491549
```
15501550

1551+
For additional techniques and examples, see [Modeling Non-JSON Data](#modeling-non-json-data).
1552+
15511553
#### Encoding Object
15521554

15531555
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
15991601
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.
16001602
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.
16011603

1604+
For additional techniques and examples, see [Modeling Non-JSON Data](#modeling-non-json-data).
1605+
16021606
#### Responses Object
16031607

16041608
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
25122516

25132517
This object MAY be extended with [Specification Extensions](#specification-extensions), though as noted, additional properties MAY omit the `x-` prefix within this object.
25142518

2519+
For additional techniques and examples, see [Schema Modeling Techniques](#schema-modeling-techniques).
2520+
25152521
##### Extended Validation with Annotations
25162522

25172523
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
25482554

25492555
##### Schema Object Examples
25502556

2557+
For additional techniques and examples, see [Schema Modeling Techniques](#schema-modeling-techniques).
2558+
25512559
###### Primitive Example
25522560

25532561
```json
@@ -3531,6 +3539,8 @@ Two examples of this:
35313539

35323540
## Modeling Data
35333541

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+
35343544
### Data Types
35353545

35363546
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,
35993609
| <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) |
36003610
| <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 |
36013611

3602-
### Data Modeling Techniques
3612+
### Schema Modeling Techniques
3613+
3614+
These techniques are all based on the [Schema Object](#schema-object).
36033615

36043616
#### Composition and Inheritance (Polymorphism)
36053617

@@ -4002,12 +4014,18 @@ oneOf:
40024014
description: Specify colors with the cyan, magenta, yellow, and black subtractive color model
40034015
```
40044016

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+
40054023
#### XML Modeling
40064024

40074025
The [xml](#schema-xml) field allows extra definitions when translating the JSON definition to XML.
40084026
The [XML Object](#xml-object) contains additional information about the available options.
40094027

4010-
### Considerations for File Uploads
4028+
#### Considerations for File Uploads
40114029

40124030
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.
40134031

@@ -4058,14 +4076,14 @@ requestBody:
40584076

40594077
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).
40604078

4061-
### Encoding the `x-www-form-urlencoded` Media Type
4079+
#### Encoding the `x-www-form-urlencoded` Media Type
40624080

40634081
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).
40644082
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.
40654083

40664084
See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detailed examination of percent-encoding concerns for form media types.
40674085

4068-
#### Example: URL Encoded Form with JSON Values
4086+
##### Example: URL Encoded Form with JSON Values
40694087

40704088
When there is no [`encoding`](#media-type-encoding) field, the serialization strategy is based on the Encoding Object's default values:
40714089

@@ -4111,7 +4129,7 @@ Here is the `id` parameter (without `address`) serialized as `application/json`
41114129
id=%22f81d4fae-7dec-11d0-a765-00a0c91e6bf6%22
41124130
```
41134131

4114-
#### Example: URL Encoded Form with Binary Values
4132+
##### Example: URL Encoded Form with Binary Values
41154133

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

@@ -4145,7 +4163,7 @@ Note that the `=` padding characters at the end need to be percent-encoded, even
41454163
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).
41464164
However, this is not guaranteed, so it may be more interoperable to keep the padding and rely on percent-decoding.
41474165

4148-
### Encoding `multipart` Media Types
4166+
#### Encoding `multipart` Media Types
41494167

41504168
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.
41514169

@@ -4168,7 +4186,7 @@ Because of this, and because the Encoding Object's `contentType` defaulting rule
41684186

41694187
See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detailed examination of percent-encoding concerns for form media types.
41704188

4171-
#### Example: Basic Multipart Form
4189+
##### Example: Basic Multipart Form
41724190

41734191
When the `encoding` field is _not_ used, the encoding is determined by the Encoding Object's defaults:
41744192

@@ -4195,7 +4213,7 @@ requestBody:
41954213
$ref: '#/components/schemas/Address'
41964214
```
41974215
4198-
#### Example: Multipart Form with Encoding Objects
4216+
##### Example: Multipart Form with Encoding Objects
41994217
42004218
Using `encoding`, we can set more specific types for binary data, or non-JSON formats for complex values.
42014219
We can also describe headers for each part:
@@ -4240,7 +4258,7 @@ requestBody:
42404258
type: integer
42414259
```
42424260
4243-
#### Example: Multipart Form with Multiple Files
4261+
##### Example: Multipart Form with Multiple Files
42444262
42454263
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:
42464264

0 commit comments

Comments
 (0)