Formatting of string values

Author: ralfhandl

versions/3.0.4.md

@@ -1096,7 +1096,7 @@ See also [Appendix C: Using RFC6570 Implementations](#appendix-c-using-rfc6570-i
 ###### Fixed Fields for use with `content`
 
 For more complex scenarios, the [`content`](#parameter-content) property can define the media type and schema of the parameter, as well as give examples of its use.
-Using `content` with a `text/plain` media type is RECOMMENDED for `in: header` and `in: cookie` parameters where the `schema` strategy is not appropriate.
+Using `content` with a `text/plain` media type is RECOMMENDED for `in: "header"` and `in: "cookie"` parameters where the `schema` strategy is not appropriate.
 
 | Field Name                             |                         Type                         | Description                                                                                                                                        |
 | -------------------------------------- | :--------------------------------------------------: | -------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -1122,7 +1122,7 @@ See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a discus
 
 Assume a parameter named `color` has one of the following values:
 
-```text
+```json
    string -> "blue"
    array -> ["blue", "black", "brown"]
    object -> { "R": 100, "G": 200, "B": 150 }
@@ -1487,7 +1487,7 @@ application/json:
 
 ##### Considerations for File Uploads
 
-In contrast with the 2.0 specification, `file` input/output content in OpenAPI is described with the same semantics as any other schema type. Specifically:
+In contrast to OpenAPI 2.0, `file` input/output content in OpenAPI 3 is described with the same semantics as any other schema type. Specifically:
 
 ```yaml
 # content transferred in binary (octet-stream):
@@ -1531,18 +1531,18 @@ To upload multiple files, a `multipart` media type MUST be used as shown under [
 
 ##### Support for x-www-form-urlencoded Request Bodies
 
-See [Encoding the `x-www-form-urlencoded` Media Type](#encoding-the-x-www-form-urlencoded-media-type) for guidance and examples, both with and without the `encoding` attribute.
+See [Encoding the `x-www-form-urlencoded` Media Type](#encoding-the-x-www-form-urlencoded-media-type) for guidance and examples, both with and without the `encoding` field.
 
 ##### Special Considerations for `multipart` Content
 
-See [Encoding `multipart` Media Types](#encoding-multipart-media-types) for further guidance and examples, both with and without the `encoding` attribute.
+See [Encoding `multipart` Media Types](#encoding-multipart-media-types) for further guidance and examples, both with and without the `encoding` field.
 
 #### Encoding Object
 
 A single encoding definition applied to a single schema property.
 See [Appendix B](#appendix-b-data-type-conversion) for a discussion of converting values of various types to string representations.
 
-Properties are correlated with `multipart` parts using the `name` parameter to `Content-Disposition: form-data`, and with `application/x-www-form-urlencoded` using the query string parameter names.
+Properties are correlated with `multipart` parts using the [`name` parameter](https://www.rfc-editor.org/rfc/rfc7578#section-4.2) of `Content-Disposition: form-data`, and with `application/x-www-form-urlencoded` using the query string parameter names.
 In both cases, their order is implementation-defined.
 
 See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detailed examination of percent-encoding concerns for form media types.
@@ -1579,7 +1579,7 @@ See [Appendix B](#appendix-b-data-type-conversion) for a discussion of data type
 | Field Name                                        |   Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | ------------------------------------------------- | :-------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | <a name="encoding-style"></a>style                 | `string`  | Describes how a specific property value will be serialized depending on its type. See [Parameter Object](#parameter-object) for details on the [`style`](#parameter-style) property. The behavior follows the same values as `query` parameters, including default values. Note that the initial `?` used in query strings is not used in `application/x-www-form-urlencoded` message bodies, and MUST be removed (if using an RFC6570 implementation) or simply not added (if constructing the string manually). This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.                                                                                                                                                                                                                                                                                                                                                                            |
-| <a name="encoding-explode"></a>explode             | `boolean` | When this is true, property values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. When [`style`](#encoding-style) is `form`, the default value is `true`. For all other styles, the default value is `false`. Note that despite `false` being the default for `deepObject`, the combination of `false` with `deepObject` is undefined. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| <a name="encoding-explode"></a>explode             | `boolean` | When this is `true`, property values of type `array` or `object` generate separate parameters for each value of the array, or key-value-pair of the map. For other types of properties this property has no effect. When [`style`](#encoding-style) is `"form"`, the default value is `true`. For all other styles, the default value is `false`. Note that despite `false` being the default for `deepObject`, the combination of `false` with `deepObject` is undefined. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`.                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | <a name="encoding-allow-reserved"></a>allowReserved | `boolean` | When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570](https://datatracker.ietf.org/doc/html/rfc6570#section-3.2.3), which allows [RFC3986's reserved character set](https://datatracker.ietf.org/doc/html/rfc3986#section-2.2), as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including `%` outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are [not allowed in the query string](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4) (`[`, `]`, `#`), or have a special meaning in `application/x-www-form-urlencoded` (`-`, `&`, `+`); see Appendices [C](#appendix-c-using-rfc6570-implementations) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. The default value is `false`. This property SHALL be ignored if the request body media type is not `application/x-www-form-urlencoded`. |
 
 See also [Appendix C: Using RFC6570 Implementations](#appendix-c-using-rfc6570-implementations) for additional guidance.
@@ -1595,7 +1595,7 @@ However, if all three of `style`, `explode`, and `allowReserved` fields are abse
 * All three keywords are to be entirely ignored, rather than treated as having their default values
 * Encoding is to be based on `contentType` alone, whether it is present with an explicit value or absent and treated as having its default value
 
-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.
+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.
 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.
 
 ##### Encoding the `x-www-form-urlencoded` Media Type
@@ -1607,7 +1607,7 @@ See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detail
 
 ###### Example: URL Encoded Form with JSON Values
 
-When there is no [`encoding` field](#media-type-encoding), the serialization strategy is based on the Encoding Object's default values:
+When there is no [`encoding`](#media-type-encoding) field, the serialization strategy is based on the Encoding Object's default values:
 
 ```yaml
 requestBody:
@@ -1687,7 +1687,7 @@ However, this is not guaranteed and the value would still need to be percent-dec
 
 ##### Encoding `multipart` Media Types
 
-It is common to use `multipart/form-data` as a `Content-Type` when transferring forms as request bodies. 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.
+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.
 
 The `form-data` disposition and its `name` parameter are mandatory for `multipart/form-data` ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.2)).
 Array properties are handled by applying the same `name` to multiple parts, as is recommended by [RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.3) for supplying multiple values per form field.
@@ -1700,16 +1700,16 @@ Note that there are significant restrictions on what headers can be used with `m
 
 Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP.
 
-Using `format: byte` for a multipart field is equivalent to specifying an [Encoding Object](#encoding-object) with a `headers` field containing `Content-Transfer-Encoding` with a schema that requires the value `base64`.
-If `format: byte` is used for a multipart field that has an Encoding Object with a `headers` field containing `Content-Transfer-Encoding` with a schema that disallows `base64`, the result is undefined for serialization and parsing.
+Using `format: "byte"` for a multipart field is equivalent to specifying an [Encoding Object](#encoding-object) with a `headers` field containing `Content-Transfer-Encoding` with a schema that requires the value `base64`.
+If `format: "byte"` is used for a multipart field that has an Encoding Object with a `headers` field containing `Content-Transfer-Encoding` with a schema that disallows `base64`, the result is undefined for serialization and parsing.
 
-Per the JSON Schema specification, `contentMediaType` without `contentEncoding` present is treated as if `contentEncoding: identity` were present. While useful for embedding text documents such as `text/html` into JSON strings, it is not useful for a `multipart/form-data` part, as it just causes the document to be treated as `text/plain` instead of its actual media type. Use the Encoding Object without `contentMediaType` if no `contentEncoding` is required.
+Per the JSON Schema specification, `contentMediaType` without `contentEncoding` present is treated as if `contentEncoding: "identity"` were present. While useful for embedding text documents such as `text/html` into JSON strings, it is not useful for a `multipart/form-data` part, as it just causes the document to be treated as `text/plain` instead of its actual media type. Use the Encoding Object without `contentMediaType` if no `contentEncoding` is required.
 
 See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detailed examination of percent-encoding concerns for form media types.
 
 ###### Example: Basic Multipart Form
 
-When the `encoding` attribute is _not_ used, the encoding is determined by the Encoding Object's defaults:
+When the `encoding` field is _not_ used, the encoding is determined by the Encoding Object's defaults:
 
 ```yaml
 requestBody:
@@ -2304,7 +2304,7 @@ Because of the potential for name clashes, the `operationRef` syntax is preferre
 for multi-document OpenAPI descriptions.
 
 Note that it is not possible to provide a constant value to `parameters` that matches the syntax of a runtime expression.
-It is possible to have ambiguous parameter names, e.g. `name: id, in: path` and `name: path.id, in: query`; this is NOT RECOMMENDED and the behavior is implementation-defined, however implementations SHOULD prefer the qualified interpretation (`path.id` as a path parameter), as the names can always be qualified to disambiguate them (e.g. using `query.path.id` for the query parameter).
+It is possible to have ambiguous parameter names, e.g. `name: "id", in: "path"` and `name: "path.id", in: "query"`; this is NOT RECOMMENDED and the behavior is implementation-defined, however implementations SHOULD prefer the qualified interpretation (`path.id` as a path parameter), as the names can always be qualified to disambiguate them (e.g. using `query.path.id` for the query parameter).
 
 ##### Examples
 
@@ -4215,17 +4215,17 @@ This will expand to the result:
 
 ## Appendix D: Serializing Headers and Cookies
 
-RFC6570's percent-encoding behavior is not always appropriate for `in: header` and `in: cookie` parameters.
+RFC6570's percent-encoding behavior is not always appropriate for `in: "header"` and `in: "cookie"` parameters.
 In many cases, it is more appropriate to use `content` with a media type such as `text/plain` and require the application to assemble the correct string.
 
-For both cookies ([RFC6265](https://www.rfc-editor.org/rfc/rfc6265)) and HTTP headers using the structured fields ([RFC8941](https://www.rfc-editor.org/rfc/rfc8941)) syntax, non-ASCII content is handled using base64 encoding (`format: byte`).
+For both cookies ([RFC6265](https://www.rfc-editor.org/rfc/rfc6265)) and HTTP headers using the structured fields ([RFC8941](https://www.rfc-editor.org/rfc/rfc8941)) syntax, non-ASCII content is handled using base64 encoding (`format: "byte"`).
 Note that the standard base64 encoding alphabet includes non-URL-safe characters that are percent-encoded by RFC6570 expansion; serializing values through both encodings is NOT RECOMMENDED.
 
 Most HTTP headers predate the structured field syntax, and a comprehensive assessment of their syntax and encoding rules is well beyond the scope of this specification.
 While [RFC8187](https://www.rfc-editor.org/rfc/rfc8187) recommends percent-encoding HTTP field (header or trailer) parameters, these parameters appear after a `;` character.
-With `style: simple`, that delimiter would itself be percent-encoded, violating the general HTTP field syntax.
+With `style: "simple"`, that delimiter would itself be percent-encoded, violating the general HTTP field syntax.
 
-Using `style: form` with `in: cookie` is ambiguous for a single value, and incorrect for multiple values.
+Using `style: "form"` with `in: "cookie"` is ambiguous for a single value, and incorrect for multiple values.
 This is true whether the multiple values are the result of using `explode: true` or not.
 
 This style is specified to be equivalent to RFC6570 form expansion which includes the `?` character (see Appendix C for more details), which is not part of the cookie syntax.