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.

Sign up for GitHub

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

Jump to bottom

Improve media type serialization examples (3.0.4) #3864

Merged
merged 3 commits into from
Jun 10, 2024
Merged

Improve media type serialization examples (3.0.4) #3864

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3ee70cd
Improve media type encoding examples
handrews May 28, 2024
656fd21
review feedback - typo
handrews May 29, 2024
e386f10
Use ZIP+4 as a string, also shows encoding of +
handrews Jun 3, 2024
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
61 changes: 29 additions & 32 deletions versions/3.0.4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1297,7 +1297,7 @@ This object MAY be extended with [Specification Extensions](#specificationExtens

##### Request Body Examples

A request body with a referenced model definition.
A request body with a referenced schema definition.
```json
{
"description": "user to add to the system",
Expand Down Expand Up @@ -1373,35 +1373,6 @@ content:
externalValue: http://foo.bar/examples/user-example.whatever
```

A body parameter that is an array of string values:
```json
{
"description": "user to add to the system",
"content": {
"text/plain": {
"schema": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
```

```yaml
description: user to add to the system
required: true
content:
text/plain:
schema:
type: array
items:
type: string
```


#### <a name="mediaTypeObject"></a>Media Type Object
Each Media Type Object provides schema and examples for the media type identified by its key.

Expand Down Expand Up @@ -1557,9 +1528,35 @@ requestBody:
properties: {}
```

In this example, the contents in the `requestBody` MUST be stringified per [RFC1866](https://tools.ietf.org/html/rfc1866) when passed to the server. In addition, the `address` field complex object will be stringified.
In this example, the contents in the `requestBody` MUST be encoded per [RFC1866](https://tools.ietf.org/html/rfc1866) when passed to the server. In addition, the `address` field complex object will be serialized to a string representation prior to encoding.

When passing complex objects in the `application/x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the [Encoding Object](#encodingObject)'s [`style`](#encodingStyle) property as `form`.

With this example, given an `id` of `f81d4fae-7dec-11d0-a765-00a0c91e6bf6` and a US-style address (with ZIP+4) as follows:

```json
{
"streetAddress": "123 Example Dr.",
"city": "Somewhere",
"state": "CA",
"zip": "99999+1234"
}
```

Assuming the most compact representation of the JSON value (with unnecessary whitespace removed), we would expect to see the following request body, where space characters have been replaced with `+` and `+`, `"`, `{`, and `}` have been percent-encoded to `%2B`, `%22`, `%7B`, and `%7D`, respectively:

When passing complex objects in the `application/x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the [`Encoding Object`](#encodingObject)'s [`style`](#encodingStyle) property as `form`.
```urlencoded
id=f81d4fae-7dec-11d0-a765-00a0c91e6bf6&address=%7B%22streetAddress%22:%22123+Example+Dr.%22,%22city%22:%22Somewhere%22,%22state%22:%22CA%22,%22zip%22:%2299999%2B1234%22%7D
```

Note that the `id` keyword is treated as `text/plain` per the [Encoding Object](#encodingObject)'s default behavior, and is serialized as-is.
If it were treated as `application/json`, then the serialized value would be a JSON string including quotation marks, which would be percent-encoded as `%22`.

Here is the `id` parameter (without `address`) serialized as `application/json` instead of `text/plain`, and then encoded per RFC1866:

```urlencoded
id=%22f81d4fae-7dec-11d0-a765-00a0c91e6bf6%22
```

##### Special Considerations for `multipart` Content

Expand Down