From bacc8ba071d124e5446a3065875a353daaadced7 Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Mon, 29 Jun 2026 10:27:32 -0700 Subject: [PATCH 1/3] provide additional guidance on usage of "style" with multipart/form-data see also https://github.com/OAI/OpenAPI-Specification/discussions/5406 --- src/oas.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 7c115959f8..d7b486924e 100644 --- a/src/oas.md +++ b/src/oas.md @@ -4893,10 +4893,15 @@ Implementations of this specification MAY use an implementation of RFC6570 to pe Note that when using `style: "form"` RFC6570 expansion to produce an `application/x-www-form-urlencoded` HTTP message body, it is necessary to remove the `?` prefix that is produced to satisfy the URI query string syntax. -When using `style` and similar keywords to produce a `multipart/form-data` body, the query string names are placed in the `name` parameter of the `Content-Disposition` part header, and the values are placed in the corresponding part body; the `?`, `=`, and `&` characters are not used, and URI percent encoding is not applied, regardless of the value of `allowReserved`. +When using `style` and/or `explode` to produce a `multipart/form-data` body, the query string name is placed in the `name` parameter of the `Content-Disposition` part header, and the value is placed in the corresponding part body; the `?`, `=`, and `&` characters are not used, and URI percent encoding is not applied, regardless of the value of `allowReserved`. Note that while [RFC7578](https://datatracker.ietf.org/doc/html/rfc7578) allows using [[RFC3986]] percent-encoding in "file names", it does not otherwise address the use of percent-encoding within the format. Users are expected to provide names and data with any escaping necessary for conformance with RFC7578 already applied. +Due to these restrictions, the only `style` and `explode` combinations that can be used in `multipart/form-data` are: +- `style: form` with any primitive type +- `style: form` and `explode: false` with arrays and objects (note that due to the omission of the query string name, this serialization is equivalent to `style: simple`) +- `style: spaceDelimited` or `style: pipeDelimited` and `explode: false` with arrays and objects + Note also that not all RFC6570 implementations support all four levels of operators, all of which are needed to fully support the OpenAPI Specification's usage. Using an implementation with a lower level of support will require additional manual construction of URI Templates to work around the limitations. From 836fd402ef8d784e1eb5a3c4c522a5872348187c Mon Sep 17 00:00:00 2001 From: Karen Etheridge Date: Thu, 2 Jul 2026 15:30:46 -0700 Subject: [PATCH 2/3] Update src/oas.md Co-authored-by: Henry Andrews --- src/oas.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index d7b486924e..8e8deec12f 100644 --- a/src/oas.md +++ b/src/oas.md @@ -4897,11 +4897,12 @@ When using `style` and/or `explode` to produce a `multipart/form-data` body, the Note that while [RFC7578](https://datatracker.ietf.org/doc/html/rfc7578) allows using [[RFC3986]] percent-encoding in "file names", it does not otherwise address the use of percent-encoding within the format. Users are expected to provide names and data with any escaping necessary for conformance with RFC7578 already applied. -Due to these restrictions, the only `style` and `explode` combinations that can be used in `multipart/form-data` are: +Due to these restrictions, the only `style` and `explode` combinations that can safely be used in `multipart/form-data` are: - `style: form` with any primitive type - `style: form` and `explode: false` with arrays and objects (note that due to the omission of the query string name, this serialization is equivalent to `style: simple`) - `style: spaceDelimited` or `style: pipeDelimited` and `explode: false` with arrays and objects +The behavior of other combinations with `multipart/form-data` is undefined. Note also that not all RFC6570 implementations support all four levels of operators, all of which are needed to fully support the OpenAPI Specification's usage. Using an implementation with a lower level of support will require additional manual construction of URI Templates to work around the limitations. From 62a22e98ad6720961c954709d95a538d95416c17 Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Wed, 8 Jul 2026 10:42:37 -0700 Subject: [PATCH 3/3] Fix linting error. --- src/oas.md | 1 + 1 file changed, 1 insertion(+) diff --git a/src/oas.md b/src/oas.md index 8e8deec12f..33d5f6fb3b 100644 --- a/src/oas.md +++ b/src/oas.md @@ -4898,6 +4898,7 @@ Note that while [RFC7578](https://datatracker.ietf.org/doc/html/rfc7578) allows Users are expected to provide names and data with any escaping necessary for conformance with RFC7578 already applied. Due to these restrictions, the only `style` and `explode` combinations that can safely be used in `multipart/form-data` are: + - `style: form` with any primitive type - `style: form` and `explode: false` with arrays and objects (note that due to the omission of the query string name, this serialization is equivalent to `style: simple`) - `style: spaceDelimited` or `style: pipeDelimited` and `explode: false` with arrays and objects