Allow Parameter/Header examples w/content

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.

Author: handrews

src/oas.md

@@ -968,6 +968,8 @@ 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`.
+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.
 
 | Field Name | Type | Description |
 | ---- | :----: | ---- |
@@ -977,6 +979,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).
 
@@ -985,8 +989,6 @@ Note that while `"Cookie"` as a `name` is not forbidden if `in` is `"header"`, t
 ###### Fixed Fields for use with `schema`
 
 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.
 
 These fields MUST NOT be used with `in: "querystring"`.
 
@@ -998,8 +1000,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.
 
@@ -2423,11 +2423,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.
+
 | 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).
 
@@ -2440,9 +2445,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.
-
 | 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"`. |

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: