OpenAPI Specification v3.0.4
Version 3.0.4
diff --git a/oas/v3.1.2.html b/oas/v3.1.2.html index 0d7f9ccb77..386819f4c7 100644 --- a/oas/v3.1.2.html +++ b/oas/v3.1.2.html @@ -237,8 +237,8 @@ "generatedSubtitle": "19 September 2025" } - -
OpenAPI Specification v3.1.2
Version 3.1.2
diff --git a/oas/v3.2.0.html b/oas/v3.2.0.html index b794f12c20..8f5a6fbd77 100644 --- a/oas/v3.2.0.html +++ b/oas/v3.2.0.html @@ -404,7 +404,7 @@OpenAPI Specification v3.2.0
$self
stringThis string MUST be in the form of a URI reference as defined by [RFC3986] Section 4.1. The $self field provides the self-assigned URI of this document, which also serves as its base URI in accordance with [RFC3986] Section 5.1.1. Implementations MUST support identifying the targets of API description URIs using the URI defined by this field when it is present. See Establishing the Base URI for the base URI behavior when $self is absent or relative, and see Appendix F for examples of using $self to resolve references.
+This string MUST be in the form of a URI reference as defined by [RFC3986] Section 4.1. The $self field provides the self-assigned URI of this document, which also serves as its base URI in accordance with [RFC3986] Section 5.1.1. Implementations MUST support identifying the targets of API description URIs using the URI defined by this field when it is present. See Establishing the Base URI for the base URI behavior when $self is absent or relative, and see Appendix F for examples of using $self to resolve references.
info
@@ -1804,7 +1804,7 @@ OpenAPI Specification v3.2.0
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.
+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:
@@ -2333,7 +2333,7 @@ OpenAPI Specification v3.2.0
MUST be used as shown under Example: Multipart Form with Multiple Files.
-A single encoding definition applied to a single value, with the mapping of Encoding Objects to values determined by the Media Type Object as described under Encoding Usage and Restrictions.
+A single encoding definition applied to a single value, with the mapping of Encoding Objects to values determined by the Media Type Object as described under Encoding Usage and Restrictions.
See Appendix B for a discussion of converting values of various types to string representations.
See Appendix E for a detailed examination of percent-encoding concerns for form media types.
@@ -2643,7 +2643,7 @@ OpenAPI Specification v3.2.0
As described in [RFC2557], a set of resources making up a web page can be sent in a multipart/related payload, preserving links from the text/html document to subsidiary resources such as scripts, style sheets, and images by defining a Content-Location header for each page.
The first part is used as the root resource (unless using Content-ID, which RFC2557 advises against and is forbidden in this example), so we use prefixItems and prefixEncoding to define that it must be an HTML resource, and then allow any of several different types of resources in any order to follow.
-The Content-Location header is defined using content: {text/plain: {...}} to avoid percent-encoding its URI value; see Appendix D for further details.
+The Content-Location header is defined using content: {text/plain: {...}} to avoid percent-encoding its URI value; see Appendix D for further details.
components:
headers:
RFC2557NoContentId:
@@ -2694,7 +2694,7 @@ OpenAPI Specification v3.2.0
For multipart/byteranges [RFC9110] Section 14.6, a Content-Range header is required:
-See Appendix D for an explanation of why content: {text/plain: {...}} is used to describe the header value.
+See Appendix D for an explanation of why content: {text/plain: {...}} is used to describe the header value.
multipart/byteranges:
itemSchema:
$comment: A single range of bytes from a video
@@ -3538,7 +3538,7 @@ OpenAPI Specification v3.2.0
MUST be handled by placing each value on a separate line, without the header name or the : delimiter.
-
Note also that any URI percent-encoding, base64 encoding, or other escaping MUST be performed prior to supplying the data to OAS tooling; see Appendix D for details.
+Note also that any URI percent-encoding, base64 encoding, or other escaping MUST be performed prior to supplying the data to OAS tooling; see Appendix D for details.
The following example shows two different ways to describe Set-Cookie headers that require cookies named "lang" and "foo", as well as a "urlSafeData" cookie that is expected to be percent-encoded. The first uses content in order to show exactly how such examples are formatted, but also notes the limitations of schema constraints with multi-line text. The second shows the use of style: "simple", which produces the same serialized example text (with each line corresponding to one Set-Cookie: line in the HTTP response), but allows schema constraints on each cookie; note that the percent-encoding is already applied in the dataValue field of the example:
components:
headers:
string$self field provides the self-assigned URI of this document, which also serves as its base URI in accordance with [RFC3986] Section 5.1.1. Implementations MUST support identifying the targets of API description URIs using the URI defined by this field when it is present. See Establishing the Base URI for the base URI behavior when $self is absent or relative, and see Appendix F for examples of using $self to resolve references.$self field provides the self-assigned URI of this document, which also serves as its base URI in accordance with [RFC3986] Section 5.1.1. Implementations MUST support identifying the targets of API description URIs using the URI defined by this field when it is present. See Establishing the Base URI for the base URI behavior when $self is absent or relative, and see Appendix F for examples of using $self to resolve references.OpenAPI Specification v3.2.0
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.
+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:
@@ -2333,7 +2333,7 @@ OpenAPI Specification v3.2.0
MUST be used as shown under Example: Multipart Form with Multiple Files.
-A single encoding definition applied to a single value, with the mapping of Encoding Objects to values determined by the Media Type Object as described under Encoding Usage and Restrictions.
+A single encoding definition applied to a single value, with the mapping of Encoding Objects to values determined by the Media Type Object as described under Encoding Usage and Restrictions.
See Appendix B for a discussion of converting values of various types to string representations.
See Appendix E for a detailed examination of percent-encoding concerns for form media types.
@@ -2643,7 +2643,7 @@ OpenAPI Specification v3.2.0
As described in [RFC2557], a set of resources making up a web page can be sent in a multipart/related payload, preserving links from the text/html document to subsidiary resources such as scripts, style sheets, and images by defining a Content-Location header for each page.
The first part is used as the root resource (unless using Content-ID, which RFC2557 advises against and is forbidden in this example), so we use prefixItems and prefixEncoding to define that it must be an HTML resource, and then allow any of several different types of resources in any order to follow.
-The Content-Location header is defined using content: {text/plain: {...}} to avoid percent-encoding its URI value; see Appendix D for further details.
+The Content-Location header is defined using content: {text/plain: {...}} to avoid percent-encoding its URI value; see Appendix D for further details.
components:
headers:
RFC2557NoContentId:
@@ -2694,7 +2694,7 @@ OpenAPI Specification v3.2.0
For multipart/byteranges [RFC9110] Section 14.6, a Content-Range header is required:
-See Appendix D for an explanation of why content: {text/plain: {...}} is used to describe the header value.
+See Appendix D for an explanation of why content: {text/plain: {...}} is used to describe the header value.
multipart/byteranges:
itemSchema:
$comment: A single range of bytes from a video
@@ -3538,7 +3538,7 @@ OpenAPI Specification v3.2.0
MUST be handled by placing each value on a separate line, without the header name or the : delimiter.
-
Note also that any URI percent-encoding, base64 encoding, or other escaping MUST be performed prior to supplying the data to OAS tooling; see Appendix D for details.
+Note also that any URI percent-encoding, base64 encoding, or other escaping MUST be performed prior to supplying the data to OAS tooling; see Appendix D for details.
The following example shows two different ways to describe Set-Cookie headers that require cookies named "lang" and "foo", as well as a "urlSafeData" cookie that is expected to be percent-encoded. The first uses content in order to show exactly how such examples are formatted, but also notes the limitations of schema constraints with multi-line text. The second shows the use of style: "simple", which produces the same serialized example text (with each line corresponding to one Set-Cookie: line in the HTTP response), but allows schema constraints on each cookie; note that the percent-encoding is already applied in the dataValue field of the example:
components:
headers: