v3.2: Allow Parameter/Header "examples" field with "content" field

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,37 @@ 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
@@ -1154,16 +1185,32 @@ name: json
 content:
   application/json:
     schema:
-      # Allow an arbitrary JSON object to keep
-      # the example simple
       type: object
-    example: {
+      properties:
+        numbers:
+          type: array
+          items:
+            type: number
+        flag:
+          type: [boolean, "null"]
+    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 +1226,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 +2462,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).
 
@@ -2428,9 +2484,6 @@ Serializing headers with `schema` can be problematic due to the URI percent-enco
 The `allowReserved` field can disable most but not all of this behavior.
 See [Appendix D](#appendix-d-serializing-headers-and-cookies) for details and further guidance.
 
-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"`. |
@@ -2472,6 +2525,9 @@ ETag:
       schema:
         type: string
         pattern: ^"
+  examples:
+    dataValue: xyzzx
+    serializedValue: xyzzx
 ```
 
 #### Tag Object

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:
@@ -733,6 +733,9 @@ $defs:
             type: boolean
         $ref: '#/$defs/examples'
     $ref: '#/$defs/specification-extensions'
+    allOf:
+    - $ref: '#/$defs/examples'
+    - $ref: '#/$defs/specification-extensions'
     unevaluatedProperties: false
 
   header-or-reference: