Media Type Registry

Forms: Ordered name-value pairs

Media Type(s):

• application/x-www-form-urlencoded (IANA) – WHATWG URL, HTTP 4.01 §17.13.4.1 (historical), RFC1866 §8.2.1 (historical but cited by later RFCs and the OAS)
• multipart/form-data (IANA) – RFC7578

OAS References:

• Encoding By Name
• Encoding the x-www-form-urlencoded Media Type
• Encoding multipart Media Types
• Appendix C: Using RFC6570-Based Serialization
• Appendix E: Percent-Encoding and Form Media Types

Summary

Web-style form data consists of name-value pairs, with duplicate names allowed, and are structured either in a way compatible with URI form query strings or as a multipart document.

Remarks

Both form media types use the Encoding Object to map object properties from schema-ready data structures to name-value pairs, with special rules for arrays causing each array value to be treated as a separate pair with the same name. While the ordering of pairs is significant in these formats, the OAS does not (as of v3.2) provide a way to control such ordering.

As of OAS v3.2, endpoint URL query strings can be modeled as a media type using in: querystring in the Parameter Object. The query string can also be modeled using multiple in: query Parameter Objects through mechanisms similar to the Encoding Object.

Note that URL-encoded forms have been defined by different standards organizations at different times, leading to inconsistencies regarding percent-encoding in later standards and implementations; this is addressed in detail in Appendix E.