Note RFC6570 issues with form-data (3.1.1 add-on to 3818)

OAS 3.1 allows using RFC6570-style serialization with
`multipart/form-data`, but this can interact with the requirements
of the media type in unexpected and arguably incorrect ways.

Author: handrews

versions/3.1.1.md

@@ -4218,6 +4218,10 @@ 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 to the `Content-Disposition` part header, and the values are placed in the corresponding part body; the `?`, `=`, and `&` characters are not used.
+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.
+RFC7578 discusses character set and encoding issues for `multipart/form-data` in detail, and it is RECOMMENDED that OpenAPI Description authors read this guidance carefully before deciding to use RFC6570-based serialization with this media type.
+
 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.