allowReserved only permitted where percent-encoding is done

namely: in=path, in=query, in=cookie+style=form,
but not in=header, in=querystring or in=cookie+style=cookie
and not in encoding objects where contentType is used (none of style, explode,
allowReserved are present)

this brings in some work that didn't get merged in #4904
..and also fixes a bad $ref URI

Author: karenetheridge

src/oas.md

@@ -819,7 +819,7 @@ In these cases, implementations MUST pass values through unchanged rather than a
 | ---- | :----: | ---- |
 | <a name="parameter-style"></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). |
 | <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, 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`. |
-| <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 [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. |
+| <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 [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 (that is: `in: path`, `in: query`, and `in: cookie` with `style: form`). |
 | <a name="parameter-schema"></a>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.

src/schemas/validation/schema.yaml

@@ -421,9 +421,6 @@ $defs:
             type: string
           explode:
             type: boolean
-          allowReserved:
-            default: false
-            type: boolean
         allOf:
           - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-path'
           - $ref: '#/$defs/parameter/dependentSchemas/schema/$defs/styles-for-header'
@@ -449,6 +446,9 @@ $defs:
                     - simple
                 required:
                   const: true
+                allowReserved:
+                  type: boolean
+                  default: false
               required:
                 - required
 
@@ -477,6 +477,9 @@ $defs:
                     - spaceDelimited
                     - pipeDelimited
                     - deepObject
+                allowReserved:
+                  type: boolean
+                  default: false
 
           styles-for-cookie:
             if:
@@ -490,6 +493,15 @@ $defs:
                   enum:
                     - form
                     - cookie
+              if:
+                properties:
+                  style:
+                    const: form
+              then:
+                properties:
+                  allowReserved:
+                    type: boolean
+                    default: false
 
     unevaluatedProperties: false
 
@@ -598,6 +610,7 @@ $defs:
         type: boolean
       allowReserved:
         type: boolean
+        default: false
       encoding:
         type: object
         additionalProperties:
@@ -614,9 +627,7 @@ $defs:
           prefixEncoding: false
           itemEncoding: false
       style:
-        properties:
-          allowReserved:
-            default: false
+        $ref: '#/$defs/styles-for-form'
       explode:
         properties:
           style:
@@ -627,9 +638,8 @@ $defs:
         properties:
           style:
             default: form
-    allOf:
-      - $ref: '#/$defs/specification-extensions'
-      - $ref: '#/$defs/styles-for-form'
+        $ref: '#/$defs/styles-for-form'
+    $ref: '#/$defs/specification-extensions'
     unevaluatedProperties: false
 
   responses:
@@ -810,9 +820,6 @@ $defs:
           explode:
             default: false
             type: boolean
-          allowReserved:
-            default: false
-            type: boolean
     allOf:
     - $ref: '#/$defs/examples'
     - $ref: '#/$defs/specification-extensions'

tests/schema/fail/header-object-allowReserved.yaml

@@ -0,0 +1,12 @@
+openapi: 3.3.0
+info:
+  title: allowReserved only permitted with in and style values that percent-encode
+  version: 1.0.0
+components:
+  headers:
+    Style:
+      schema:
+        type: array
+      style: simple
+      explode: true
+      allowReserved: true

tests/schema/fail/parameter-object-cookie-allowReserved.yaml

@@ -0,0 +1,12 @@
+openapi: 3.3.0
+info:
+  title: allowReserved only permitted with in and style values that percent-encode
+  version: 1.0.0
+components:
+  parameters:
+    my_cookie:
+      name: my_cookie
+      in: cookie
+      style: cookie
+      allowReserved: true
+      schema: {}

tests/schema/fail/parameter-object-header-allowReserved.yaml

@@ -0,0 +1,11 @@
+openapi: 3.3.0
+info:
+  title: allowReserved only permitted with in and style values that percent-encode
+  version: 1.0.0
+components:
+  parameters:
+    header:
+      name: my-header
+      in: header
+      allowReserved: false
+      schema: {}

tests/schema/pass/header-object-examples.yaml

@@ -17,10 +17,9 @@ components:
             type: string
             pattern: ^"
     Reference:
-      $ref: '#/components/schemas/ETag'
+      $ref: '#/components/headers/ETag'
     Style:
       schema:
         type: array
       style: simple
       explode: true
-      allowReserved: true

tests/schema/pass/parameter-object-cookie-form-allowReserved.yaml

@@ -0,0 +1,18 @@
+openapi: 3.3.0
+info:
+  title: allowReserved only permitted with in and style values that percent-encode
+  version: 1.0.0
+components:
+  parameters:
+    style_form:
+      name: my_form_cookie
+      in: cookie
+      # default style is form, therefore allowReserved is allowed
+      allowReserved: true
+      schema: {}
+    style_cookie:
+      name: my_cookie_cookie
+      in: cookie
+      style: cookie
+      # no percent decoding for style=cookie, therefore allowReserved is not allowed
+      schema: {}

tests/schema/pass/parameter-object-path-allowReserved.yaml

@@ -0,0 +1,12 @@
+openapi: 3.3.0
+info:
+  title: api
+  version: 1.0.0
+components:
+  parameters:
+    path:
+      name: my-path
+      in: path
+      required: true
+      allowReserved: false
+      schema: {}

tests/schema/pass/parameter-object-query-allowReserved.yaml

@@ -0,0 +1,11 @@
+openapi: 3.3.0
+info:
+  title: allowReserved only permitted with in and style values that percent-encode
+  version: 1.0.0
+components:
+  parameters:
+    my_query:
+      name: my_query
+      in: query
+      allowReserved: true
+      schema: {}