From 042e70884b3895811d7354d9923d2b4bd6176670 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sat, 12 Jul 2025 16:36:49 -0700 Subject: [PATCH 1/3] 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. --- src/oas.md | 16 +++++++++------- src/schemas/validation/schema.yaml | 7 +++++-- 2 files changed, 14 insertions(+), 9 deletions(-) diff --git a/src/oas.md b/src/oas.md index 985304f993..4a379a038b 100644 --- a/src/oas.md +++ b/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`. | 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`. | | deprecated | `boolean` | Specifies that a parameter is deprecated and SHOULD be transitioned out of usage. Default value is `false`. | | 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.

**Deprecated:** Use of this field is NOT RECOMMENDED, and it is likely to be removed in a later revision. | +| example | Any | Example of the parameter's potential value; see [Working With Examples](#working-with-examples). | +| 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: | 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. | | 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`. | | schema | [Schema Object](#schema-object) | The schema defining the type used for the parameter. | -| example | Any | Example of the parameter's potential value; see [Working With Examples](#working-with-examples). | -| 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 | | ---- | :----: | ---- | | 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. | | required | `boolean` | Determines whether this header is mandatory. The default value is `false`. | | deprecated | `boolean` | Specifies that the header is deprecated and SHOULD be transitioned out of usage. Default value is `false`. | +| example | Any | Example of the header's potential value; see [Working With Examples](#working-with-examples). | +| 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 | | ---- | :----: | ---- | | style | `string` | Describes how the header value will be serialized. The default (and only legal value for headers) is `"simple"`. | diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 9990fefb67..69d80e216d 100644 --- 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: @@ -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: From a7c9c0c34b486bfa7c9f60f5455e940c41ad38be Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sat, 19 Jul 2025 10:36:43 -0700 Subject: [PATCH 2/3] Review feedback and maintainability Let's only explain the validation requirements in one place. Also, header example fields were supposed to be moved rather than duplicatd but I missed the removal of the old ones. --- src/oas.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/src/oas.md b/src/oas.md index 4a379a038b..57251555cc 100644 --- a/src/oas.md +++ b/src/oas.md @@ -968,8 +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. + +The `example` and `examples` fields are mutually exclusive; see [Working with Examples](#working-with-examples) for guidance on validation requirements. | Field Name | Type | Description | | ---- | :----: | ---- | @@ -2423,8 +2423,7 @@ 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. +The `example` and `examples` fields are mutually exclusive; see [Working with Examples](#working-with-examples) for guidance on validation requirements. | Field Name | Type | Description | | ---- | :----: | ---- | @@ -2439,7 +2438,6 @@ This object MAY be extended with [Specification Extensions](#specification-exten ###### Fixed Fields for use with `schema` For simpler scenarios, a [`schema`](#header-schema) and [`style`](#header-style) can describe the structure and syntax of the header. -When `example` or `examples` are provided in conjunction with the `schema` field, the example MUST follow the prescribed serialization strategy for the header. Serializing headers with `schema` can be problematic due to the URI percent-encoding that is automatically applied, which would percent-encode characters such as `;` that are used to separate primary header values from their parameters. The `allowReserved` field can disable most but not all of this behavior. @@ -2451,8 +2449,6 @@ See [Appendix D](#appendix-d-serializing-headers-and-cookies) for details and fu | 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`. | | allowReserved | `boolean` | When this is true, header 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). See [Appendix D: Serializing Headers and Cookies](#appendix-d-serializing-headers-and-cookies) for guidance on header encoding and escaping. The default value is `false`. | | schema | [Schema Object](#schema-object) | The schema defining the type used for the header. | -| example | Any | Example of the header's potential value; see [Working With Examples](#working-with-examples). | -| 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. From dfbda977f1c445ecff380acf3f35d0be92a84735 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sat, 19 Jul 2025 10:39:07 -0700 Subject: [PATCH 3/3] Remove redundant $ref --- src/schemas/validation/schema.yaml | 1 - 1 file changed, 1 deletion(-) diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index 69d80e216d..fc519c6a97 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -732,7 +732,6 @@ $defs: default: false type: boolean $ref: '#/$defs/examples' - $ref: '#/$defs/specification-extensions' allOf: - $ref: '#/$defs/examples' - $ref: '#/$defs/specification-extensions'