Better RFC2557 example

Author: handrews

src/oas.md

@@ -1902,29 +1902,52 @@ multipart/mixed:
 
 ###### Example: Ordered Multipart With Required Header
 
-As described in [[?RFC2557]], a set of HTML pages can be sent in a `multipart/related` payload, preserving links among themselves by defining a `Content-Location` header for each page.
+As described in [[?RFC2557]], a set of resources making up a web pages can be sent in a `multipart/related` payload, preserving links among themselves by defining a `Content-Location` header for each page.
+The first part is used as the root resource (unless using `Content-ID`, which RFC2557 advises against), so we use `prefixItems` and `prefixEncoding` to define that it must be an HTML resource, and then allow any of several different types of resources in any order to follow.
 
-See [Appendix D](appendix-d-serializing-headers-and-cookies) for an explanation of why `content: {text/plain: {...}}` is used to describe the header value.
+The `Content-Location` header is defined using `content: {text/plain: {...}}` to avoid percent-encoding its URI value; see [Appendix D](appendix-d-serializing-headers-and-cookies) for further details.
 
 ```yaml
-multipart/related:
-  schema:
-    items:
-      type: string
-  itemEncoding:
-    contentType: text/html
-    headers:
-      Content-Location:
-        required: true
-        content:
-          text/plain:
-            schema:
-              type: string
-              format: uri
+components:
+  headers:
+    RFC2557ContentId:
+      description: Use Content-Location instead of Content-ID
+      schema: false
+    RFC2557ContentLocation:
+      required: true
+      content:
+        text/plain:
+          schema:
+            $comment: Use a full URI (not a relative reference)
+            type: string
+            format: uri
+  requestBodies:
+    RFC2557:
+      content:
+        multipart/related; type=text/html:
+          schema:
+            prefixItems:
+            - type: string
+            items:
+              anyOf:
+              - type: string
+              - $comment: To allow binary, this must always pass
+          prefixEncoding:
+          - contentType: text/html
+            headers:
+              Content-ID:
+                $ref: '#/components/headers/RFC2557ContentId'
+              Content-Location:
+                $ref: '#/components/headers/RFC2557ContentLocation'
+          itemEncoding:
+            contentType: text/html, text/css, text/javascript, image/*
+            headers:
+              Content-ID:
+                $ref: '#/components/headers/RFC2557ContentId'
+              Content-Location:
+                $ref: '#/components/headers/RFC2557ContentLocation'
 ```
 
-While the above example could have used `itemSchema` instead, if the payload is expected to be processed all at once, using `schema` ensures that tools will wait until the complete response is available before processing.
-
 ###### Example: Streaming Multipart
 
 This example assumes a device that takes large sets of pictures and streams them to the caller.