Update Set-Cookie example for recent changes

Changes to our understanding of percent-encoding and headers
have made the previous example incorrect.  This brings it into
agreement with the new recommendations.

This also explains how percent-encoding and other escaping is
handled, and links to the updated Appendix D which provids more
detail including a link to the IETF draft update of the cookie
RFC that clarifies this.

Author: handrews

src/oas.md

@@ -3036,14 +3036,14 @@ For HTTP messages, this is purely a serialization concern, and no more of a prob
 
 However, because examples and values modeled with `content` do not incorporate the header name, for these fields `Set-Cookie` MUST be handled by placing each value on a separate line, without the header name or the `:` delimiter.
 
-The following example shows two different ways to describe `Set-Cookie` headers that require cookies named `"lang"` and `"foo"`.  The first uses `content` to preserve the necessary whitespace in the `"Expires"` cookie attribute, while the second shows the use of `style: "simple"` and forbids whitespace to ensure that values work with this serialization approach:
+Note also that any URI percent-encoding, base64 encoding, or other escaping MUST be performed prior to supplying the data to OAS tooling; see [Appendix D](appendix-d-serializing-headers-and-cookies) for details.
+
+The following example shows two different ways to describe `Set-Cookie` headers that require cookies named `"lang"` and `"foo"`, as well as a `"urlSafeData"` cookie that is expected to be percent-encoded.  The first uses `content` in order to show exactly how such examples are formatted, but also notes the limitations of schema constraints with multi-line text.  The second shows the use of `style: "simple"`, which produces the same serialized example text (with each line corresponding to one `Set-Cookie:` line in the HTTP response), but allows schema constraints on each cookie; note that the percent-encoding is already applied in the `dataValue` field of the example:
 
 ```yaml
 components:
   headers:
-    SetCookieWithExpires:
-      # Spaces within the Expires values prevent the use of `schema` and
-      # `style` as they would be percent-encoded, even with `allowReserved`.
+    SetCookieWithContent:
       content:
         text/plain:
           schema:
@@ -3058,45 +3058,47 @@ components:
           dataValue: |
             lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT
             foo=bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT
+            urlSafeData: Hello%2C%20world%21
           serializedValue: |
             lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT
             foo=bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT
-    SetCookieWithNoSpaces:
+            urlSafeData: Hello%2C%20world%21
+    SetCookieWithSchemaAnd Style:
       schema:
         type: object
         required:
         - lang
         - foo
+        - urlSafeData
+        properties:
+          urlSafeData:
+            type: string
+            pattern: ^[-_.%a-zA-Z0-9]+(;|$)
         additionalProperties:
-          type: string
-          pattern: "^[^[:space:]]*$"
+          # Require an Expires parameter
+          pattern: "; *Expires="
       style: simple
       explode: true
       examples:
         SetCookies:
           dataValue: {
-            "lang": "en-US",
-            "foo": "bar"
+            "lang": "en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT"
+            "foo": "bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT"
+            "urlSafeData": "Hello%2C%20world%21"
           }
           serializedValue: |
-            lang=en-US
-            foo=bar
+            lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GMT
+            foo=bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT
+            urlSafeData: Hello%2C%20world%21
 ```
 
-In an HTTP message, the serialized example with Expires would look like:
+In an HTTP message, the serialized example would look like:
 
 ```http
 Set-Cookie: lang=en-US; Expires=Wed, 09 Jun 2021 10:18:14 GM
 Set-Cookie: foo=bar; Expires=Wed, 09 Jun 2021 10:18:14 GMT
 ```
 
-and the example without Expires would look like:
-
-```http
-Set-Cookie: lang=en-US
-Set-Cookie: foo=bar
-```
-
 ##### Header Object Example
 
 A simple header of type `integer`: