Allow Parameter/Header examples w/content

handrews · handrews · commit 67719d2a6f60 · 2025-06-02T14:17:36.000-07:00
Parameter and Header serialization is complex, particularly when
using the `content` field to use a Media Type Object.

In such scenarios, the serialization occurs in two steps:
The first step is to serialize the data to the media type, which
can be captured by the `examples` field of the Media Type Object.

The second is the encoding/escaping of the media type document
for use in a URI, HTTP header, or other location with its own rules.

Sometimes the part needing illustration with an example is at one
level, sometimes at another, and sometimes it is helpful to show
both.

For simplicity, the "data" examples are always treated as the
overall input data, so they would be the same at both levels.
This is also because it is not always possible to show each step,
particularly when there are binary serializations. This allows
showing either step (or both steps) with both data and serialization,
depending on what makes sense for the use case.
diff --git a/src/oas.md b/src/oas.md
@@ -964,6 +964,7 @@ See [Appendix B](#appendix-b-data-type-conversion) for a discussion of convertin
 ###### Common Fixed Fields
 
 These fields MAY be used with either `content` or `schema`.
+The `example` and `examples` fields are mutually exclusive, and if either is present it SHALL _override_ any `example` in the schema.
 
 | Field Name | Type | Description |
 | ---- | :----: | ---- |
@@ -973,6 +974,8 @@ These fields MAY be used with either `content` or `schema`.
 | <a name="parameter-required"></a>required | `boolean` | Determines whether this parameter is mandatory. If the [parameter location](#parameter-in) is `"path"`, this field is **REQUIRED** and its value MUST be `true`. Otherwise, the field MAY be included and its default value is `false`. |
 | <a name="parameter-deprecated"></a> deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`. |
 | <a name="parameter-allow-empty-value"></a> allowEmptyValue | `boolean` | If `true`, clients MAY pass a zero-length string value in place of parameters that would otherwise be omitted entirely, which the server SHOULD interpret as the parameter being unused. Default value is `false`. If [`style`](#parameter-style) is used, and if [behavior is _n/a_ (cannot be serialized)](#style-examples), the value of `allowEmptyValue` SHALL be ignored. Interactions between this field and the parameter's [Schema Object](#schema-object) are implementation-defined. This field is valid only for `query` parameters. <br><br>**Deprecated:** Use of this field is NOT RECOMMENDED, and it is likely to be removed in a later revision. |
+| <a name="parameter-example"></a>example | Any | Example of the parameter's potential value; see [Working With Examples](#working-with-examples). |
+| <a name="parameter-examples"></a>examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the parameter's potential value; see [Working With Examples](#working-with-examples). |
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
@@ -982,7 +985,6 @@ Note that while `"Cookie"` as a `name` is not forbidden if `in` is `"header"`, t
 
 For simpler scenarios, a [`schema`](#parameter-schema) and [`style`](#parameter-style) can describe the structure and syntax of the parameter.
 When `example` or `examples` are provided in conjunction with the `schema` field, the example SHOULD match the specified schema and follow the prescribed serialization strategy for the parameter.
-The `example` and `examples` fields are mutually exclusive, and if either is present it SHALL _override_ any `example` in the schema.
 
 These fields MUST NOT be used with `in: "querystring"`.
 
@@ -994,8 +996,6 @@ Serializing with `schema` is NOT RECOMMENDED for `in: "cookie"` parameters, `in:
 | <a name="parameter-explode"></a>explode | `boolean` | When this is true, parameter 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 parameters this field has no effect. When [`style`](#parameter-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. |
 | <a name="parameter-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 by the rules of the `in` destination or media type, or are [not allowed in the path by this specification](#path-templating); see Appendices [C](#appendix-c-using-rfc6570-based-serialization) and [E](#appendix-e-percent-encoding-and-form-media-types) for details. The default value is `false`. |
 | <a name="parameter-schema"></a>schema | [Schema Object](#schema-object) | The schema defining the type used for the parameter. |
-| <a name="parameter-example"></a>example | Any | Example of the parameter's potential value; see [Working With Examples](#working-with-examples). |
-| <a name="parameter-examples"></a>examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the parameter's potential value; see [Working With Examples](#working-with-examples). |
 
 See also [Appendix C: Using RFC6570-Based Serialization](#appendix-c-using-rfc6570-based-serialization) for additional guidance.
 
@@ -1146,6 +1146,38 @@ content:
           type: number
 ```
 
+A querystring parameter using regular form encoding, but managed with a Media Type Object:
+
+```yaml
+in: querystring
+content:
+  application/x-www-form-urlencoded:
+    schema:
+      type: object
+      properties:
+        foo:
+          type: string
+        bar:
+          type: boolean
+    examples:
+      spacesAndPluses:
+        description: Note handling of spaces and "+" per media type.
+        dataValue:
+          foo: a + b
+          bar: true
+        serializedValue:
+          foo=a+%2B+b&bar=true
+examples:
+  spacesAndPluses:
+    description: |
+      Note that no additional percent encoding is done, as this
+      media type is URI query string-ready by definition.
+    dataValue:
+      foo: a + b
+      bar: true
+    serializedValue:
+          foo=a+%2B+b&bar=true
+
 A querystring parameter that uses JSON for the entire string (not as a single query parameter value):
 
 ```yaml
@@ -1157,13 +1189,24 @@ content:
       # Allow an arbitrary JSON object to keep
       # the example simple
       type: object
-    example: {
+    examples:
+      TwoNoFlag:
+        description: Serialize with minimized whitespace
+        dataValue: {
+          "numbers": [1, 2],
+          "flag": null
+        }
+        serializedValue: '{"numbers":[1,2],"flag":null}'
+examples:
+  TwoNoFlag:
+    dataValue: {
       "numbers": [1, 2],
       "flag": null
     }
+    serializedValue: %7B%22numbers%22%3A%5B1%2C2%5D%2C%22flag%22%3Anull%7D
 ```
 
-Assuming a path of `/foo`, a server of `https://example.com`, the full URL incorporating the value from the `example` field (with whitespace minimized) would be:
+Assuming a path of `/foo`, a server of `https://example.com`, the full URL incorporating the value serialized as shown by the Example Objects would be:
 
 ```uri
 https://example.com/foo?%7B%22numbers%22%3A%5B1%2C2%5D%2C%22flag%22%3Anull%7D
@@ -1179,11 +1222,15 @@ content:
     schema:
       type: string
     example: $.a.b[1:1]
+examples:
+  Selector:
+    dataValue: $.a.b[1:1]
+    serializedValue: %24.a.b%5B1%3A1%5D
 ```
 
 As there is not, as of this writing, a [registered](#media-type-registry) mapping between the JSON Schema data model and JSONPath, the details of the string's allowed structure would need to be conveyed either in a human-readable `description` field, or through a mechanism outside of the OpenAPI Description, such as a JSON Schema for the data structure to be queried.
 
-Assuming a path of `/foo` and a server of `https://example.com`, the full URL incorporating the value from the `example` field would be:
+Assuming a path of `/foo` and a server of `https://example.com`, the full URL incorporating the value from the Example Object would be:
 
 ```uri
 https://example.com/foo?%24.a.b%5B1%3A1%5D
@@ -2411,11 +2458,16 @@ The Header Object follows the structure of the [Parameter Object](#parameter-obj
 
 These fields MAY be used with either `content` or `schema`.
 
+When `example` or `examples` are provided in conjunction with the `schema` field, the example SHOULD match the specified schema and follow the prescribed serialization strategy for the header.
+The `example` and `examples` fields are mutually exclusive, and if either is present it SHALL _override_ any `example` in the schema.
+
 | Field Name | Type | Description |
 | ---- | :----: | ---- |
 | <a name="header-description"></a>description | `string` | A brief description of the header. This could contain examples of use. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation. |
 | <a name="header-required"></a>required | `boolean` | Determines whether this header is mandatory. The default value is `false`. |
 | <a name="header-deprecated"></a> deprecated | `boolean` | Specifies that the header is deprecated and SHOULD be transitioned out of usage. Default value is `false`. |
+| <a name="header-example"></a>example | Any | Example of the header's potential value; see [Working With Examples](#working-with-examples). |
+| <a name="header-examples"></a>examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the header's potential value; see [Working With Examples](#working-with-examples). |
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
@@ -2426,16 +2478,11 @@ When `example` or `examples` are provided in conjunction with the `schema` field
 
 Serializing with `schema` is NOT RECOMMENDED for headers with parameters (name=value pairs following a `;`) in their values, or where values might have non-URL-safe characters; see [Appendix D](#appendix-d-serializing-headers-and-cookies) for details.
 
-When `example` or `examples` are provided in conjunction with the `schema` field, the example SHOULD match the specified schema and follow the prescribed serialization strategy for the header.
-The `example` and `examples` fields are mutually exclusive, and if either is present it SHALL _override_ any `example` in the schema.
-
 | Field Name | Type | Description |
 | ---- | :----: | ---- |
 | <a name="header-style"></a>style | `string` | Describes how the header value will be serialized. The default (and only legal value for headers) is `"simple"`. |
 | <a name="header-explode"></a>explode | `boolean` | When this is true, header values of type `array` or `object` generate a single header whose value is a comma-separated list of the array items or key-value pairs of the map, see [Style Examples](#style-examples). For other data types this field has no effect. The default value is `false`. |
 | <a name="header-schema"></a>schema | [Schema Object](#schema-object) \| [Reference Object](#reference-object) | The schema defining the type used for the header. |
-| <a name="header-example"></a>example | Any | Example of the header's potential value; see [Working With Examples](#working-with-examples). |
-| <a name="header-examples"></a>examples | Map[ `string`, [Example Object](#example-object) \| [Reference Object](#reference-object)] | Examples of the header's potential value; see [Working With Examples](#working-with-examples). |
 
 See also [Appendix C: Using RFC6570-Based Serialization](#appendix-c-using-rfc6570-based-serialization) for additional guidance.
 
diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml
@@ -366,6 +366,8 @@ $defs:
       - required:
         - content
     allOf:
+      - $ref: '#/$defs/examples'
+      - $ref: '#/$defs/specification-extensions'
       - if:
           properties:
             in:
@@ -403,7 +405,6 @@ $defs:
             default: false
             type: boolean
         allOf:
-          - $ref: '#/$defs/examples'
           - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-path'
           - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-header'
           - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-query'
@@ -474,7 +475,6 @@ $defs:
                   default: form
                   const: form
 
-    $ref: '#/$defs/specification-extensions'
     unevaluatedProperties: false
 
   parameter-or-reference:
@@ -728,8 +728,9 @@ $defs:
           explode:
             default: false
             type: boolean
-        $ref: '#/$defs/examples'
-    $ref: '#/$defs/specification-extensions'
+    allOf:
+    - $ref: '#/$defs/examples'
+    - $ref: '#/$defs/specification-extensions'
     unevaluatedProperties: false
 
   header-or-reference:
