From 3ee70cd47aad6eb996e2d0dd51eb2a8d63baf642 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Tue, 28 May 2024 13:44:37 -0700 Subject: [PATCH 1/3] Improve media type encoding examples * Replace the outdated "model" terminology with "schema" * Remove the outdated `text/plain` array example, which does not correlate with current OAS requirements * Rather than replacing the `text/plain` example direclty, enhance the example of serializing `application/json` content in `application/x-www-form-urlencoeded` request bodies. --- versions/3.0.4.md | 61 ++++++++++++++++++++++------------------------- 1 file changed, 29 insertions(+), 32 deletions(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 12b2375a79..8a17cfb484 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -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", @@ -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 -``` - - #### Media Type Object Each Media Type Object provides schema and examples for the media type identified by its key. @@ -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 as follows: + +```json +{ + "streetAddress": "123 Example Dr.", + "city": "Somewhere", + "state": "CA", + "zip": 99999 +} +``` + +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 `%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:99999%7D +``` + +Note that the `id` keyword is treated a `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 From 656fd213fd729b53b9db4647c269125f10ff8a9b Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 29 May 2024 09:09:57 -0700 Subject: [PATCH 2/3] review feedback - typo Co-authored-by: Ralf Handl --- versions/3.0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 8a17cfb484..a9586a8fe2 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -1549,7 +1549,7 @@ Assuming the most compact representation of the JSON value (with unnecessary whi id=f81d4fae-7dec-11d0-a765-00a0c91e6bf6&address=%7B%22streetAddress%22:%22123+Example+Dr.%22,%22city%22:%22Somewhere%22,%22state%22:%22CA%22,%22zip%22:99999%7D ``` -Note that the `id` keyword is treated a `text/plain` per the [Encoding Object](#encodingObject)'s default behavior, and is serialized as-is. +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: From e386f10a0b2b10c9ee4a5cfbc2759df90ac9a3c4 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 3 Jun 2024 15:58:30 -0700 Subject: [PATCH 3/3] Use ZIP+4 as a string, also shows encoding of + --- versions/3.0.4.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index a9586a8fe2..182993dd1b 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -1532,21 +1532,21 @@ In this example, the contents in the `requestBody` MUST be encoded per [RFC1866] 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 as follows: +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 + "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 `%22`, `%7B`, and `%7D`, respectively: +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: ```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:99999%7D +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.