From 60f164d90f9d212fadd326f323dfac06acd99386 Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Mon, 24 Jun 2024 14:59:22 -0700 Subject: [PATCH 1/5] Clarify interaction of format: byte and Content-Transfer-Encoding header definition --- versions/3.0.4.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 03da3f7ddc..2de195d9bd 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -1753,8 +1753,9 @@ It is not currently possible to correlate schema properties with unnamed, ordere Note that there are significant restrictions on what headers can be used with `multipart` media types in general ([RFC2046 §5.1](https://www.rfc-editor.org/rfc/rfc2046.html#section-5.1)) and `multi-part/form-data` in particular ([RFC7578 §4.8](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.8)). Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578 §4.7](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP. -Using `format: byte` for a multipart field is equivalent to setting `Content-Transfer-Encoding: base64`. -If `format: byte` is used along with setting a different `Content-Transfer-Encoding` value with the `headers` field, the result is undefined. + +Using `format: byte` for a multipart field is equivalent to specifying an `encoding` object with a `headers` field containing `Content-Transfer-Encoding: enum: ["base64"]`. +If `format: byte` is used for a multipart field that has an encoding object with a `headers` field containing `Content-Transfer-Encoding` with a schema that permits values other than "base64", the result is undefined. Per the JSON Schema specification, `contentMediaType` without `contentEncoding` present is treated as if `contentEncoding: identity` were present. While useful for embedding text documents such as `text/html` into JSON strings, it is not useful for a `multipart/form-data` part, as it just causes the document to be treated as `text/plain` instead of its actual media type. Use the Encoding Object without `contentMediaType` if no `contentEncoding` is required. From 7bb584fb699d7ca69eae1199ed09e7e33ab4a06e Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Mon, 24 Jun 2024 15:53:49 -0700 Subject: [PATCH 2/5] Address PR review commments --- versions/3.0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 2de195d9bd..890af64b7d 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -1754,7 +1754,7 @@ Note that there are significant restrictions on what headers can be used with `m Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578 §4.7](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP. -Using `format: byte` for a multipart field is equivalent to specifying an `encoding` object with a `headers` field containing `Content-Transfer-Encoding: enum: ["base64"]`. +Using `format: byte` for a multipart field is equivalent to specifying an `encoding` object with a `headers` field containing `Content-Transfer-Encoding: { schema: { enum: [base64] } }`. If `format: byte` is used for a multipart field that has an encoding object with a `headers` field containing `Content-Transfer-Encoding` with a schema that permits values other than "base64", the result is undefined. Per the JSON Schema specification, `contentMediaType` without `contentEncoding` present is treated as if `contentEncoding: identity` were present. While useful for embedding text documents such as `text/html` into JSON strings, it is not useful for a `multipart/form-data` part, as it just causes the document to be treated as `text/plain` instead of its actual media type. Use the Encoding Object without `contentMediaType` if no `contentEncoding` is required. From d4425ba3f20105a903487227f860cfa7c63ae25c Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Thu, 27 Jun 2024 11:05:02 -0700 Subject: [PATCH 3/5] Reword as discussed in TSC meeting today --- versions/3.0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 890af64b7d..b18377fb79 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -1755,7 +1755,7 @@ Note that there are significant restrictions on what headers can be used with `m Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578 §4.7](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP. Using `format: byte` for a multipart field is equivalent to specifying an `encoding` object with a `headers` field containing `Content-Transfer-Encoding: { schema: { enum: [base64] } }`. -If `format: byte` is used for a multipart field that has an encoding object with a `headers` field containing `Content-Transfer-Encoding` with a schema that permits values other than "base64", the result is undefined. +If `format: byte` is used for a multipart field that has an encoding object with a `headers` field containing `Content-Transfer-Encoding` with a schema that disallows "base64", the result is undefined for serialization and parsing. Per the JSON Schema specification, `contentMediaType` without `contentEncoding` present is treated as if `contentEncoding: identity` were present. While useful for embedding text documents such as `text/html` into JSON strings, it is not useful for a `multipart/form-data` part, as it just causes the document to be treated as `text/plain` instead of its actual media type. Use the Encoding Object without `contentMediaType` if no `contentEncoding` is required. From 37866fbe3b57fb960698ae4b26b71fc4019ca5cb Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Thu, 27 Jun 2024 12:33:35 -0700 Subject: [PATCH 4/5] Avoid "partially condensed YAML" Co-authored-by: Ralf Handl --- versions/3.0.4.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index b18377fb79..9c47767930 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -1754,7 +1754,7 @@ Note that there are significant restrictions on what headers can be used with `m Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578 §4.7](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP. -Using `format: byte` for a multipart field is equivalent to specifying an `encoding` object with a `headers` field containing `Content-Transfer-Encoding: { schema: { enum: [base64] } }`. +Using `format: byte` for a multipart field is equivalent to specifying an Encoding Object with a `headers` field containing `Content-Transfer-Encoding` with a schema that requires the value `base64`. If `format: byte` is used for a multipart field that has an encoding object with a `headers` field containing `Content-Transfer-Encoding` with a schema that disallows "base64", the result is undefined for serialization and parsing. Per the JSON Schema specification, `contentMediaType` without `contentEncoding` present is treated as if `contentEncoding: identity` were present. While useful for embedding text documents such as `text/html` into JSON strings, it is not useful for a `multipart/form-data` part, as it just causes the document to be treated as `text/plain` instead of its actual media type. Use the Encoding Object without `contentMediaType` if no `contentEncoding` is required. From 8b8f2cc347ce41962ed4e66898263ce2cec22375 Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Thu, 27 Jun 2024 12:43:47 -0700 Subject: [PATCH 5/5] Final polish --- versions/3.0.4.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 9c47767930..7045ec6cfd 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -1754,8 +1754,8 @@ Note that there are significant restrictions on what headers can be used with `m Note also that `Content-Transfer-Encoding` is deprecated for `multipart/form-data` ([RFC7578 §4.7](https://www.rfc-editor.org/rfc/rfc7578.html#section-4.7)) where binary data is supported, as it is in HTTP. -Using `format: byte` for a multipart field is equivalent to specifying an Encoding Object with a `headers` field containing `Content-Transfer-Encoding` with a schema that requires the value `base64`. -If `format: byte` is used for a multipart field that has an encoding object with a `headers` field containing `Content-Transfer-Encoding` with a schema that disallows "base64", the result is undefined for serialization and parsing. +Using `format: byte` for a multipart field is equivalent to specifying an [Encoding Object](#encodingObject) with a `headers` field containing `Content-Transfer-Encoding` with a schema that requires the value `base64`. +If `format: byte` is used for a multipart field that has an Encoding Object with a `headers` field containing `Content-Transfer-Encoding` with a schema that disallows `base64`, the result is undefined for serialization and parsing. Per the JSON Schema specification, `contentMediaType` without `contentEncoding` present is treated as if `contentEncoding: identity` were present. While useful for embedding text documents such as `text/html` into JSON strings, it is not useful for a `multipart/form-data` part, as it just causes the document to be treated as `text/plain` instead of its actual media type. Use the Encoding Object without `contentMediaType` if no `contentEncoding` is required.