diff --git a/src/oas.md b/src/oas.md index 0624358d25..d84e38c02e 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,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 | | ---- | :----: | ---- | | 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 +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 | | ---- | :----: | ---- | | 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 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: