The OpenAPI Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 3.1) SHALL designate the OAS feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.1.0 and 3.1.1 for example.
OpenAPI Specification v3.1.0
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986].
-Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986].
Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986] Section 4.2.
+Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986] Section 5.2.
If a URI contains a fragment identifier, then the fragment should be resolved per the fragment resolution mechanism of the referenced document. If the representation of the referenced document is JSON or YAML, then the fragment identifier SHOULD be interpreted as a JSON-Pointer as per [RFC6901].
-Relative references in Schema Objects, including any that appear as $id values, use the nearest parent $id as a Base URI, as described by JSON Schema Specification Draft 2020-12. If no parent schema contains an $id, then the Base URI MUST be determined according to [RFC3986].
Relative references in Schema Objects, including any that appear as $id values, use the nearest parent $id as a Base URI, as described by JSON Schema Specification Draft 2020-12. If no parent schema contains an $id, then the Base URI MUST be determined according to [RFC3986] Section 5.1.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986]. +
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Unless specified otherwise, relative references are resolved using the URLs defined in the Server Object as a Base URL. Note that these themselves MAY be relative to the referring document.
In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.
@@ -1262,7 +1262,7 @@OpenAPI Specification v3.1.0
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
+The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
responses
@@ -1443,7 +1443,7 @@ OpenAPI Specification v3.1.0
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
-header - Custom headers that are expected as part of the request. Note that [RFC7230] states header names are case insensitive.
+header - Custom headers that are expected as part of the request. Note that [RFC7230] Page 22 states header names are case insensitive.
cookie - Used to pass a specific cookie value to the API.
@@ -1512,7 +1512,7 @@ OpenAPI Specification v3.1.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
schema
@@ -1566,25 +1566,25 @@ OpenAPI Specification v3.1.0
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
label
primitive, array, objectpathLabel style parameters defined by [RFC6570]
+Label style parameters defined by [RFC6570] Section 3.2.5
form
primitive, array, objectquery, cookieForm style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
+Form style parameters defined by [RFC6570] Section 3.2.8. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
simple
arraypath, headerSimple style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
+Simple style parameters defined by [RFC6570] Section 3.2.2. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
spaceDelimited
@@ -2090,7 +2090,7 @@ OpenAPI Specification v3.1.0
In contrast with the 2.0 specification, file input/output content in OpenAPI is described with the same semantics as any other schema type.
-In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in [RFC4648], including “base64” and “base64url”, as well as “quoted-printable” from [RFC2045]. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.
+In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in [RFC4648], including “base64” and “base64url”, as well as “quoted-printable” from [RFC2045] Section 6.7. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.
JSON Schema also offers a contentMediaType keyword. However, when the media type is already specified by the Media Type Object’s key, or by the contentType field of an Encoding Object, the contentMediaType keyword SHALL be ignored if present.
Examples:
Content transferred in binary (octet-stream) MAY omit schema:
@@ -2241,7 +2241,7 @@ OpenAPI Specification v3.1.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
@@ -2387,7 +2387,7 @@ OpenAPI Specification v3.1.0
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
content
@@ -2878,7 +2878,7 @@ OpenAPI Specification v3.1.0
= "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
"^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
-
Here, json-pointer is taken from [RFC6901], char from [RFC7159] and token from [RFC7230].
+Here, json-pointer is taken from [RFC6901], char from [RFC7159] Section 7 and token from [RFC7230] Section 3.2.6.
The name identifier is case-sensitive, whereas token is not.
The table below provides examples of runtime expressions and examples of their use in a value:
@@ -3928,7 +3928,7 @@ OpenAPI Specification v3.1.0
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
bearerFormat
diff --git a/oas/v2.0.html b/oas/v2.0.html
index 02413fe9a6..8afba6fe4a 100644
--- a/oas/v2.0.html
+++ b/oas/v2.0.html
@@ -165,7 +165,7 @@
"publishISODate": "2014-09-08T00:00:00.000Z",
"generatedSubtitle": "08 September 2014"
}
-
+
OpenAPI Specification v2.0
Version 2.0
@@ -218,7 +218,7 @@ OpenAPI Specification v2.0
-The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
+The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
The Swagger specification is licensed under The Apache License, Version 2.0.
Swagger™ is a project used to describe and document RESTful APIs.
@@ -274,7 +274,7 @@ OpenAPI Specification v2.0
-The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by [RFC7231] and in the IANA Status Code Registry.
+The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by [RFC7231] Section 6 and in the IANA Status Code Registry.
The files describing the RESTful API in accordance with the Swagger specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to
@@ -357,13 +357,13 @@
OpenAPI Specification v2.0
date
stringdateAs defined by full-date - [RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
dateTime
stringdate-timeAs defined by date-time - [RFC3339]
+As defined by date-time - [RFC3339] Section 5.6
password
@@ -2076,7 +2076,7 @@ OpenAPI Specification v2.0
A simple object to allow referencing other definitions in the specification. It can be used to reference parameters and responses that are defined at the top level for reuse.
-The Reference Object is a JSON Reference that uses a JSON Pointer as its value. For this specification, only canonical dereferencing is supported.
+The Reference Object is a JSON Reference that uses a JSON Pointer [RFC6901] as its value. For this specification, only canonical dereferencing is supported.
@@ -3309,8 +3309,14 @@ OpenAPI Specification v2.0
- - [RFC6838]
-
+
- [RFC2119]
-
+ Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+
- [RFC3339]
-
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
+
- [RFC6838]
-
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
+
- [RFC6901]
-
+ JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901
- [RFC7231]
-
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
diff --git a/oas/v3.0.0.html b/oas/v3.0.0.html
index 907c6d4c3f..f4edf9c5ce 100644
--- a/oas/v3.0.0.html
+++ b/oas/v3.0.0.html
@@ -254,7 +254,7 @@ OpenAPI Specification v3.0.0
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -354,13 +354,13 @@ OpenAPI Specification v3.0.0
[RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
dateTime
stringdate-timeAs defined by date-time - [RFC3339]
+As defined by date-time - [RFC3339] Section 5.6
password
@@ -374,7 +374,7 @@ OpenAPI Specification v3.0.0
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
@@ -1240,7 +1240,7 @@ OpenAPI Specification v3.0.0
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
responses
@@ -1420,7 +1420,7 @@ OpenAPI Specification v3.0.0
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
-header - Custom headers that are expected as part of the request. Note that [RFC7230] states header names are case insensitive.
+header - Custom headers that are expected as part of the request. Note that [RFC7230] Page 22 states header names are case insensitive.
cookie - Used to pass a specific cookie value to the API.
@@ -1489,7 +1489,7 @@ OpenAPI Specification v3.0.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
schema
@@ -1543,25 +1543,25 @@ OpenAPI Specification v3.0.0
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
label
primitive, array, objectpathLabel style parameters defined by [RFC6570]
+Label style parameters defined by [RFC6570] Section 3.2.5
form
primitive, array, objectquery, cookieForm style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
+Form style parameters defined by [RFC6570] Section 3.2.8. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
simple
arraypath, headerSimple style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
+Simple style parameters defined by [RFC6570] Section 3.2.2. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
spaceDelimited
@@ -2214,7 +2214,7 @@ OpenAPI Specification v3.0.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
@@ -2362,7 +2362,7 @@ OpenAPI Specification v3.0.0
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
content
@@ -3975,7 +3975,7 @@ OpenAPI Specification v3.0.0
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235].
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1.
bearerFormat
@@ -4313,6 +4313,8 @@ OpenAPI Specification v3.0.0
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+ [RFC3339]
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC6570]
diff --git a/oas/v3.0.1.html b/oas/v3.0.1.html
index fbde7dccb9..94db0d0cdb 100644
--- a/oas/v3.0.1.html
+++ b/oas/v3.0.1.html
@@ -259,7 +259,7 @@ OpenAPI Specification v3.0.1
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -359,13 +359,13 @@ OpenAPI Specification v3.0.1
[RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
dateTime
stringdate-timeAs defined by date-time - [RFC3339]
+As defined by date-time - [RFC3339] Section 5.6
password
@@ -379,7 +379,7 @@ OpenAPI Specification v3.0.1
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
@@ -1245,7 +1245,7 @@ OpenAPI Specification v3.0.1
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
responses
@@ -1425,7 +1425,7 @@ OpenAPI Specification v3.0.1
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
-header - Custom headers that are expected as part of the request. Note that [RFC7230] states header names are case insensitive.
+header - Custom headers that are expected as part of the request. Note that [RFC7230] Page 22 states header names are case insensitive.
cookie - Used to pass a specific cookie value to the API.
@@ -1494,7 +1494,7 @@ OpenAPI Specification v3.0.1
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
schema
@@ -1548,25 +1548,25 @@ OpenAPI Specification v3.0.1
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
label
primitive, array, objectpathLabel style parameters defined by [RFC6570]
+Label style parameters defined by [RFC6570] Section 3.2.5
form
primitive, array, objectquery, cookieForm style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
+Form style parameters defined by [RFC6570] Section 3.2.8. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
simple
arraypath, headerSimple style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
+Simple style parameters defined by [RFC6570] Section 3.2.2. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
spaceDelimited
@@ -2219,7 +2219,7 @@ OpenAPI Specification v3.0.1
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
@@ -2367,7 +2367,7 @@ OpenAPI Specification v3.0.1
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
content
@@ -3921,7 +3921,7 @@ OpenAPI Specification v3.0.1
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235].
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1.
bearerFormat
@@ -4264,6 +4264,8 @@ OpenAPI Specification v3.0.1
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+ [RFC3339]
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC6570]
diff --git a/oas/v3.0.2.html b/oas/v3.0.2.html
index 96aa375913..02c2a94b40 100644
--- a/oas/v3.0.2.html
+++ b/oas/v3.0.2.html
@@ -269,7 +269,7 @@ OpenAPI Specification v3.0.2
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -360,12 +360,12 @@ OpenAPI Specification v3.0.2
[RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
stringdate-timeAs defined by date-time - [RFC3339]
+As defined by date-time - [RFC3339] Section 5.6
stringOpenAPI Specification v3.0.2
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
@@ -1264,7 +1264,7 @@ OpenAPI Specification v3.0.2
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
responses
@@ -1444,7 +1444,7 @@ OpenAPI Specification v3.0.2
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
-header - Custom headers that are expected as part of the request. Note that [RFC7230] states header names are case insensitive.
+header - Custom headers that are expected as part of the request. Note that [RFC7230] Page 22 states header names are case insensitive.
cookie - Used to pass a specific cookie value to the API.
@@ -1513,7 +1513,7 @@ OpenAPI Specification v3.0.2
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
schema
@@ -1567,25 +1567,25 @@ OpenAPI Specification v3.0.2
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
label
primitive, array, objectpathLabel style parameters defined by [RFC6570]
+Label style parameters defined by [RFC6570] Section 3.2.5
form
primitive, array, objectquery, cookieForm style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
+Form style parameters defined by [RFC6570] Section 3.2.8. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
simple
arraypath, headerSimple style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
+Simple style parameters defined by [RFC6570] Section 3.2.2. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
spaceDelimited
@@ -2238,7 +2238,7 @@ OpenAPI Specification v3.0.2
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
@@ -2386,7 +2386,7 @@ OpenAPI Specification v3.0.2
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
content
@@ -3942,7 +3942,7 @@ OpenAPI Specification v3.0.2
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235].
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1.
bearerFormat
@@ -4290,6 +4290,8 @@ OpenAPI Specification v3.0.2
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+ [RFC3339]
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC6570]
diff --git a/oas/v3.0.3.html b/oas/v3.0.3.html
index 4c7f42246d..04acafbb29 100644
--- a/oas/v3.0.3.html
+++ b/oas/v3.0.3.html
@@ -270,7 +270,7 @@ OpenAPI Specification v3.0.3
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -362,12 +362,12 @@ OpenAPI Specification v3.0.3
[RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
stringdate-timeAs defined by date-time - [RFC3339]
+As defined by date-time - [RFC3339] Section 5.6
stringOpenAPI Specification v3.0.3
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
@@ -1266,7 +1266,7 @@ OpenAPI Specification v3.0.3
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
responses
@@ -1446,7 +1446,7 @@ OpenAPI Specification v3.0.3
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
-header - Custom headers that are expected as part of the request. Note that [RFC7230] states header names are case insensitive.
+header - Custom headers that are expected as part of the request. Note that [RFC7230] Page 22 states header names are case insensitive.
cookie - Used to pass a specific cookie value to the API.
@@ -1515,7 +1515,7 @@ OpenAPI Specification v3.0.3
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
schema
@@ -1569,25 +1569,25 @@ OpenAPI Specification v3.0.3
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
label
primitive, array, objectpathLabel style parameters defined by [RFC6570]
+Label style parameters defined by [RFC6570] Section 3.2.5
form
primitive, array, objectquery, cookieForm style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
+Form style parameters defined by [RFC6570] Section 3.2.8. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
simple
arraypath, headerSimple style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
+Simple style parameters defined by [RFC6570] Section 3.2.2. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
spaceDelimited
@@ -2239,7 +2239,7 @@ OpenAPI Specification v3.0.3
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
@@ -2387,7 +2387,7 @@ OpenAPI Specification v3.0.3
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
content
@@ -2877,7 +2877,7 @@ OpenAPI Specification v3.0.3
= "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
"^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
-
Here, json-pointer is taken from [RFC6901], char from [RFC7159] and token from [RFC7230].
+Here, json-pointer is taken from [RFC6901], char from [RFC7159] Section 7 and token from [RFC7230] Section 3.2.6.
The name identifier is case-sensitive, whereas token is not.
The table below provides examples of runtime expressions and examples of their use in a value:
@@ -3956,7 +3956,7 @@ OpenAPI Specification v3.0.3
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
bearerFormat
@@ -4331,6 +4331,8 @@ OpenAPI Specification v3.0.3
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+ [RFC3339]
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC6570]
diff --git a/oas/v3.1.0.html b/oas/v3.1.0.html
index 4f53076434..f4d70949d2 100644
--- a/oas/v3.1.0.html
+++ b/oas/v3.1.0.html
@@ -252,7 +252,7 @@ OpenAPI Specification v3.1.0
Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.
Each template expression in the path MUST correspond to a path parameter that is included in the Path Item itself and/or in each of the Path Item’s Operations. An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required.
-The value for these path parameters MUST NOT contain any unescaped “generic syntax” characters described by [RFC3986]: forward slashes (/), question marks (?), or hashes (#).
+The value for these path parameters MUST NOT contain any unescaped “generic syntax” characters described by [RFC3986] Section 3: forward slashes (/), question marks (?), or hashes (#).
Media type definitions are spread across several resources.
The media type definitions SHOULD be in compliance with [RFC6838].
@@ -271,7 +271,7 @@ OpenAPI Specification v3.1.0
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 3.1) SHALL designate the OAS feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.1.0 and 3.1.1 for example.
@@ -345,12 +345,12 @@ OpenAPI Specification v3.1.0
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986].
-Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986].
+Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986] Section 4.2.
+Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986] Section 5.2.
If a URI contains a fragment identifier, then the fragment should be resolved per the fragment resolution mechanism of the referenced document. If the representation of the referenced document is JSON or YAML, then the fragment identifier SHOULD be interpreted as a JSON-Pointer as per [RFC6901].
-Relative references in Schema Objects, including any that appear as $id values, use the nearest parent $id as a Base URI, as described by JSON Schema Specification Draft 2020-12. If no parent schema contains an $id, then the Base URI MUST be determined according to [RFC3986].
+Relative references in Schema Objects, including any that appear as $id values, use the nearest parent $id as a Base URI, as described by JSON Schema Specification Draft 2020-12. If no parent schema contains an $id, then the Base URI MUST be determined according to [RFC3986] Section 5.1.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Unless specified otherwise, relative references are resolved using the URLs defined in the Server Object as a Base URL. Note that these themselves MAY be relative to the referring document.
In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.
@@ -1262,7 +1262,7 @@ OpenAPI Specification v3.1.0
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
+The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
responses
@@ -1443,7 +1443,7 @@ OpenAPI Specification v3.1.0
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
-header - Custom headers that are expected as part of the request. Note that [RFC7230] states header names are case insensitive.
+header - Custom headers that are expected as part of the request. Note that [RFC7230] Page 22 states header names are case insensitive.
cookie - Used to pass a specific cookie value to the API.
@@ -1512,7 +1512,7 @@ OpenAPI Specification v3.1.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
schema
@@ -1566,25 +1566,25 @@ OpenAPI Specification v3.1.0
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
label
primitive, array, objectpathLabel style parameters defined by [RFC6570]
+Label style parameters defined by [RFC6570] Section 3.2.5
form
primitive, array, objectquery, cookieForm style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
+Form style parameters defined by [RFC6570] Section 3.2.8. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
simple
arraypath, headerSimple style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
+Simple style parameters defined by [RFC6570] Section 3.2.2. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
spaceDelimited
@@ -2090,7 +2090,7 @@ OpenAPI Specification v3.1.0
In contrast with the 2.0 specification, file input/output content in OpenAPI is described with the same semantics as any other schema type.
-In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in [RFC4648], including “base64” and “base64url”, as well as “quoted-printable” from [RFC2045]. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.
+In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in [RFC4648], including “base64” and “base64url”, as well as “quoted-printable” from [RFC2045] Section 6.7. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.
JSON Schema also offers a contentMediaType keyword. However, when the media type is already specified by the Media Type Object’s key, or by the contentType field of an Encoding Object, the contentMediaType keyword SHALL be ignored if present.
Examples:
Content transferred in binary (octet-stream) MAY omit schema:
@@ -2241,7 +2241,7 @@ OpenAPI Specification v3.1.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
@@ -2387,7 +2387,7 @@ OpenAPI Specification v3.1.0
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
content
@@ -2878,7 +2878,7 @@ OpenAPI Specification v3.1.0
= "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
"^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
-
Here, json-pointer is taken from [RFC6901], char from [RFC7159] and token from [RFC7230].
+Here, json-pointer is taken from [RFC6901], char from [RFC7159] Section 7 and token from [RFC7230] Section 3.2.6.
The name identifier is case-sensitive, whereas token is not.
The table below provides examples of runtime expressions and examples of their use in a value:
@@ -3928,7 +3928,7 @@ OpenAPI Specification v3.1.0
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
bearerFormat
requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.OpenAPI Specification v3.1.0
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
/items?id=###, the query parameter is id.OpenAPI Specification v3.1.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
boolean:/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.:/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.OpenAPI Specification v3.1.0
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
primitive, array, objectpathprimitive, array, objectquery, cookiecollectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.arraypath, headercollectionFormat with a csv value from OpenAPI 2.0.collectionFormat with a csv value from OpenAPI 2.0.OpenAPI Specification v3.1.0
In contrast with the 2.0 specification, file input/output content in OpenAPI is described with the same semantics as any other schema type.
In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in [RFC4648], including “base64” and “base64url”, as well as “quoted-printable” from [RFC2045]. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.
In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in [RFC4648], including “base64” and “base64url”, as well as “quoted-printable” from [RFC2045] Section 6.7. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.
JSON Schema also offers a contentMediaType keyword. However, when the media type is already specified by the Media Type Object’s key, or by the contentType field of an Encoding Object, the contentMediaType keyword SHALL be ignored if present.
Examples:
Content transferred in binary (octet-stream) MAY omit schema:
OpenAPI Specification v3.1.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
boolean:/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.:/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.string, Header Object | Reference Object]"Content-Type", it SHALL be ignored."Content-Type", it SHALL be ignored.OpenAPI Specification v3.1.0
= "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA -
Here, json-pointer is taken from [RFC6901], char from [RFC7159] and token from [RFC7230].
Here, json-pointer is taken from [RFC6901], char from [RFC7159] Section 7 and token from [RFC7230] Section 3.2.6.
The name identifier is case-sensitive, whereas token is not.
The table below provides examples of runtime expressions and examples of their use in a value:
OpenAPI Specification v3.1.0
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
stringhttp
OpenAPI Specification v2.0
Version 2.0
@@ -218,7 +218,7 @@OpenAPI Specification v2.0
-The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
+The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
The Swagger specification is licensed under The Apache License, Version 2.0.
Swagger™ is a project used to describe and document RESTful APIs.
@@ -274,7 +274,7 @@ OpenAPI Specification v2.0
-The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by [RFC7231] and in the IANA Status Code Registry.
+The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by [RFC7231] Section 6 and in the IANA Status Code Registry.
The files describing the RESTful API in accordance with the Swagger specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to
@@ -357,13 +357,13 @@
OpenAPI Specification v2.0
date
stringdateAs defined by full-date - [RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
+The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in [RFC2119].
The Swagger specification is licensed under The Apache License, Version 2.0.
Swagger™ is a project used to describe and document RESTful APIs.
@@ -274,7 +274,7 @@OpenAPI Specification v2.0
The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by [RFC7231] and in the IANA Status Code Registry.
+The HTTP Status Codes are used to indicate the status of the executed operation. The available status codes are described by [RFC7231] Section 6 and in the IANA Status Code Registry.
The files describing the RESTful API in accordance with the Swagger specification are represented as JSON objects and conform to the JSON standards. YAML, being a superset of JSON, can be used as well to @@ -357,13 +357,13 @@
OpenAPI Specification v2.0
date
stringdateAs defined by full-date - [RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
stringdatefull-date - [RFC3339]full-date - [RFC3339] Section 5.6stringdate-timedate-time - [RFC3339]date-time - [RFC3339] Section 5.6OpenAPI Specification v2.0
A simple object to allow referencing other definitions in the specification. It can be used to reference parameters and responses that are defined at the top level for reuse.
-The Reference Object is a JSON Reference that uses a JSON Pointer as its value. For this specification, only canonical dereferencing is supported.
+The Reference Object is a JSON Reference that uses a JSON Pointer [RFC6901] as its value. For this specification, only canonical dereferencing is supported.
@@ -3309,8 +3309,14 @@ OpenAPI Specification v2.0
- - [RFC6838]
-
+
- [RFC2119]
-
+ Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+
- [RFC3339]
-
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
+
- [RFC6838]
-
Media Type Specifications and Registration Procedures. N. Freed; J. Klensin; T. Hansen. IETF. January 2013. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc6838
+
- [RFC6901]
-
+ JavaScript Object Notation (JSON) Pointer. P. Bryan, Ed.; K. Zyp; M. Nottingham, Ed.. IETF. April 2013. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6901
- [RFC7231]
-
Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content. R. Fielding, Ed.; J. Reschke, Ed.. IETF. June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7231.html
diff --git a/oas/v3.0.0.html b/oas/v3.0.0.html
index 907c6d4c3f..f4edf9c5ce 100644
--- a/oas/v3.0.0.html
+++ b/oas/v3.0.0.html
@@ -254,7 +254,7 @@ OpenAPI Specification v3.0.0
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -354,13 +354,13 @@ OpenAPI Specification v3.0.0
[RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
dateTime
stringdate-timeAs defined by date-time - [RFC3339]
+As defined by date-time - [RFC3339] Section 5.6
password
@@ -374,7 +374,7 @@ OpenAPI Specification v3.0.0
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
@@ -1240,7 +1240,7 @@ OpenAPI Specification v3.0.0
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
responses
@@ -1420,7 +1420,7 @@ OpenAPI Specification v3.0.0
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
-header - Custom headers that are expected as part of the request. Note that [RFC7230] states header names are case insensitive.
+header - Custom headers that are expected as part of the request. Note that [RFC7230] Page 22 states header names are case insensitive.
cookie - Used to pass a specific cookie value to the API.
@@ -1489,7 +1489,7 @@ OpenAPI Specification v3.0.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
schema
@@ -1543,25 +1543,25 @@ OpenAPI Specification v3.0.0
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
label
primitive, array, objectpathLabel style parameters defined by [RFC6570]
+Label style parameters defined by [RFC6570] Section 3.2.5
form
primitive, array, objectquery, cookieForm style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
+Form style parameters defined by [RFC6570] Section 3.2.8. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
simple
arraypath, headerSimple style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
+Simple style parameters defined by [RFC6570] Section 3.2.2. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
spaceDelimited
@@ -2214,7 +2214,7 @@ OpenAPI Specification v3.0.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
@@ -2362,7 +2362,7 @@ OpenAPI Specification v3.0.0
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
A simple object to allow referencing other definitions in the specification. It can be used to reference parameters and responses that are defined at the top level for reuse.
-The Reference Object is a JSON Reference that uses a JSON Pointer as its value. For this specification, only canonical dereferencing is supported.
+The Reference Object is a JSON Reference that uses a JSON Pointer [RFC6901] as its value. For this specification, only canonical dereferencing is supported.
As defined by full-date - [RFC3339] Section 5.6 |
||||
| dateTime | string |
date-time |
-As defined by date-time - [RFC3339] |
+As defined by date-time - [RFC3339] Section 5.6 |
| password | @@ -374,7 +374,7 @@Request Body Object | Reference Object | -The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers. |
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers. |
|
| responses | @@ -1420,7 +1420,7 @@boolean |
-Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false. |
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false. |
|
| schema | @@ -1543,25 +1543,25 @@Path-style parameters defined by [RFC6570] Section 3.2.7 | |||
| label | primitive, array, object |
path |
-Label style parameters defined by [RFC6570] | +Label style parameters defined by [RFC6570] Section 3.2.5 |
| form | primitive, array, object |
query, cookie |
-Form style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0. |
+Form style parameters defined by [RFC6570] Section 3.2.8. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0. |
| simple | array |
path, header |
-Simple style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv value from OpenAPI 2.0. |
+Simple style parameters defined by [RFC6570] Section 3.2.2. This option replaces collectionFormat with a csv value from OpenAPI 2.0. |
| spaceDelimited | @@ -2214,7 +2214,7 @@boolean |
-Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded. |
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded. |
OpenAPI Specification v3.0.0
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
string, Header Object | Reference Object]"Content-Type", it SHALL be ignored."Content-Type", it SHALL be ignored.OpenAPI Specification v3.0.0
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235].
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1.
stringhttpOpenAPI Specification v3.0.0
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+ [RFC3339]
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC6570]
diff --git a/oas/v3.0.1.html b/oas/v3.0.1.html
index fbde7dccb9..94db0d0cdb 100644
--- a/oas/v3.0.1.html
+++ b/oas/v3.0.1.html
@@ -259,7 +259,7 @@ OpenAPI Specification v3.0.1
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -359,13 +359,13 @@ OpenAPI Specification v3.0.1
[RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
OpenAPI Specification v3.0.1
The HTTP Status Codes are used to indicate the status of the executed operation. -The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -359,13 +359,13 @@OpenAPI Specification v3.0.1
[RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
full-date - [RFC3339] Section 5.6stringdate-timedate-time - [RFC3339]date-time - [RFC3339] Section 5.6OpenAPI Specification v3.0.1
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
@@ -1245,7 +1245,7 @@ OpenAPI Specification v3.0.1
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986]. +
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
OpenAPI Specification v3.0.1
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.OpenAPI Specification v3.0.1
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
/items?id=###, the query parameter is id.OpenAPI Specification v3.0.1
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
boolean:/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.:/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.OpenAPI Specification v3.0.1
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
primitive, array, objectpathprimitive, array, objectquery, cookiecollectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.arraypath, headercollectionFormat with a csv value from OpenAPI 2.0.collectionFormat with a csv value from OpenAPI 2.0.OpenAPI Specification v3.0.1
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
boolean:/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.:/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.OpenAPI Specification v3.0.1
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
content
@@ -3921,7 +3921,7 @@ OpenAPI Specification v3.0.1
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235].
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1.
bearerFormat
@@ -4264,6 +4264,8 @@ OpenAPI Specification v3.0.1
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+ [RFC3339]
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC6570]
diff --git a/oas/v3.0.2.html b/oas/v3.0.2.html
index 96aa375913..02c2a94b40 100644
--- a/oas/v3.0.2.html
+++ b/oas/v3.0.2.html
@@ -269,7 +269,7 @@ OpenAPI Specification v3.0.2
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -360,12 +360,12 @@ OpenAPI Specification v3.0.2
[RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
stringdate-timeAs defined by date-time - [RFC3339]
+As defined by date-time - [RFC3339] Section 5.6
stringOpenAPI Specification v3.0.2
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
@@ -1264,7 +1264,7 @@ OpenAPI Specification v3.0.2
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
responses
@@ -1444,7 +1444,7 @@ OpenAPI Specification v3.0.2
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
-header - Custom headers that are expected as part of the request. Note that [RFC7230] states header names are case insensitive.
+header - Custom headers that are expected as part of the request. Note that [RFC7230] Page 22 states header names are case insensitive.
cookie - Used to pass a specific cookie value to the API.
@@ -1513,7 +1513,7 @@ OpenAPI Specification v3.0.2
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
schema
@@ -1567,25 +1567,25 @@ OpenAPI Specification v3.0.2
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
label
primitive, array, objectpathLabel style parameters defined by [RFC6570]
+Label style parameters defined by [RFC6570] Section 3.2.5
form
primitive, array, objectquery, cookieForm style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
+Form style parameters defined by [RFC6570] Section 3.2.8. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
simple
arraypath, headerSimple style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
+Simple style parameters defined by [RFC6570] Section 3.2.2. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
spaceDelimited
@@ -2238,7 +2238,7 @@ OpenAPI Specification v3.0.2
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
@@ -2386,7 +2386,7 @@ OpenAPI Specification v3.0.2
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
content
@@ -3942,7 +3942,7 @@ OpenAPI Specification v3.0.2
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235].
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1.
bearerFormat
@@ -4290,6 +4290,8 @@ OpenAPI Specification v3.0.2
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+ [RFC3339]
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC6570]
diff --git a/oas/v3.0.3.html b/oas/v3.0.3.html
index 4c7f42246d..04acafbb29 100644
--- a/oas/v3.0.3.html
+++ b/oas/v3.0.3.html
@@ -270,7 +270,7 @@ OpenAPI Specification v3.0.3
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -362,12 +362,12 @@ OpenAPI Specification v3.0.3
[RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
stringdate-timeAs defined by date-time - [RFC3339]
+As defined by date-time - [RFC3339] Section 5.6
stringOpenAPI Specification v3.0.3
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
@@ -1266,7 +1266,7 @@ OpenAPI Specification v3.0.3
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
responses
@@ -1446,7 +1446,7 @@ OpenAPI Specification v3.0.3
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
-header - Custom headers that are expected as part of the request. Note that [RFC7230] states header names are case insensitive.
+header - Custom headers that are expected as part of the request. Note that [RFC7230] Page 22 states header names are case insensitive.
cookie - Used to pass a specific cookie value to the API.
@@ -1515,7 +1515,7 @@ OpenAPI Specification v3.0.3
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
schema
@@ -1569,25 +1569,25 @@ OpenAPI Specification v3.0.3
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
label
primitive, array, objectpathLabel style parameters defined by [RFC6570]
+Label style parameters defined by [RFC6570] Section 3.2.5
form
primitive, array, objectquery, cookieForm style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
+Form style parameters defined by [RFC6570] Section 3.2.8. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
simple
arraypath, headerSimple style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
+Simple style parameters defined by [RFC6570] Section 3.2.2. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
spaceDelimited
@@ -2239,7 +2239,7 @@ OpenAPI Specification v3.0.3
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
@@ -2387,7 +2387,7 @@ OpenAPI Specification v3.0.3
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
content
@@ -2877,7 +2877,7 @@ OpenAPI Specification v3.0.3
= "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
"^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
-
Here, json-pointer is taken from [RFC6901], char from [RFC7159] and token from [RFC7230].
+Here, json-pointer is taken from [RFC6901], char from [RFC7159] Section 7 and token from [RFC7230] Section 3.2.6.
The name identifier is case-sensitive, whereas token is not.
The table below provides examples of runtime expressions and examples of their use in a value:
@@ -3956,7 +3956,7 @@ OpenAPI Specification v3.0.3
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
bearerFormat
@@ -4331,6 +4331,8 @@ OpenAPI Specification v3.0.3
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+ [RFC3339]
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC6570]
diff --git a/oas/v3.1.0.html b/oas/v3.1.0.html
index 4f53076434..f4d70949d2 100644
--- a/oas/v3.1.0.html
+++ b/oas/v3.1.0.html
@@ -252,7 +252,7 @@ OpenAPI Specification v3.1.0
Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.
Each template expression in the path MUST correspond to a path parameter that is included in the Path Item itself and/or in each of the Path Item’s Operations. An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required.
-The value for these path parameters MUST NOT contain any unescaped “generic syntax” characters described by [RFC3986]: forward slashes (/), question marks (?), or hashes (#).
+The value for these path parameters MUST NOT contain any unescaped “generic syntax” characters described by [RFC3986] Section 3: forward slashes (/), question marks (?), or hashes (#).
Media type definitions are spread across several resources.
The media type definitions SHOULD be in compliance with [RFC6838].
@@ -271,7 +271,7 @@ OpenAPI Specification v3.1.0
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 3.1) SHALL designate the OAS feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.1.0 and 3.1.1 for example.
@@ -345,12 +345,12 @@ OpenAPI Specification v3.1.0
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986].
-Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986].
+Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986] Section 4.2.
+Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986] Section 5.2.
If a URI contains a fragment identifier, then the fragment should be resolved per the fragment resolution mechanism of the referenced document. If the representation of the referenced document is JSON or YAML, then the fragment identifier SHOULD be interpreted as a JSON-Pointer as per [RFC6901].
-Relative references in Schema Objects, including any that appear as $id values, use the nearest parent $id as a Base URI, as described by JSON Schema Specification Draft 2020-12. If no parent schema contains an $id, then the Base URI MUST be determined according to [RFC3986].
+Relative references in Schema Objects, including any that appear as $id values, use the nearest parent $id as a Base URI, as described by JSON Schema Specification Draft 2020-12. If no parent schema contains an $id, then the Base URI MUST be determined according to [RFC3986] Section 5.1.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Unless specified otherwise, relative references are resolved using the URLs defined in the Server Object as a Base URL. Note that these themselves MAY be relative to the referring document.
In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.
@@ -1262,7 +1262,7 @@ OpenAPI Specification v3.1.0
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
+The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
responses
@@ -1443,7 +1443,7 @@ OpenAPI Specification v3.1.0
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
-header - Custom headers that are expected as part of the request. Note that [RFC7230] states header names are case insensitive.
+header - Custom headers that are expected as part of the request. Note that [RFC7230] Page 22 states header names are case insensitive.
cookie - Used to pass a specific cookie value to the API.
@@ -1512,7 +1512,7 @@ OpenAPI Specification v3.1.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
schema
@@ -1566,25 +1566,25 @@ OpenAPI Specification v3.1.0
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
label
primitive, array, objectpathLabel style parameters defined by [RFC6570]
+Label style parameters defined by [RFC6570] Section 3.2.5
form
primitive, array, objectquery, cookieForm style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
+Form style parameters defined by [RFC6570] Section 3.2.8. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
simple
arraypath, headerSimple style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
+Simple style parameters defined by [RFC6570] Section 3.2.2. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
spaceDelimited
@@ -2090,7 +2090,7 @@ OpenAPI Specification v3.1.0
In contrast with the 2.0 specification, file input/output content in OpenAPI is described with the same semantics as any other schema type.
-In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in [RFC4648], including “base64” and “base64url”, as well as “quoted-printable” from [RFC2045]. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.
+In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in [RFC4648], including “base64” and “base64url”, as well as “quoted-printable” from [RFC2045] Section 6.7. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.
JSON Schema also offers a contentMediaType keyword. However, when the media type is already specified by the Media Type Object’s key, or by the contentType field of an Encoding Object, the contentMediaType keyword SHALL be ignored if present.
Examples:
Content transferred in binary (octet-stream) MAY omit schema:
@@ -2241,7 +2241,7 @@ OpenAPI Specification v3.1.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
@@ -2387,7 +2387,7 @@ OpenAPI Specification v3.1.0
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
content
@@ -2878,7 +2878,7 @@ OpenAPI Specification v3.1.0
= "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
"^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
-
Here, json-pointer is taken from [RFC6901], char from [RFC7159] and token from [RFC7230].
+Here, json-pointer is taken from [RFC6901], char from [RFC7159] Section 7 and token from [RFC7230] Section 3.2.6.
The name identifier is case-sensitive, whereas token is not.
The table below provides examples of runtime expressions and examples of their use in a value:
@@ -3928,7 +3928,7 @@ OpenAPI Specification v3.1.0
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
bearerFormat
string, Header Object | Reference Object]"Content-Type", it SHALL be ignored."Content-Type", it SHALL be ignored.OpenAPI Specification v3.0.1
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235].
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1.
stringhttpOpenAPI Specification v3.0.1
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+ [RFC3339]
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC6570]
diff --git a/oas/v3.0.2.html b/oas/v3.0.2.html
index 96aa375913..02c2a94b40 100644
--- a/oas/v3.0.2.html
+++ b/oas/v3.0.2.html
@@ -269,7 +269,7 @@ OpenAPI Specification v3.0.2
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -360,12 +360,12 @@ OpenAPI Specification v3.0.2
[RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
OpenAPI Specification v3.0.2
The HTTP Status Codes are used to indicate the status of the executed operation. -The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -360,12 +360,12 @@OpenAPI Specification v3.0.2
[RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
full-date - [RFC3339] Section 5.6stringdate-timedate-time - [RFC3339]date-time - [RFC3339] Section 5.6stringOpenAPI Specification v3.0.2
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
@@ -1264,7 +1264,7 @@ OpenAPI Specification v3.0.2
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986]. +
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
OpenAPI Specification v3.0.2
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.OpenAPI Specification v3.0.2
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
/items?id=###, the query parameter is id.OpenAPI Specification v3.0.2
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
boolean:/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.:/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.OpenAPI Specification v3.0.2
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
primitive, array, objectpathprimitive, array, objectquery, cookiecollectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.arraypath, headercollectionFormat with a csv value from OpenAPI 2.0.collectionFormat with a csv value from OpenAPI 2.0.OpenAPI Specification v3.0.2
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
boolean:/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.:/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.string, Header Object | Reference Object]"Content-Type", it SHALL be ignored."Content-Type", it SHALL be ignored.OpenAPI Specification v3.0.2
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235].
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1.
stringhttpOpenAPI Specification v3.0.2
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+ [RFC3339]
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC6570]
diff --git a/oas/v3.0.3.html b/oas/v3.0.3.html
index 4c7f42246d..04acafbb29 100644
--- a/oas/v3.0.3.html
+++ b/oas/v3.0.3.html
@@ -270,7 +270,7 @@ OpenAPI Specification v3.0.3
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -362,12 +362,12 @@ OpenAPI Specification v3.0.3
[RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
OpenAPI Specification v3.0.3
The HTTP Status Codes are used to indicate the status of the executed operation. -The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.The OpenAPI Specification is versioned using Semantic Versioning 2.0.0 (semver) and follows the semver specification.
@@ -362,12 +362,12 @@OpenAPI Specification v3.0.3
[RFC3339]
+As defined by full-date - [RFC3339] Section 5.6
full-date - [RFC3339] Section 5.6stringdate-timedate-time - [RFC3339]date-time - [RFC3339] Section 5.6stringOpenAPI Specification v3.0.3
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
@@ -1266,7 +1266,7 @@ OpenAPI Specification v3.0.3
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986]. +
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Relative references are resolved using the URLs defined in the Server Object as a Base URI.
Relative references used in $ref are processed as per JSON Reference, using the URL of the current document as the base URI. See also the Reference Object.
OpenAPI Specification v3.0.3
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
+The request body applicable for this operation. The requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.
requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.requestBody is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague, requestBody SHALL be ignored by consumers.OpenAPI Specification v3.0.3
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
/items?id=###, the query parameter is id.OpenAPI Specification v3.0.3
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
boolean:/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.:/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.OpenAPI Specification v3.0.3
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
primitive, array, objectpathprimitive, array, objectquery, cookiecollectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.arraypath, headercollectionFormat with a csv value from OpenAPI 2.0.collectionFormat with a csv value from OpenAPI 2.0.OpenAPI Specification v3.0.3
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.
boolean:/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.:/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded.OpenAPI Specification v3.0.3
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
content
@@ -2877,7 +2877,7 @@ OpenAPI Specification v3.0.3
= "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
"^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
-
Here, json-pointer is taken from [RFC6901], char from [RFC7159] and token from [RFC7230].
+Here, json-pointer is taken from [RFC6901], char from [RFC7159] Section 7 and token from [RFC7230] Section 3.2.6.
The name identifier is case-sensitive, whereas token is not.
The table below provides examples of runtime expressions and examples of their use in a value:
@@ -3956,7 +3956,7 @@ OpenAPI Specification v3.0.3
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
bearerFormat
@@ -4331,6 +4331,8 @@ OpenAPI Specification v3.0.3
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+ [RFC3339]
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC6570]
diff --git a/oas/v3.1.0.html b/oas/v3.1.0.html
index 4f53076434..f4d70949d2 100644
--- a/oas/v3.1.0.html
+++ b/oas/v3.1.0.html
@@ -252,7 +252,7 @@ OpenAPI Specification v3.1.0
Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.
Each template expression in the path MUST correspond to a path parameter that is included in the Path Item itself and/or in each of the Path Item’s Operations. An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required.
-The value for these path parameters MUST NOT contain any unescaped “generic syntax” characters described by [RFC3986]: forward slashes (/), question marks (?), or hashes (#).
+The value for these path parameters MUST NOT contain any unescaped “generic syntax” characters described by [RFC3986] Section 3: forward slashes (/), question marks (?), or hashes (#).
Media type definitions are spread across several resources.
The media type definitions SHOULD be in compliance with [RFC6838].
@@ -271,7 +271,7 @@ OpenAPI Specification v3.1.0
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 3.1) SHALL designate the OAS feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.1.0 and 3.1.1 for example.
@@ -345,12 +345,12 @@ OpenAPI Specification v3.1.0
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986].
-Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986].
+Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986] Section 4.2.
+Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986] Section 5.2.
If a URI contains a fragment identifier, then the fragment should be resolved per the fragment resolution mechanism of the referenced document. If the representation of the referenced document is JSON or YAML, then the fragment identifier SHOULD be interpreted as a JSON-Pointer as per [RFC6901].
-Relative references in Schema Objects, including any that appear as $id values, use the nearest parent $id as a Base URI, as described by JSON Schema Specification Draft 2020-12. If no parent schema contains an $id, then the Base URI MUST be determined according to [RFC3986].
+Relative references in Schema Objects, including any that appear as $id values, use the nearest parent $id as a Base URI, as described by JSON Schema Specification Draft 2020-12. If no parent schema contains an $id, then the Base URI MUST be determined according to [RFC3986] Section 5.1.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Unless specified otherwise, relative references are resolved using the URLs defined in the Server Object as a Base URL. Note that these themselves MAY be relative to the referring document.
In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.
@@ -1262,7 +1262,7 @@ OpenAPI Specification v3.1.0
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
+The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
responses
@@ -1443,7 +1443,7 @@ OpenAPI Specification v3.1.0
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
query - Parameters that are appended to the URL. For example, in /items?id=###, the query parameter is id.
-header - Custom headers that are expected as part of the request. Note that [RFC7230] states header names are case insensitive.
+header - Custom headers that are expected as part of the request. Note that [RFC7230] Page 22 states header names are case insensitive.
cookie - Used to pass a specific cookie value to the API.
@@ -1512,7 +1512,7 @@ OpenAPI Specification v3.1.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
schema
@@ -1566,25 +1566,25 @@ OpenAPI Specification v3.1.0
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
label
primitive, array, objectpathLabel style parameters defined by [RFC6570]
+Label style parameters defined by [RFC6570] Section 3.2.5
form
primitive, array, objectquery, cookieForm style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
+Form style parameters defined by [RFC6570] Section 3.2.8. This option replaces collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.
simple
arraypath, headerSimple style parameters defined by [RFC6570]. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
+Simple style parameters defined by [RFC6570] Section 3.2.2. This option replaces collectionFormat with a csv value from OpenAPI 2.0.
spaceDelimited
@@ -2090,7 +2090,7 @@ OpenAPI Specification v3.1.0
In contrast with the 2.0 specification, file input/output content in OpenAPI is described with the same semantics as any other schema type.
-In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in [RFC4648], including “base64” and “base64url”, as well as “quoted-printable” from [RFC2045]. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.
+In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in [RFC4648], including “base64” and “base64url”, as well as “quoted-printable” from [RFC2045] Section 6.7. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.
JSON Schema also offers a contentMediaType keyword. However, when the media type is already specified by the Media Type Object’s key, or by the contentType field of an Encoding Object, the contentMediaType keyword SHALL be ignored if present.
Examples:
Content transferred in binary (octet-stream) MAY omit schema:
@@ -2241,7 +2241,7 @@ OpenAPI Specification v3.1.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
@@ -2387,7 +2387,7 @@ OpenAPI Specification v3.1.0
headers
Map[string, Header Object | Reference Object]
-Maps a header name to its definition. [RFC7230] states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
+Maps a header name to its definition. [RFC7230] Page 22 states header names are case insensitive. If a response header is defined with the name "Content-Type", it SHALL be ignored.
content
@@ -2878,7 +2878,7 @@ OpenAPI Specification v3.1.0
= "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
"^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
-
Here, json-pointer is taken from [RFC6901], char from [RFC7159] and token from [RFC7230].
+Here, json-pointer is taken from [RFC6901], char from [RFC7159] Section 7 and token from [RFC7230] Section 3.2.6.
The name identifier is case-sensitive, whereas token is not.
The table below provides examples of runtime expressions and examples of their use in a value:
@@ -3928,7 +3928,7 @@ OpenAPI Specification v3.1.0
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
bearerFormat
string, Header Object | Reference Object]"Content-Type", it SHALL be ignored."Content-Type", it SHALL be ignored.OpenAPI Specification v3.0.3
= "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA -
Here, json-pointer is taken from [RFC6901], char from [RFC7159] and token from [RFC7230].
Here, json-pointer is taken from [RFC6901], char from [RFC7159] Section 7 and token from [RFC7230] Section 3.2.6.
The name identifier is case-sensitive, whereas token is not.
The table below provides examples of runtime expressions and examples of their use in a value:
OpenAPI Specification v3.0.3
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
stringhttpOpenAPI Specification v3.0.3
Hypertext Markup Language - 2.0. T. Berners-Lee; D. Connolly. IETF. November 1995. Historic. URL: https://www.rfc-editor.org/rfc/rfc1866
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
+ [RFC3339]
+ Date and Time on the Internet: Timestamps. G. Klyne; C. Newman. IETF. July 2002. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc3339
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[RFC6570]
diff --git a/oas/v3.1.0.html b/oas/v3.1.0.html
index 4f53076434..f4d70949d2 100644
--- a/oas/v3.1.0.html
+++ b/oas/v3.1.0.html
@@ -252,7 +252,7 @@ OpenAPI Specification v3.1.0
Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.
Each template expression in the path MUST correspond to a path parameter that is included in the Path Item itself and/or in each of the Path Item’s Operations. An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required.
-The value for these path parameters MUST NOT contain any unescaped “generic syntax” characters described by [RFC3986]: forward slashes (/), question marks (?), or hashes (#).
+The value for these path parameters MUST NOT contain any unescaped “generic syntax” characters described by [RFC3986] Section 3: forward slashes (/), question marks (?), or hashes (#).
Media type definitions are spread across several resources.
The media type definitions SHOULD be in compliance with [RFC6838].
@@ -271,7 +271,7 @@ OpenAPI Specification v3.1.0
The HTTP Status Codes are used to indicate the status of the executed operation.
-The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.
The OpenAPI Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 3.1) SHALL designate the OAS feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.1.0 and 3.1.1 for example.
@@ -345,12 +345,12 @@ OpenAPI Specification v3.1.0
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
-Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986].
-Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986].
+Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986] Section 4.2.
+Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986] Section 5.2.
If a URI contains a fragment identifier, then the fragment should be resolved per the fragment resolution mechanism of the referenced document. If the representation of the referenced document is JSON or YAML, then the fragment identifier SHOULD be interpreted as a JSON-Pointer as per [RFC6901].
-Relative references in Schema Objects, including any that appear as $id values, use the nearest parent $id as a Base URI, as described by JSON Schema Specification Draft 2020-12. If no parent schema contains an $id, then the Base URI MUST be determined according to [RFC3986].
+Relative references in Schema Objects, including any that appear as $id values, use the nearest parent $id as a Base URI, as described by JSON Schema Specification Draft 2020-12. If no parent schema contains an $id, then the Base URI MUST be determined according to [RFC3986] Section 5.1.
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986].
+
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Unless specified otherwise, relative references are resolved using the URLs defined in the Server Object as a Base URL. Note that these themselves MAY be relative to the referring document.
In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.
@@ -1262,7 +1262,7 @@ OpenAPI Specification v3.1.0
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
+The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
OpenAPI Specification v3.1.0
Path templating refers to the usage of template expressions, delimited by curly braces ({}), to mark a section of a URL path as replaceable using path parameters.
Each template expression in the path MUST correspond to a path parameter that is included in the Path Item itself and/or in each of the Path Item’s Operations. An exception is if the path item is empty, for example due to ACL constraints, matching path parameters are not required.
-The value for these path parameters MUST NOT contain any unescaped “generic syntax” characters described by [RFC3986]: forward slashes (/), question marks (?), or hashes (#).
The value for these path parameters MUST NOT contain any unescaped “generic syntax” characters described by [RFC3986] Section 3: forward slashes (/), question marks (?), or hashes (#).
Media type definitions are spread across several resources. The media type definitions SHOULD be in compliance with [RFC6838].
@@ -271,7 +271,7 @@OpenAPI Specification v3.1.0
The HTTP Status Codes are used to indicate the status of the executed operation. -The available status codes are defined by [RFC7231] and registered status codes are listed in the IANA Status Code Registry.
+The available status codes are defined by [RFC7231] Section 6 and registered status codes are listed in the IANA Status Code Registry.The OpenAPI Specification is versioned using a major.minor.patch versioning scheme. The major.minor portion of the version string (for example 3.1) SHALL designate the OAS feature set. .patch versions address errors in, or provide clarifications to, this document, not the feature set. Tooling which supports OAS 3.1 SHOULD be compatible with all OAS 3.1.* versions. The patch version SHOULD NOT be considered by tooling, making no distinction between 3.1.0 and 3.1.1 for example.
OpenAPI Specification v3.1.0
MUST support, at a minimum, markdown syntax as described by CommonMark 0.27. Tooling MAY choose to ignore some CommonMark features to address security concerns.
Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986].
-Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986].
Unless specified otherwise, all properties that are URIs MAY be relative references as defined by [RFC3986] Section 4.2.
+Relative references, including those in Reference Objects, PathItem Object $ref fields, Link Object operationRef fields and Example Object externalValue fields, are resolved using the referring document as the Base URI according to [RFC3986] Section 5.2.
If a URI contains a fragment identifier, then the fragment should be resolved per the fragment resolution mechanism of the referenced document. If the representation of the referenced document is JSON or YAML, then the fragment identifier SHOULD be interpreted as a JSON-Pointer as per [RFC6901].
-Relative references in Schema Objects, including any that appear as $id values, use the nearest parent $id as a Base URI, as described by JSON Schema Specification Draft 2020-12. If no parent schema contains an $id, then the Base URI MUST be determined according to [RFC3986].
Relative references in Schema Objects, including any that appear as $id values, use the nearest parent $id as a Base URI, as described by JSON Schema Specification Draft 2020-12. If no parent schema contains an $id, then the Base URI MUST be determined according to [RFC3986] Section 5.1.
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986]. +
Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986] Section 4.2.
Unless specified otherwise, relative references are resolved using the URLs defined in the Server Object as a Base URL. Note that these themselves MAY be relative to the referring document.
In the following description, if a field is not explicitly REQUIRED or described with a MUST or SHALL, it can be considered OPTIONAL.
@@ -1262,7 +1262,7 @@OpenAPI Specification v3.1.0
requestBody
Request Body Object | Reference Object
-The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
+The request body applicable for this operation. The requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.requestBody is fully supported in HTTP methods where the HTTP 1.1 specification [RFC7231] Section 4.3.1 has explicitly defined semantics for request bodies. In other cases where the HTTP spec is vague (such as GET, HEAD and DELETE), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.OpenAPI Specification v3.1.0
Path Templating, where the parameter value is actually part of the operation’s URL. This does not include the host or base path of the API. For example, in /items/{itemId}, the path parameter is itemId.
/items?id=###, the query parameter is id.OpenAPI Specification v3.1.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.
boolean:/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.:/?#[]@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.OpenAPI Specification v3.1.0
RFC6570]
+Path-style parameters defined by [RFC6570] Section 3.2.7
primitive, array, objectpathprimitive, array, objectquery, cookiecollectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.collectionFormat with a csv (when explode is false) or multi (when explode is true) value from OpenAPI 2.0.arraypath, headercollectionFormat with a csv value from OpenAPI 2.0.collectionFormat with a csv value from OpenAPI 2.0.OpenAPI Specification v3.1.0
In contrast with the 2.0 specification, file input/output content in OpenAPI is described with the same semantics as any other schema type.
In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in [RFC4648], including “base64” and “base64url”, as well as “quoted-printable” from [RFC2045]. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.
In contrast with the 3.0 specification, the format keyword has no effect on the content-encoding of the schema. JSON Schema offers a contentEncoding keyword, which may be used to specify the Content-Encoding for the schema. The contentEncoding keyword supports all encodings defined in [RFC4648], including “base64” and “base64url”, as well as “quoted-printable” from [RFC2045] Section 6.7. The encoding specified by the contentEncoding keyword is independent of an encoding specified by the Content-Type header in the request or response or metadata of a multipart body – when both are present, the encoding specified in the contentEncoding is applied first and then the encoding specified in the Content-Type header.
JSON Schema also offers a contentMediaType keyword. However, when the media type is already specified by the Media Type Object’s key, or by the contentType field of an Encoding Object, the contentMediaType keyword SHALL be ignored if present.
Examples:
Content transferred in binary (octet-stream) MAY omit schema:
OpenAPI Specification v3.1.0
allowReserved
booleanDetermines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
+Determines whether the parameter value SHOULD allow reserved characters, as defined by [RFC3986] Section 2.2 :/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.
boolean:/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.:/?#[]@!$&'()*+,;= to be included without percent-encoding. The default value is false. This property SHALL be ignored if the request body media type is not application/x-www-form-urlencoded or multipart/form-data. If a value is explicitly defined, then the value of contentType (implicit or explicit) SHALL be ignored.string, Header Object | Reference Object]"Content-Type", it SHALL be ignored."Content-Type", it SHALL be ignored.OpenAPI Specification v3.1.0
= "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA -
Here, json-pointer is taken from [RFC6901], char from [RFC7159] and token from [RFC7230].
Here, json-pointer is taken from [RFC6901], char from [RFC7159] Section 7 and token from [RFC7230] Section 3.2.6.
The name identifier is case-sensitive, whereas token is not.
The table below provides examples of runtime expressions and examples of their use in a value:
OpenAPI Specification v3.1.0
scheme
stringhttpREQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235]. The values used SHOULD be registered in the IANA Authentication Scheme registry.
+REQUIRED. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in [RFC7235] Section 5.1. The values used SHOULD be registered in the IANA Authentication Scheme registry.
stringhttp