From 23beb08d82ff738b70a97be3120b26f86aa17da2 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 20 Jun 2025 17:42:25 -0700 Subject: [PATCH 1/2] New encoding examples --- src/oas.md | 92 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/src/oas.md b/src/oas.md index e91c9cb08a..0295d25da0 100644 --- a/src/oas.md +++ b/src/oas.md @@ -1869,6 +1869,98 @@ requestBody: As seen in the [Encoding Object's `contentType` field documentation](#encoding-content-type), the empty schema for `items` indicates a media type of `application/octet-stream`. +###### Example: Ordered, Unnamed Multipart + +A `multipart/mixed` payload consisting of a JSON metadata document followed by an image which the metadata describes: + +```yaml +multipart/mixed: + schema: + prefixItems: + - # default content type for objects + # is `application/json` + type: object + properties: + author: + type: string + created: + type: string + format: datetime + copyright: + type: string + license: + type: string + - # default content type for a schema without `type` + # is `application/octet-stream`, which we need + # to override. + {} + prefixEncoding: + - # Encoding Object defaults are correct for JSON + {} + - contentType: image/* +``` + +###### 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. + +See [Appendix D](appendix-d-serializing-headers-and-cookies) for an explanation of why `content: {text/plain: {...}}` is used to describe the header value. + +```yaml +multipart/related: + schema: + items: + type: string + itemEncoding: + contentType: text/html + headers: + Content-Location: + required: true + content: + text/plain: + schema: + type: string + format: uri +``` + +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. +Unlike the previous example, we use `itemSchema` here because the expectation is that each image is processed as it arrives (or in small batches), since we know that buffering the entire stream will take too much memory. + +```yaml +multipart/mixed: + itemSchema: + $comment: A single data image from the device + itemEncoding: + contentType: image/jpg +``` + +###### Example: Streaming Byte Ranges + +For `multipart/byteranges` [[RFC9110]] [Section 14.6](https://www.rfc-editor.org/rfc/rfc9110.html#section-14.6), a `Content-Range` header is required: + +See [Appendix D](appendix-d-serializing-headers-and-cookies) for an explanation of why `content: {text/plain: {...}}` is used to describe the header value. + +```yaml +multipart/byteranges: + itemSchema: + $comment: A single range of bytes from a video + itemEncoding: + contentType: video/mp4 + headers: + Content-Range: + required: true + content: + text/plain: + schema: + # A suitable "pattern" constraint for this + # header is left as an exercise for the reader + type: string +``` + #### Responses Object A container for the expected responses of an operation. From 775fb60e079c18a9e949a3ea434233ebe9481071 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Fri, 20 Jun 2025 17:50:16 -0700 Subject: [PATCH 2/2] Better RFC2557 example --- src/oas.md | 59 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 41 insertions(+), 18 deletions(-) diff --git a/src/oas.md b/src/oas.md index 0295d25da0..503811b34a 100644 --- a/src/oas.md +++ b/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.