From 5cdf94f8910d4f717d80e1f0ac6afa1f6fc8b352 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 2 Jun 2025 14:07:05 -0700 Subject: [PATCH 1/4] 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 | 67 ++++++++++++++++++++++++++---- src/schemas/validation/schema.yaml | 7 +++- 2 files changed, 63 insertions(+), 11 deletions(-) diff --git a/src/oas.md b/src/oas.md index 0624358d25..b6deda49b4 100644 --- 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`. | 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). @@ -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: | 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. @@ -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 | | ---- | :----: | ---- | | 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). @@ -2428,9 +2480,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 | | ---- | :----: | ---- | | 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 7842f0438ea1641c87d40334de2f7d9fcc48ad0c Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Thu, 5 Jun 2025 12:08:14 -0700 Subject: [PATCH 2/4] Fix example formatting Co-authored-by: Karen Etheridge --- src/oas.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index b6deda49b4..eaaab6a679 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1175,8 +1175,7 @@ examples: dataValue: foo: a + b bar: true - serializedValue: - foo=a+%2B+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): From afe9631bc996a59b9dcb801b43e93d48627f52fd Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 9 Jun 2025 12:25:25 -0700 Subject: [PATCH 3/4] Improve example clarity --- src/oas.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/src/oas.md b/src/oas.md index eaaab6a679..a1965cbdeb 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1185,9 +1185,14 @@ name: json content: application/json: schema: - # Allow an arbitrary JSON object to keep - # the example simple type: object + properties: + numbers: + type: array + items: + type: number + flag: + type: [boolean, "null"] examples: TwoNoFlag: description: Serialize with minimized whitespace From e9f1322958395b827661d0bb89ec78d0b04c6a35 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Tue, 10 Jun 2025 12:28:07 -0700 Subject: [PATCH 4/4] Example of content + examples for Header Object --- src/oas.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/src/oas.md b/src/oas.md index a1965cbdeb..d84e38c02e 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2525,6 +2525,9 @@ ETag: schema: type: string pattern: ^" + examples: + dataValue: xyzzx + serializedValue: xyzzx ``` #### Tag Object