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 By Position
• 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
• Non-JSON Data

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.

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.

Since v3.3, the OAS provides for a way to preserve ordering, by treating the deserialized content as an array, rather than an object.

Examples

Treating the data as an object, this data:

{
  "alpha": 1,
  "beta": 2,
  "gamma": [ 3, 4 ]
}

… serializes as application/x-www-form-urlencoded to: alpha=1&beta=2&gamma=3&gamma=4

and serializes as multipart/form-data; boundary="4aKOX" to:

--4aKOX
Content-Disposition: form-data; name="alpha"

1
--4aKOX
Content-Disposition: form-data; name="beta"

2
--4aKOX
Content-Disposition: form-data; name="gamma"

3
--4aKOX
Content-Disposition: form-data; name="gamma"

4
--4aKOX--

If preservation of value/part order is important, treat the data as an array, where each array item is an object consisting of the key/value pair:

[
  { "alpha": 1 },
  { "beta": 2 },
  { "gamma": 3 }
  { "gamma": 4 }
}

This distinction can be made clear to a deserializer by using type: array in the schema, using the process as described in Non-JSON Data.