Describes a single operation parameter.
All API URLs MUST successfully parse and percent-decode using [RFC3986] rules.
Content in the application/x-www-form-urlencoded format, including query strings produced by Parameter Objects with in: "query", MUST also successfully parse and percent-decode using [WHATWG-URL] rules, including treating non-percent-encoded + as an escaped space character.
These requirements are specified in terms of percent-decoding rules, which are consistently tolerant across different versions of the various standards that apply to URIs.
Percent-encoding is performed in several places:
- By [RFC6570] implementations (or simulations thereof; see Appendix C)
- By the Parameter or Encoding Objects when incorporating a value serialized with a Media Type Object for a media type that does not already incorporate URI percent-encoding
- By the user, prior to passing data through RFC6570’s reserved expansion process
When percent-encoding, the safest approach is to percent-encode all characters not in RFC3986’s “unreserved” set, and for form-urlencoded to also percent-encode the tilde character (~) to align with historical requirements that are traced back to [RFC1738], the URI RFC at the time form-urlencoded was created.
This approach is used in examples in this specification.
For form-urlencoded, while the encoding algorithm given by [WHATWG-URL] requires escaping the space character as +, percent-encoding it as %20 also meets the above requirements.
Examples in this specification will prefer %20 when using RFC6570’s default (non-reserved) form-style expansion, and + otherwise.
Reserved characters MUST NOT be percent-encoded when being used for reserved purposes such as &=+ for form-urlencoded or , for delimiting non-exploded array and object values in RFC6570 expansions.
The result of inserting non-percent-encoded delimiters into data using manual percent-encoding, including via RFC6570’s reserved expansion rules, is undefined and will likely prevent implementations from parsing the results back into the correct data structures.
In some cases, such as inserting / into path parameter values, doing so is explicitly forbidden by this specification.
See also:
- Appendix C for guidance on using or simulating/extending RFC6570 implementations.
- Appendix D for guidance on percent-encoding and cookies, as well as other escaping approaches for headers and cookies.
- Appendix E for a thorough discussion of percent-encoding options, compatibility, and handling OAS-defined delimiters that are not allowed by RFC3986.
The rules in this section apply to both the Parameter and Header Objects, both of which use the same mechanisms.
When showing serialized examples, such as with the Example Object’s serializedValue or externalValue fields, in most cases the value to show is just the value, with all relevant percent-encoding or other encoding/escaping applied, and also including any delimiters produced by the style and explode configuration.
In cases where the name is an inherent part of constructing the serialization, such as the name=value pairs produced by style: "form" or the combination of style: "simple", explode: true, the name and any delimiter between the name and value MUST be included.
The matrix and label styles produce a leading delimiter which is always a valid part of the serialization and MUST be included.
The RFC6570 operators corresponding to style: "form" produce a leading delimiter of either ? or & depending on the exact syntax used.
As the suitability of either delimiter depends on where in the query string the parameter occurs, as well as whether it is in a URI or in application/x-www-form-urlencoded content, this leading delimiter MUST NOT be included in examples of individual parameters or media type documents.
For in: "cookie", style: "form", neither the & nor ? delimiters are ever correct; see Appendix D: Serializing Headers and Cookies for more details.
For headers, the header name MUST NOT be included as part of the serialization, as it is never part of the RFC6570-derived result.
However, names produced by style: "simple", explode: "true" are included as they appear within the header value, not as separate headers.
See the Header Object for special rules for showing examples of the Set-Cookie response header, which violates the normal rules for multiple header values.
The following section illustrates these rules.
A header parameter with an array of 64-bit integer numbers:
name: X-Token
in: header
description: token to be passed as a header
required: true
schema:
type: array
items:
type: integer
format: int64
style: simple
examples:
Tokens:
dataValue: [12345678, 90099]
serializedValue: "12345678,90099"
A cookie parameter with an exploded object (the default for style: "cookie"):
name: cookie
in: cookie
style: cookie
schema:
type: object
properties:
greeting:
type: string
code:
type: integer
minimum: 0
examples:
Object:
description: |
Note that the comma (,) has been pre-percent-encoded
to "%2C" in the data, as it is forbidden in
cookie values. However, the exclamation point (!)
is legal in cookies, so it can be left unencoded.
dataValue: {
"greeting": "Hello%2C world!",
"code": 42
}
serializedValue: "greeting=Hello%2C world!; code=42"
A cookie parameter relying on the percent-encoding behavior of the default style: "form":
name: greeting
in: cookie
schema:
type: string
examples:
Greeting:
description: |
Note that in this approach, RFC6570's percent-encoding
process applies, so unsafe characters are not
pre-percent-encoded. This results in all non-URL-safe
characters, rather than just the one non-cookie-safe
character, getting percent-encoded.
dataValue: "Hello, world!"
serializedValue: "greeting=Hello%2C%20world%21"
A path parameter of a string value:
name: username
in: path
description: username to fetch
required: true
schema:
type: string
examples:
"Edsger Dijkstra":
dataValue: edijkstra
serializedValue: edijkstra
Diṅnāga:
dataValue: diṅnāga
serializedValue: di%E1%B9%85n%C4%81ga
Al-Khwarizmi:
dataValue: "الخوارزميّ"
serializedValue: "%D8%A7%D9%84%D8%AE%D9%88%D8%A7%D8%B1%D8%B2%D9%85%D9%8A%D9%91"
An optional query parameter of a string value, allowing multiple values by repeating the query parameter
(Note that we use "%20" in place of " " (space) because that is how RFC6570 handles it; for guidance on using + to represent the space character, see Appendix E for more guidance on these escaping options):
name: thing
in: query
required: false
schema:
type: array
items:
type: string
style: form
explode: true
examples:
ObjectList:
dataValue: ["one thing", "another thing"]
serializedValue: "thing=one%20thing&thing=another%20thing"
A free-form query parameter, allowing arbitrary parameters of type: "integer":
in: query
name: freeForm
schema:
type: object
additionalProperties:
type: integer
style: form
examples:
Pagination:
dataValue: {
"page": 4,
"pageSize": 50
}
serializeValue: page=4&pageSize=50
A complex parameter using content to define serialization, with multiple levels and types of examples shown to make the example usage options clear — note that dataValue is the same at both levels and does not need to be shown in both places in normal usage, but serializedValue is different:
in: query
name: coordinates
content:
application/json:
schema:
type: object
required:
- lat
- long
properties:
lat:
type: number
long:
type: number
examples:
dataValue: {
"lat": 10,
"long": 60
}
serializedValue: '{"lat":10,"long":60}'
examples:
dataValue: {
"lat": 10,
"long": 60
}
serializedValue: coordinates=%7B%22lat%22%3A10%2C%22long%22%3A60%7D
A querystring parameter using regular form encoding, but managed with a Media Type Object.
This shows spaces being handled per the application/x-www-form-urlencoded media type rules (encode as +) rather than the RFC6570 process (encode as %20); see Appendix E for further guidance on this distinction.
Examples are shown at both the media type and parameter level to emphasize that, since application/x-www-form-urlencoded is suitable for use in query strings by definition, no further encoding or escaping is applied to the serialized media type value:
in: querystring
content:
application/x-www-form-urlencoded:
schema:
type: object
properties:
foo:
type: string
bar:
type: boolean
examples:
spacesAndPluses:
description: Note handling of spaces and "+" per media type.
dataValue:
foo: a + b
bar: true
serializedValue: foo=a+%2B+b&bar=true
examples:
spacesAndPluses:
description: |
Note that no additional percent encoding is done, as this
media type is URI query string-ready by definition.
dataValue:
foo: a + b
bar: true
serializedValue: foo=a+%2B+b&bar=true
A querystring parameter that uses JSON for the entire string (not as a single query parameter value).
The dataValue field is shown at both levels to fully illustrate both ways of providing an example.
As seen below, this is redundant and need not be done in practice:
in: querystring
name: json
content:
application/json:
schema:
type: object
properties:
numbers:
type: array
items:
type: integer
flag:
type: [boolean, "null"]
examples:
TwoNoFlag:
description: Serialize with minimized whitespace
dataValue: {
"numbers": [1, 2],
"flag": null
}
serializedValue: '{"numbers":[1,2],"flag":null}'
examples:
TwoNoFlag:
dataValue: {
"numbers": [1, 2],
"flag": null
}
serializedValue: "%7B%22numbers%22%3A%5B1%2C2%5D%2C%22flag%22%3Anull%7D"
Assuming a path of /foo, a server of https://example.com, the full URL incorporating the value from serializedValue would be:
https://example.com/foo?%7B%22numbers%22%3A%5B1%2C2%5D%2C%22flag%22%3Anull%7D
A querystring parameter that uses JSONPath.
Note that in this example we not only do not repeat dataValue, but we use the shorthand example because the application/jsonpath value is a string that, at the media type level, is serialized as-is:
in: querystring
name: selector
content:
application/jsonpath:
schema:
type: string
example: $.a.b[1:1]
examples:
Selector:
serializedValue: "%24.a.b%5B1%3A1%5D"
As there is not, as of this writing, a registered mapping between the JSON Schema data model and JSONPath, the details of the string’s allowed structure would need to be conveyed either in a human-readable description field, or through a mechanism outside of the OpenAPI Description, such as a JSON Schema for the data structure to be queried.
Assuming a path of /foo and a server of https://example.com, the full URL incorporating the value from serializedValue would be:
https://example.com/foo?%24.a.b%5B1%3A1%5D
