diff --git a/src/oas.md b/src/oas.md index da5374a3c3..53ae8da532 100644 --- a/src/oas.md +++ b/src/oas.md @@ -769,14 +769,15 @@ See [Appendix E](#appendix-e-percent-encoding-and-form-media-types) for a detail There are five possible parameter locations specified by the `in` field: * path - Used together with [Path Templating](#path-templating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`. -* query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`; MUST NOT appear in the same operation (or in the operation's path-item) as an `in: "querystring"` parameter. +* query - Parameters that are appended to the URL with the `?` character (or to existing query parameters with the `&` character), as described by [RFC3986 section 3.4](https://datatracker.ietf.org/doc/html/rfc3986#section-3.4); +MUST NOT appear in the same operation (or in the operation's path-item) as an `in: "querystring"` parameter. * querystring - A parameter that treats the entire URL query string as a value which MUST be specified using the `content` field, most often with media type `application/x-www-form-urlencoded` using [Encoding Objects](#encoding-object) in the same way as with request bodies of that media type; MUST NOT appear more than once, and MUST NOT appear in the same operation (or in the operation's path-item) as any `in: "query"` parameters. * header - Custom headers that are expected as part of the request. Note that [RFC9110](https://www.rfc-editor.org/rfc/rfc9110.html#section-5.1) states header names are case-insensitive. * cookie - Used to pass a specific cookie value to the API. #### Fixed Fields -The rules for serialization of the parameter are specified in one of two ways. +The rules for serialization and deserialization of the parameter are specified in one of two ways. Parameter Objects MUST include either a `content` field or a `schema` field, but not both. See [Appendix B](#appendix-b-data-type-conversion) for a discussion of converting values of various types to string representations. @@ -820,7 +821,7 @@ In these cases, implementations MUST pass values through unchanged rather than a | style | `string` | Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of `in`): for `"query"` - `"form"`; for `"path"` - `"simple"`; for `"header"` - `"simple"`; for `"cookie"` - `"form"` (for compatibility reasons; note that `style: "cookie"` SHOULD be used with `in: "cookie"`; see [Appendix D](#appendix-d-serializing-headers-and-cookies) for details). | | 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, or when [`style`](#parameter-style) is `"deepObject"`, this field has no effect. When `style` is `"form"` or `"cookie"`, the default value is `true`. For all other styles, the default value is `false`. | | 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 [URL Percent-Encoding](#url-percent-encoding) for details. The default value is `false`. This field only applies to `in` and `style` values that automatically percent-encode. | -| schema | [Schema Object](#schema-object) | The schema defining the type used for the parameter. | +| schema | [Schema Object](#schema-object) | The schema defining the type and other constraints used for the parameter. | See also [Appendix C: Using RFC6570-Based Serialization](#appendix-c-using-rfc6570-based-serialization) for additional guidance. @@ -923,15 +924,15 @@ The following table shows serialized examples, as would be shown with the `seria | label | true | _empty_ | .blue | .blue.black.brown | .R=100.G=200.B=150 | | simple | false | _empty_ | blue | blue,black,brown | R,100,G,200,B,150 | | simple | true | _empty_ | blue | blue,black,brown | R=100,G=200,B=150 | -| form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 | -| form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150 | -| spaceDelimited | false | _n/a_ | _n/a_ | color=blue%20black%20brown | color=R%20100%20G%20200%20B%20150 | +| form | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 | +| form | true | color= | color=blue | color=blue&color=black&color=brown | R=100&G=200&B=150 | +| spaceDelimited | false | _n/a_ | _n/a_ | color=blue%20black%20brown | color=R%20100%20G%20200%20B%20150 | | spaceDelimited | true | _n/a_ | _n/a_ | _n/a_ | _n/a_ | -| pipeDelimited | false | _n/a_ | _n/a_ | color=blue%7Cblack%7Cbrown | color=R%7C100%7CG%7C200%7CB%7C150 | +| pipeDelimited | false | _n/a_ | _n/a_ | color=blue%7Cblack%7Cbrown | color=R%7C100%7CG%7C200%7CB%7C150 | | pipeDelimited | true | _n/a_ | _n/a_ | _n/a_ | _n/a_ | -| deepObject | _n/a_ | _n/a_ | _n/a_ | _n/a_ | color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150 | -| cookie | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 | -| cookie | true | color= | color=blue | color=blue; color=black; color=brown | R=100; G=200; B=150 | +| deepObject | _n/a_ | _n/a_ | _n/a_ | _n/a_ | color%5BR%5D=100&color%5BG%5D=200&color%5BB%5D=150 | +| cookie | false | color= | color=blue | color=blue,black,brown | color=R,100,G,200,B,150 | +| cookie | true | color= | color=blue | color=blue; color=black; color=brown | R=100; G=200; B=150 | #### Extending Support for Querystring Formats @@ -1070,7 +1071,7 @@ examples: dataValue: page: 4 pageSize: 50 - serializeValue: page=4&pageSize=50 + serializedValue: page=4&pageSize=50 ``` A complex parameter using `content` to define serialization, with multiple levels and types of examples shown to make the example usage options clear — note that `dataValue` is the same at both levels and does not need to be shown in both places in normal usage, but `serializedValue` is different: @@ -3072,7 +3073,7 @@ Serializing data into such formats requires either examining the schema-validate When inspecting schemas, given a starting point schema, implementations MUST examine that schema and all schemas that can be reached from it by following only `$ref` and `allOf` keywords. These schemas are guaranteed to apply to any instance. -When searching schemas for `type`, if the `type` keyword's value is a list of types and the serialized value can be successfully parsed as more than one of the types in the list, and no other findable `type` keyword disambiguates the actual required type, the behavior is implementation-defined. +When searching schemas for `type`, if the `type` keyword's value is a list of types and the serialized value can be successfully parsed as more than one of the types in the list, and no other findable `type` keyword disambiguates the actual required type, the behavior is implementation-defined and must be documented. Schema Objects that do not contain `type` MUST be considered to allow all types, regardless of which other keywords are present (e.g. `maximum` applies to numbers, but _does not_ require the instance to be a number). Implementations MAY inspect subschemas or possible reference targets of other keywords such as `oneOf` or `$dynamicRef`, but MUST NOT attempt to resolve ambiguities. @@ -4909,7 +4910,7 @@ parameters: type: string ``` -This example is equivalent to RFC6570's `{?foo*,bar}`, and **NOT** `{?foo*}{&bar}`. The latter is problematic because if `foo` is not defined, the result will be an invalid URI. +This example is equivalent to RFC6570's `{?foo*,bar}`, and **NOT** `{?foo*}{&bar}`. The latter is problematic because if `foo` is not defined (or the object has no properties), the result will be an invalid URI. The `&` prefix operator has no equivalent in the Parameter Object. Note that RFC6570 does not specify behavior for compound values beyond the single level addressed by `explode`. The result of using objects or arrays where no behavior is clearly specified for them is implementation-defined. @@ -4964,9 +4965,9 @@ parameters: type: object additionalProperties: type: string - explode: true - name: words in: query + explode: false schema: type: array items: @@ -4994,16 +4995,14 @@ To do that, we'll add `allowReserved: true` to `formulas`, and change to `style: parameters: - name: formulas in: query + allowReserved: true schema: type: object additionalProperties: type: string - explode: true - allowReserved: true - name: words in: query style: spaceDelimited - explode: false schema: type: array items: diff --git a/src/schemas/validation/schema.yaml b/src/schemas/validation/schema.yaml index bdc429c078..3f8976bb1f 100644 --- a/src/schemas/validation/schema.yaml +++ b/src/schemas/validation/schema.yaml @@ -439,6 +439,8 @@ $defs: const: path then: properties: + name: + pattern: '^[^{}]+$' style: default: simple enum: