From 271bcf58c9a528a75bb1824640f8af30e13b1eb8 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Mon, 16 Sep 2024 12:55:04 +0200 Subject: [PATCH] Rebuilt --- oas/latest.html | 2 +- oas/v2.0.html | 2 +- oas/v3.0.0.html | 2 +- oas/v3.0.1.html | 2 +- oas/v3.0.2.html | 2 +- oas/v3.0.3.html | 2 +- oas/v3.0.4.html | 236 +++++++++++++++++++++++++---------------------- oas/v3.1.0.html | 2 +- oas/v3.1.1.html | 240 +++++++++++++++++++++++++----------------------- 9 files changed, 259 insertions(+), 231 deletions(-) diff --git a/oas/latest.html b/oas/latest.html index b643c2f4b6..d794120fba 100644 --- a/oas/latest.html +++ b/oas/latest.html @@ -1,6 +1,6 @@ - +

What is the OpenAPI Specification?

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Status of This Document

The source-of-truth for this specification is the HTML file referenced above as This version.
+

What is the OpenAPI Specification?

The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

Status of This Document

The source-of-truth for this specification is the HTML file referenced above as This version.

1. OpenAPI Specification

1.1 Version 3.0.4

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

@@ -342,13 +342,15 @@

OpenAPI Specification v3.0.4

4.3 OpenAPI Description Structure

An OpenAPI Description (OAD) MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, Reference Object and Path Item Object $ref keywords, as well as the Link Object operationRef keyword, are used.

-

Any document consisting entirely of an OpenAPI Object is known as a complete OpenAPI document. +

Any document consisting entirely of an OpenAPI Object is known as a syntactically complete OpenAPI document. +An OpenAPI document that does not reference any other documents is known as a self-contained OpenAPI document. +A single-document description is therefore both syntactically complete and self-contained. In a multi-document description, the document containing the OpenAPI Object where parsing begins for a specific API’s description is known as that API’s entry OpenAPI document, or simply entry document.

It is RECOMMENDED that the entry OpenAPI document be named: openapi.json or openapi.yaml.

4.3.1 Structural Interoperability

When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such as Operation Objects, Response Objects, Reference Objects, etc.) based on the parsing context. Depending on how references are arranged, a given JSON or YAML object can be parsed in multiple different contexts:

    -
  • As a complete OpenAPI Description document
    • +
  • As a syntactically complete OpenAPI Description document
  • As the Object type implied by its parent Object within the document
  • As a reference target, with the Object type matching the reference source’s context
@@ -401,7 +403,7 @@

OpenAPI Specification v3.0.4

Security Requirement in a Referenced Document for an example of the possible resolutions, including which one is recommended by this section. +

See Appendix F: Resolving Security Requirements in a Referenced Document for an example of the possible resolutions, including which one is recommended by this section. The behavior for Discrimator Object non-URI mappings and for the Operation Object’s tags field operate on the same principles.

Note that no aspect of implicit connection resolution changes how URLs are resolved or restricts their possible targets.

4.4 Data Types

@@ -777,7 +779,7 @@

OpenAPI Specification v3.0.4

"variables": { "username": { "default": "demo", - "description": "this value is assigned by the service provider, in this example `gigantic-server.com`" + "description": "A user-specific subdomain. Use `demo` for a free sandbox environment." }, "port": { "enum": ["8443", "443"], @@ -798,7 +800,7 @@

OpenAPI Specification v3.0.4

username: # note! no enum here means it is an open value default: demo - description: this value is assigned by the service provider, in this example `gigantic-server.com` + description: A user-specific subdomain. Use `demo` for a free sandbox environment. port: enum: - '8443' @@ -828,7 +830,7 @@

OpenAPI Specification v3.0.4

default string -REQUIRED. The default value to use for substitution, which SHALL be sent if an alternate value is not supplied. Note this behavior is different than the Schema Object’s treatment of default values, because in those cases parameter values are optional. If the enum is defined, the value SHOULD exist in the enum’s values. +REQUIRED. The default value to use for substitution, which SHALL be sent if an alternate value is not supplied. If the enum is defined, the value SHOULD exist in the enum’s values. Note that this behavior is different from the Schema Object’s default keyword, which documents the receiver’s behavior rather than inserting the value into the data. description @@ -1605,7 +1607,7 @@

OpenAPI Specification v3.0.4

allowReserved boolean -When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570] Section 3.2.3, which allows RFC3986’s reserved character set, as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including % outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are not allowed in the query string ([, ], #), or have a special meaning in application/x-www-form-urlencoded (-, &, +); see Appendices C and E for details. This field only applies to parameters with an in value of query. The default value is false. +When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570] Section 3.2.3, which allows RFC3986’s reserved character set, as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including % outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are not allowed in the query string ([, ], #), or have a special meaning in application/x-www-form-urlencoded (-, &, +); see Appendices C and E for details. This field only applies to parameters with an in value of query. The default value is false. schema @@ -1624,7 +1626,7 @@

OpenAPI Specification v3.0.4

Appendix C: Using RFC6570 Implementations for additional guidance.

+

See also Appendix C: Using RFC6570-Based Serialization for additional guidance.

4.7.12.2.3 Fixed Fields for use with content

For more complex scenarios, the content field can define the media type and schema of the parameter, as well as give examples of its use. Using content with a text/plain media type is RECOMMENDED for in: "header" and in: "cookie" parameters where the schema strategy is not appropriate.

@@ -1712,7 +1714,7 @@

OpenAPI Specification v3.0.4

RFC6570] Section 2.3 terminology, which describes certain values including but not limited to null as “undefined” values with special handling; notably, the empty string is not undefined -
  • For form and the non-RFC6570 query string styles spaceDelimited, pipeDelimited, and deepObject, each example is shown prefixed with ? as if it were the only query parameter; see Appendix C for more information on constructing query strings from multiple parameters, and Appendix D for warnings regarding form and cookie parameters
    • +
  • For form and the non-RFC6570 query string styles spaceDelimited, pipeDelimited, and deepObject, each example is shown prefixed with ? as if it were the only query parameter; see Appendix C for more information on constructing query strings from multiple parameters, and Appendix D for warnings regarding form and cookie parameters
  • Note that the ? prefix is not appropriate for serializing application/x-www-form-urlencoded HTTP message bodies, and MUST be stripped or (if constructing the string manually) not added when used in that context; see the Encoding Object for more information
  • The examples are percent-encoded as required by RFC6570 and RFC3986; see Appendix E for a thorough discussion of percent-encoding concerns, including why unencoded | (%7C), [ (%5B), and ] (%5D) seem to work in some environments despite not being compliant.
    • @@ -2301,11 +2303,11 @@

    OpenAPI Specification v3.0.4

    allowReserved boolean -When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570] Section 3.2.3, which allows RFC3986’s reserved character set, as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including % outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are not allowed in the query string ([, ], #), or have a special meaning in application/x-www-form-urlencoded (-, &, +); see Appendices C and E for details. The default value is false. This field SHALL be ignored if the request body media type is not application/x-www-form-urlencoded. +When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570] Section 3.2.3, which allows RFC3986’s reserved character set, as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including % outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are not allowed in the query string ([, ], #), or have a special meaning in application/x-www-form-urlencoded (-, &, +); see Appendices C and E for details. The default value is false. This field SHALL be ignored if the request body media type is not application/x-www-form-urlencoded. -

    See also Appendix C: Using RFC6570 Implementations for additional guidance.

    +

    See also Appendix C: Using RFC6570-Based Serialization for additional guidance.

    The role of contentType with application/x-www-form-urlencoded request bodies was not described in detail in version 3.0.3 and earlier of this specification. To match the intent of these fields and be compatible with version 3.1 of this specification, it is RECOMMENDED that whenever any of style, explode, or allowReserved are present with an explicit value:

      @@ -3023,9 +3025,10 @@

      OpenAPI Specification v3.0.4

      MAY be extended with Specification Extensions.

      A linked operation MUST be identified using either an operationRef or operationId. -In the case of an operationId, it MUST be unique and resolved in the scope of the OpenAPI description. -Because of the potential for name clashes, the operationRef syntax is preferred -for multi-document OpenAPI descriptions.

      +The identified or reference operation MUST be unique, and in the case of an operationId, it MUST be resolved within the scope of the OpenAPI Description (OAD). +Because of the potential for name clashes, the operationRef syntax is preferred for multi-document OADs. +However, because use of an operation depends on its URL path template in the Paths Object, operations from any Path Item Object that is referenced multiple times within the OAD cannot be resolved unambiguously. +In such ambiguous cases, the resulting behavior is implementation-defined and MAY result in an error.

      Note that it is not possible to provide a constant value to parameters that matches the syntax of a runtime expression. It is possible to have ambiguous parameter names, e.g. name: "id", in: "path" and name: "path.id", in: "query"; this is NOT RECOMMENDED and the behavior is implementation-defined, however implementations SHOULD prefer the qualified interpretation (path.id as a path parameter), as the names can always be qualified to disambiguate them (e.g. using query.path.id for the query parameter).

    4.7.20.2 Examples
    @@ -3259,7 +3262,7 @@

    OpenAPI Specification v3.0.4

    Appendix C: Using RFC6570 Implementations for additional guidance.

    +

    See also Appendix C: Using RFC6570-Based Serialization for additional guidance.

    4.7.21.1.3 Fixed Fields for use with content

    For more complex scenarios, the content field can define the media type and schema of the header, as well as give examples of its use. Using content with a text/plain media type is RECOMMENDED for headers where the schema strategy is not appropriate.

    @@ -4477,6 +4480,7 @@

    OpenAPI Specification v3.0.4

    4.7.30.2 Security Requirement Object Examples
    +

    See also Appendix F: Resolving Security Requirements in a Referenced Document for an example using Security Requirement Objects in multi-document OpenAPI Descriptions.

    4.7.30.2.1 Non-OAuth2 Security Requirement
    {
   "api_key": []
@@ -4510,81 +4514,6 @@ 
    OpenAPI Specification v3.0.4 
     
    - write:pets
       - read:pets
    -
    4.7.30.2.4 Security Requirement in a Referenced Document
    -

    See Resolving Implicit Connections for more information.

    -

    First, our entry document is where parsing begins. It defines the MySecurity security scheme to be JWT-based, and it defines a Path Item as a reference to a component in another document:

    -
    GET /api/description/openapi HTTP/1.1
-Host: www.example.com
-Accept: application/openapi+json
-
    -
    "components": {
-  "securitySchemes": {
-    "MySecurity": {
-      "type": "http",
-      "scheme": "bearer",
-      "bearerFormat": "JWT"
-    }
-  }
-},
-"paths": {
-  "/foo": {
-    "$ref": "other#/components/pathItems/Foo"
-  }
-}
-
    -
    GET /api/description/openapi HTTP/1.1
-Host: www.example.com
-Accept: application/openapi+yaml
-
    -
    components:
-  securitySchemes:
-    MySecurity:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
-paths:
-  /foo:
-    $ref: 'other#/components/pathItems/Foo'
-
    -

    Next, we have our referenced document, other. The fact that we don’t use file extensions gives the client the flexibility to choose an acceptable format on a resource-by-resource basis, assuming both representations are available:

    -
    GET /api/description/other HTTP/1.1
-Host: www.example.com
-Accept: application/openapi+json
-
    -
    "components": {
-  "securitySchemes": {
-    "MySecurity": {
-      "type": "http",
-      "scheme": "basic"
-    }
-  },
-  "pathItems": {
-    "Foo": {
-      "get": {
-        "security": [
-          "MySecurity": []
-        ]
-      }
-    }
-  }
-}
-
    -
    GET /api/description/other HTTP/1.1
-Host: www.example.com
-Accept: application/openapi+yaml
-
    -
    components:
-  securitySchemes:
-    MySecurity:
-      type: http
-      scheme: basic
-  pathItems:
-    Foo:
-      get:
-        security:
-          - MySecurity: []
-
    -

    In the other document, the referenced path item has a Security Requirement for a Security Scheme, MySecurity. The same Security Scheme exists in the original entry document. As outlined in Resolving Implicit Connections, MySecurity is resolved with an implementation-defined behavior. However, documented in that section, it is RECOMMENDED that tools resolve component names from the entry document. As with all implementation-defined behavior, it is important to check tool documentation to determine which behavior is supported.

    4.8 Specification Extensions

    While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.

    The extensions properties are implemented as patterned fields that are always prefixed by x-.

    @@ -4731,8 +4660,8 @@

    OpenAPI Specification v3.0.4

    decimal in the Format Registry) are less clear. However, care must be taken with format to ensure that the specific formats are supported by all relevant tools as unrecognized formats are ignored.

    Requiring input as pre-formatted, schema-validated strings also improves round-trip interoperability as not all programming languages and environments support the same data types.

    -

    C. Appendix C: Using RFC6570 Implementations

    -

    Serialization is defined in terms of [RFC6570] URI Templates in two scenarios:

    +

    C. Appendix C: Using RFC6570-Based Serialization

    +

    Serialization is defined in terms of [RFC6570] URI Templates in three scenarios:

    @@ -4746,6 +4675,10 @@

    OpenAPI Specification v3.0.4

    Header Object +

    + + @@ -4820,10 +4753,15 @@

    OpenAPI Specification v3.0.4

    schema: type: string -

    This example is equivalent to RFC6570’s {?foo*,bar}, and NOT {?foo*}{&bar}. The latter is problematic because if foo is not defined, the result will be an invalid URI. +

    This example is equivalent to RFC6570’s {?foo*,bar}, and NOT {?foo*}{&bar}. The latter is problematic because if foo is not defined, the result will be an invalid URI. The & prefix operator has no equivalent in the Parameter Object.

    -

    Note that RFC6570 does not specify behavior for compound values beyond the single level addressed by explode. The results of using objects or arrays where no behavior is clearly specified for them is implementation-defined.

    -

    C.2 Non-RFC6570 Field Values and Combinations

    +

    Note that RFC6570 does not specify behavior for compound values beyond the single level addressed by explode. The result of using objects or arrays where no behavior is clearly specified for them is implementation-defined.

    +

    C.2 Delimiters in Parameter Values

    +

    Delimiters used by RFC6570 expansion, such as the , used to join arrays or object values with style: "simple", are all automatically percent-encoded as long as allowReserved is false. +Note that since RFC6570 does not define a way to parse variables based on a URI Template, users must take care to first split values by delimiter before percent-decoding values that might contain the delimiter character.

    +

    When allowReserved is true, both percent-encoding (prior to joining values with a delimiter) and percent-decoding (after splitting on the delimiter) must be done manually at the correct time.

    +

    See Appendix E for additional guidance on handling delimiters for style values with no RFC6570 equivalent that already need to be percent-encoded when used as delimiters.

    +

    C.3 Non-RFC6570 Field Values and Combinations

    Configurations with no direct [RFC6570] equivalent SHOULD also be handled according to RFC6570. Implementations MAY create a properly delimited URI Template with variables for individual names and values using RFC6570 regular or reserved expansion (based on allowReserved).

    This includes:

    @@ -4834,7 +4772,7 @@

    OpenAPI Specification v3.0.4

    variable name syntax. A parameter name that includes characters outside of the allowed RFC6570 variable character set MUST be percent-encoded before it can be used in a URI Template.

    -

    C.3 Examples

    +

    C.4 Examples

    Let’s say we want to use the following data in a form query string, where formulas is exploded, and words is not:

    formulas:
   a: x+y
@@ -4845,7 +4783,7 @@ 
    OpenAPI Specification v3.0.4 
     
    - is
 - fun
    -

    C.3.1 RFC6570-Equivalent Expansion

    +

    C.4.1 RFC6570-Equivalent Expansion

    This array of Parameter Objects uses regular style: "form" expansion, fully supported by [RFC6570]:

    parameters:
 - name: formulas
@@ -4868,7 +4806,7 @@ 
    OpenAPI Specification v3.0.4 
     
    ?a=x%2By&b=x%2Fy&c=x%5Ey&words=math,is,fun
    -

    C.3.2 Expansion with Non-RFC6570-Supported Options

    +

    C.4.2 Expansion with Non-RFC6570-Supported Options

    But now let’s say that (for some reason), we really want that / in the b formula to show up as-is in the query string, and we want our words to be space-separated like in a written phrase. To do that, we’ll add allowReserved: true to formulas, and change to style: "spaceDelimited" for words:

    parameters:
@@ -4883,6 +4821,7 @@ 
    OpenAPI Specification v3.0.4 
     
    - name: words
   in: query
   style: spaceDelimited
+  explode: false
   schema:
     type: array
     items:
@@ -4911,7 +4850,7 @@ 
    OpenAPI Specification v3.0.4 
     
    ?a=x%2By&b=x/y&c=x%5Ey&words=math%20is%20fun

    The / and the pre-percent-encoded %2B have been left alone, but the disallowed ^ character (inside a value) and space characters (in the template but outside of the expanded variables) were percent-encoded.

    -

    C.3.3 Undefined Values and Manual URI Template Construction

    +

    C.4.3 Undefined Values and Manual URI Template Construction

    Care must be taken when manually constructing templates to handle the values that RFC6570 considers to be undefined correctly:

    formulas: {}
 words:
@@ -4932,7 +4871,7 @@ 
    OpenAPI Specification v3.0.4 
     
    ?words=hello%20world
    -

    C.3.4 Illegal Variable Names as Parameter Names

    +

    C.4.4 Illegal Variable Names as Parameter Names

    In this example, the heart emoji is not legal in URI Template names (or URIs):

    parameters:
 - name: ❤️
@@ -4959,7 +4898,7 @@ 
    OpenAPI Specification v3.0.4 
     
    , that delimiter would itself be percent-encoded, violating the general HTTP field syntax.
    
 
    Using style: "form" with in: "cookie" is ambiguous for a single value, and incorrect for multiple values.
 This is true whether the multiple values are the result of using explode: true or not.
    
-
    This style is specified to be equivalent to RFC6570 form expansion which includes the ? character (see Appendix C for more details), which is not part of the cookie syntax.
+
    This style is specified to be equivalent to RFC6570 form expansion which includes the ? character (see Appendix C for more details), which is not part of the cookie syntax.
 However, examples of this style in past versions of this specification have not included the ? prefix, suggesting that the comparison is not exact.
 Because implementations that rely on an RFC6570 implementation and those that perform custom serialization based on the style example will produce different results, it is implementation-defined as to which of the two results is correct.
    
 
    For multiple values, style: "form" is always incorrect as name=value pairs in cookies are delimited by ; (a semicolon followed by a space character) rather than &.
    
@@ -4978,7 +4917,7 @@ 
    OpenAPI Specification v3.0.4 
     
    Appendix C for an example of handling + in form values.
    
+This means that while these three characters are reserved-but-allowed in query strings by RFC3986, they must be percent-encoded in form-urlencoded query strings except when used for their form-urlencoded purposes; see Appendix C for an example of handling + in form values.

    E.2 Percent-Encoding and form-data

    [RFC7578] Section 2 suggests RFC3986-based percent-encoding as a mechanism to keep text-based per-part header data such as file names within the ASCII character set. This suggestion was not part of older (pre-2015) specifications for form-data, so care must be taken to ensure interoperability.

    @@ -5023,7 +4962,7 @@

    OpenAPI Specification v3.0.4

    Parameter Object when schema is present, and in the Encoding Object when at least one of style, explode, or allowReserved is present. -See Appendix C for more details of RFC6570’s two different approaches to percent-encoding, including an example involving +.

    +See Appendix C for more details of RFC6570’s two different approaches to percent-encoding, including an example involving +.

    Content-based serialization is defined by the Media Type Object, and used with the Parameter Object when the content field is present, and with the Encoding Object based on the contentType field when the fields style, explode, and allowReserved are absent. Each part is encoded based on the media type (e.g. text/plain or application/json), and must then be percent-encoded for use in a form-urlencoded string.

    Note that content-based serialization for form-data does not expect or require percent-encoding in the data, only in per-part header values.

    @@ -5040,7 +4979,7 @@

    OpenAPI Specification v3.0.4

    E.5 Percent-Encoding and Illegal or Reserved Delimiters

    -

    The [, ], |, and space characters, which are used as delimiters for the deepObject, pipeDelimited, and spaceDelimited styles, respectively, all MUST be percent-encoded to comply with[RFC3986]. +

    The [, ], |, and space characters, which are used as delimiters for the deepObject, pipeDelimited, and spaceDelimited styles, respectively, all MUST be percent-encoded to comply with [RFC3986]. This requires users to pre-encode the character(s) in some other way in parameter names and values to distinguish them from the delimiter usage when using one of these styles.

    The space character is always illegal and encoded in some way by all implementations of all versions of the relevant standards. While one could use the form-urlencoded convention of + to distinguish spaces in parameter names and values from spaceDelimited delimiters encoded as %20, the specifications define the decoding as a single pass, making it impossible to distinguish the different usages in the decoded result.

    @@ -5049,8 +4988,83 @@

    OpenAPI Specification v3.0.4

    RECOMMENDED to either define and document an additional escape convention while percent-encoding the delimiters for these styles, or to avoid these styles entirely. The exact method of additional encoding/escaping is left to the API designer, and is expected to be performed before serialization and encoding described in this specification, and reversed after this specification’s encoding and serialization steps are reversed. This keeps it outside of the processes governed by this specification.

    +

    F. Appendix F: Resolving Security Requirements in a Referenced Document

    +

    This appendix shows how to retrieve an HTTP-accessible multi-document OpenAPI Description (OAD) and resolve a Security Requirement Object in the referenced (non-entry) document. See Resolving Implicit Connections for more information.

    +

    First, the entry document is where parsing begins. It defines the MySecurity security scheme to be JWT-based, and it defines a Path Item as a reference to a component in another document:

    +
    GET /api/description/openapi HTTP/1.1
+Host: www.example.com
+Accept: application/openapi+json
+
    +
    "components": {
+  "securitySchemes": {
+    "MySecurity": {
+      "type": "http",
+      "scheme": "bearer",
+      "bearerFormat": "JWT"
+    }
+  }
+},
+"paths": {
+  "/foo": {
+    "$ref": "other#/components/pathItems/Foo"
+  }
+}
+
    +
    GET /api/description/openapi HTTP/1.1
+Host: www.example.com
+Accept: application/openapi+yaml
+
    +
    components:
+  securitySchemes:
+    MySecurity:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+paths:
+  /foo:
+    $ref: 'other#/components/pathItems/Foo'
+
    +

    This entry document references another document, other, without using a file extension. This gives the client the flexibility to choose an acceptable format on a resource-by-resource basis, assuming both representations are available:

    +
    GET /api/description/other HTTP/1.1
+Host: www.example.com
+Accept: application/openapi+json
+
    +
    "components": {
+  "securitySchemes": {
+    "MySecurity": {
+      "type": "http",
+      "scheme": "basic"
+    }
+  },
+  "pathItems": {
+    "Foo": {
+      "get": {
+        "security": [
+          "MySecurity": []
+        ]
+      }
+    }
+  }
+}
+
    +
    GET /api/description/other HTTP/1.1
+Host: www.example.com
+Accept: application/openapi+yaml
+
    +
    components:
+  securitySchemes:
+    MySecurity:
+      type: http
+      scheme: basic
+  pathItems:
+    Foo:
+      get:
+        security:
+          - MySecurity: []
+
    +

    In the other document, the referenced path item has a Security Requirement for a Security Scheme, MySecurity. The same Security Scheme exists in the original entry document. As outlined in Resolving Implicit Connections, MySecurity is resolved with an implementation-defined behavior. However, documented in that section, it is RECOMMENDED that tools resolve component names from the entry document. As with all implementation-defined behavior, it is important to check tool documentation to determine which behavior is supported.

    -

    F. References

    F.1 Normative references

    +

    G. References

    G.1 Normative references

    [ABNF]
    Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234 @@ -5127,7 +5141,7 @@

    OpenAPI Specification v3.0.4

    [YAML]
    YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html

    -

    F.2 Informative references

    +

    G.2 Informative references

    [OpenAPI-Learn]
    OpenAPI - Getting started, and the specification explained. OpenAPI Initiative. URL: https://learn.openapis.org/ diff --git a/oas/v3.1.0.html b/oas/v3.1.0.html index b643c2f4b6..d794120fba 100644 --- a/oas/v3.1.0.html +++ b/oas/v3.1.0.html @@ -1,6 +1,6 @@ - +

    What is the OpenAPI Specification?

    The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

    Status of This Document

    The source-of-truth for this specification is the HTML file referenced above as This version.
    +

    What is the OpenAPI Specification?

    The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for HTTP APIs, which allows both humans and computers to discover and understand the capabilities of a service without requiring access to source code, additional documentation, or inspection of network traffic. When properly defined via OpenAPI, a consumer can understand and interact with the remote service with a minimal amount of implementation logic. Similar to what interface descriptions have done for lower-level programming, the OpenAPI Specification removes guesswork in calling a service.

    Status of This Document

    The source-of-truth for this specification is the HTML file referenced above as This version.

    1. OpenAPI Specification

    1.1 Version 3.1.1

    The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

    @@ -343,7 +343,9 @@

    OpenAPI Specification v3.1.1

    4.3 OpenAPI Description Structure

    An OpenAPI Description (OAD) MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the author. In the latter case, Reference Object, Path Item Object and Schema Object $ref keywords, as well as the Link Object operationRef keyword, are used.

    -

    Any document consisting entirely of an OpenAPI Object is known as a complete OpenAPI document. +

    Any document consisting entirely of an OpenAPI Object is known as a syntactically complete OpenAPI document. +An OpenAPI document that does not reference any other documents is known as a self-contained OpenAPI document. +A single-document description is therefore both syntactically complete and self-contained. In a multi-document description, the document containing the OpenAPI Object where parsing begins for a specific API’s description is known as that API’s entry OpenAPI document, or simply entry document.

    It is RECOMMENDED that the entry OpenAPI document be named: openapi.json or openapi.yaml.

    4.3.1 Parsing Documents

    @@ -368,7 +370,7 @@

    OpenAPI Specification v3.1.1

    4.3.2 Structural Interoperability

    When parsing an OAD, JSON or YAML objects are parsed into specific Objects (such as Operation Objects, Response Objects, Reference Objects, etc.) based on the parsing context. Depending on how references are arranged, a given JSON or YAML object can be parsed in multiple different contexts:

      -
    • As a complete OpenAPI Description document
      • +
    • As a syntactically complete OpenAPI Description document
    • As the Object type implied by its parent Object within the document
    • As a reference target, with the Object type matching the reference source’s context
    @@ -421,7 +423,7 @@

    OpenAPI Specification v3.1.1

    Security Requirement in a Referenced Document for an example of the possible resolutions, including which one is recommended by this section. +

    See Appendix F: Resolving Security Requirements in a Referenced Document for an example of the possible resolutions, including which one is recommended by this section. The behavior for Discrimator Object non-URI mappings and for the Operation Object’s tags field operate on the same principles.

    Note that no aspect of implicit connection resolution changes how URIs are resolved, or restricts their possible targets.

    4.4 Data Types

    @@ -557,11 +559,11 @@

    OpenAPI Specification v3.1.1

    MUST be resolved using the referring document’s base URI, which is determined in accordance with [RFC3986] Section 5.1.2 – 5.1.4. In practice, this is usually the retrieval URI of the document, which MAY be determined based on either its current actual location or a user-supplied expected location.

    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 CommonMark hyperlinks are resolved in their rendered context, which might differ from the context of the API description.

    4.7 Relative References in API URLs

    API endpoints are by definition accessed as locations, and are described by this specification as URLs.

    Unless specified otherwise, all fields 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.

    -

    Relative references in CommonMark hyperlinks are resolved in their rendered context, which might differ from the context of the API description.

    4.8 Schema

    This section describes the structure of the OpenAPI Description format. This text is the only normative description of the format. @@ -618,7 +620,7 @@

    OpenAPI Specification v3.1.1

    security

    - + @@ -870,7 +872,7 @@

    OpenAPI Specification v3.1.1

    "variables": { "username": { "default": "demo", - "description": "this value is assigned by the service provider, in this example `gigantic-server.com`" + "description": "A user-specific subdomain. Use `demo` for a free sandbox environment." }, "port": { "enum": ["8443", "443"], @@ -891,7 +893,7 @@

    OpenAPI Specification v3.1.1

    username: # note! no enum here means it is an open value default: demo - description: this value is assigned by the service provider, in this example `gigantic-server.com` + description: A user-specific subdomain. Use `demo` for a free sandbox environment. port: enum: - '8443' @@ -921,7 +923,7 @@

    OpenAPI Specification v3.1.1

    default

    - + @@ -1703,7 +1705,7 @@

    OpenAPI Specification v3.1.1

    allowReserved

    - + @@ -1722,7 +1724,7 @@

    OpenAPI Specification v3.1.1

    Appendix C: Using RFC6570 Implementations for additional guidance.

    +

    See also Appendix C: Using RFC6570-Based Serialization for additional guidance.

    4.8.12.2.3 Fixed Fields for use with content

    For more complex scenarios, the content field can define the media type and schema of the parameter, as well as give examples of its use. Using content with a text/plain media type is RECOMMENDED for in: "header" and in: "cookie" parameters where the schema strategy is not appropriate.

    @@ -1810,7 +1812,7 @@

    OpenAPI Specification v3.1.1

    RFC6570] Section 2.3 terminology, which describes certain values including but not limited to null as “undefined” values with special handling; notably, the empty string is not undefined -
  • For form and the non-RFC6570 query string styles spaceDelimited, pipeDelimited, and deepObject, each example is shown prefixed with ? as if it were the only query parameter; see Appendix C for more information on constructing query strings from multiple parameters, and Appendix D for warnings regarding form and cookie parameters
    • +
  • For form and the non-RFC6570 query string styles spaceDelimited, pipeDelimited, and deepObject, each example is shown prefixed with ? as if it were the only query parameter; see Appendix C for more information on constructing query strings from multiple parameters, and Appendix D for warnings regarding form and cookie parameters
  • Note that the ? prefix is not appropriate for serializing application/x-www-form-urlencoded HTTP message bodies, and MUST be stripped or (if constructing the string manually) not added when used in that context; see the Encoding Object for more information
  • The examples are percent-encoded as required by RFC6570 and RFC3986; see Appendix E for a thorough discussion of percent-encoding concerns, including why unencoded | (%7C), [ (%5B), and ] (%5D) seem to work in some environments despite not being compliant.
    • @@ -2404,11 +2406,11 @@

    OpenAPI Specification v3.1.1

    allowReserved

    - +
    When schema is present
    Encoding Object When encoding for application/x-www-form-urlencoded and any of style, explode, or allowReserved are used
    [Security Requirement Object]A declaration of which security mechanisms can be used across the API. The list of values includes alternative Security Requirement Objects that can be used. Only one of the Security Requirement Objects need to be satisfied to authorize a request. Individual operations can override this definition. To make security optional, an empty security requirement ({}) can be included in the array.A declaration of which security mechanisms can be used across the API. The list of values includes alternative Security Requirement Objects that can be used. Only one of the Security Requirement Objects need to be satisfied to authorize a request. Individual operations can override this definition. The list can be incomplete, up to being empty or absent. To make security explicitly optional, an empty security requirement ({}) can be included in the array.
    tagsstringREQUIRED. The default value to use for substitution, which SHALL be sent if an alternate value is not supplied. Note this behavior is different than the Schema Object’s treatment of default values, because in those cases parameter values are optional. If the enum is defined, the value MUST exist in the enum’s values.REQUIRED. The default value to use for substitution, which SHALL be sent if an alternate value is not supplied. If the enum is defined, the value MUST exist in the enum’s values. Note that this behavior is different from the Schema Object’s default keyword, which documents the receiver’s behavior rather than inserting the value into the data.
    descriptionbooleanWhen this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570] Section 3.2.3, which allows RFC3986’s reserved character set, as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including % outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are not allowed in the query string ([, ], #), or have a special meaning in application/x-www-form-urlencoded (-, &, +); see Appendices C and E for details. This field only applies to parameters with an in value of query. The default value is false.When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570] Section 3.2.3, which allows RFC3986’s reserved character set, as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including % outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are not allowed in the query string ([, ], #), or have a special meaning in application/x-www-form-urlencoded (-, &, +); see Appendices C and E for details. This field only applies to parameters with an in value of query. The default value is false.
    schemabooleanWhen this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570] Section 3.2.3, which allows RFC3986’s reserved character set, as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including % outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are not allowed in the query string ([, ], #), or have a special meaning in application/x-www-form-urlencoded (-, &, +); see Appendices C and E for details. The default value is false. This field 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.When this is true, parameter values are serialized using reserved expansion, as defined by [RFC6570] Section 3.2.3, which allows RFC3986’s reserved character set, as well as percent-encoded triples, to pass through unchanged, while still percent-encoding all other disallowed characters (including % outside of percent-encoded triples). Applications are still responsible for percent-encoding reserved characters that are not allowed in the query string ([, ], #), or have a special meaning in application/x-www-form-urlencoded (-, &, +); see Appendices C and E for details. The default value is false. This field 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.
    -

    See also Appendix C: Using RFC6570 Implementations for additional guidance, including on difficulties caused by the interaction between RFC6570’s percent-encoding rules and the multipart/form-data media type.

    +

    See also Appendix C: Using RFC6570 Implementations for additional guidance, including on difficulties caused by the interaction between RFC6570’s percent-encoding rules and the multipart/form-data media type.

    Note that the presence of at least one of style, explode, or allowReserved with an explicit value is equivalent to using schema with in: "query" Parameter Objects. The absence of all three of those fields is the equivalent of using content, but with the media type specified in contentType rather than through a Media Type Object.

    4.8.15.2 Encoding the x-www-form-urlencoded Media Type
    @@ -3117,9 +3119,10 @@

    OpenAPI Specification v3.1.1

    MAY be extended with Specification Extensions.

    A linked operation MUST be identified using either an operationRef or operationId. -In the case of an operationId, it MUST be unique and resolved in the scope of the OpenAPI description. -Because of the potential for name clashes, the operationRef syntax is preferred -for multi-document OpenAPI descriptions.

    +The identified or reference operation MUST be unique, and in the case of an operationId, it MUST be resolved within the scope of the OpenAPI Description (OAD). +Because of the potential for name clashes, the operationRef syntax is preferred for multi-document OADs. +However, because use of an operation depends on its URL path template in the Paths Object, operations from any Path Item Object that is referenced multiple times within the OAD cannot be resolved unambiguously. +In such ambiguous cases, the resulting behavior is implementation-defined and MAY result in an error.

    Note that it is not possible to provide a constant value to parameters that matches the syntax of a runtime expression. It is possible to have ambiguous parameter names, e.g. name: "id", in: "path" and name: "path.id", in: "query"; this is NOT RECOMMENDED and the behavior is implementation-defined, however implementations SHOULD prefer the qualified interpretation (path.id as a path parameter), as the names can always be qualified to disambiguate them (e.g. using query.path.id for the query parameter).

    4.8.20.2 Examples
    @@ -3353,7 +3356,7 @@

    OpenAPI Specification v3.1.1

    Appendix C: Using RFC6570 Implementations for additional guidance.

    +

    See also Appendix C: Using RFC6570-Based Serialization for additional guidance.

    4.8.21.1.3 Fixed Fields for use with content

    For more complex scenarios, the content field can define the media type and schema of the header, as well as give examples of its use. Using content with a text/plain media type is RECOMMENDED for headers where the schema strategy is not appropriate.

    @@ -4667,6 +4670,7 @@

    OpenAPI Specification v3.1.1

    4.8.30.2 Security Requirement Object Examples
    +

    See also Appendix F: Resolving Security Requirements in a Referenced Document for an example using Security Requirement Objects in multi-document OpenAPI Descriptions.

    4.8.30.2.1 Non-OAuth2 Security Requirement
    {
   "api_key": []
@@ -4700,81 +4704,6 @@ 
    OpenAPI Specification v3.1.1 
     
    - write:pets
       - read:pets
    -
    4.8.30.2.4 Security Requirement in a Referenced Document
    -

    See Resolving Implicit Connections for more information.

    -

    First, our entry document is where parsing begins. It defines the MySecurity security scheme to be JWT-based, and it defines a Path Item as a reference to a component in another document:

    -
    GET /api/description/openapi HTTP/1.1
-Host: www.example.com
-Accept: application/openapi+json
-
    -
    "components": {
-  "securitySchemes": {
-    "MySecurity": {
-      "type": "http",
-      "scheme": "bearer",
-      "bearerFormat": "JWT"
-    }
-  }
-},
-"paths": {
-  "/foo": {
-    "$ref": "other#/components/pathItems/Foo"
-  }
-}
-
    -
    GET /api/description/openapi HTTP/1.1
-Host: www.example.com
-Accept: application/openapi+yaml
-
    -
    components:
-  securitySchemes:
-    MySecurity:
-      type: http
-      scheme: bearer
-      bearerFormat: JWT
-paths:
-  /foo:
-    $ref: 'other#/components/pathItems/Foo'
-
    -

    Next, we have our referenced document, other. The fact that we don’t use file extensions gives the client the flexibility to choose an acceptable format on a resource-by-resource basis, assuming both representations are available:

    -
    GET /api/description/other HTTP/1.1
-Host: www.example.com
-Accept: application/openapi+json
-
    -
    "components": {
-  "securitySchemes": {
-    "MySecurity": {
-      "type": "http",
-      "scheme": "basic"
-    }
-  },
-  "pathItems": {
-    "Foo": {
-      "get": {
-        "security": [
-          "MySecurity": []
-        ]
-      }
-    }
-  }
-}
-
    -
    GET /api/description/other HTTP/1.1
-Host: www.example.com
-Accept: application/openapi+yaml
-
    -
    components:
-  securitySchemes:
-    MySecurity:
-      type: http
-      scheme: basic
-  pathItems:
-    Foo:
-      get:
-        security:
-          - MySecurity: []
-
    -

    In the other document, the referenced path item has a Security Requirement for a Security Scheme, MySecurity. The same Security Scheme exists in the original entry document. As outlined in Resolving Implicit Connections, MySecurity is resolved with an implementation-defined behavior. However, documented in that section, it is RECOMMENDED that tools resolve component names from the entry document. As with all implementation-defined behavior, it is important to check tool documentation to determine which behavior is supported.

    4.9 Specification Extensions

    While the OpenAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.

    The extensions properties are implemented as patterned fields that are always prefixed by x-.

    @@ -4941,8 +4870,8 @@

    OpenAPI Specification v3.1.1

    decimal in the Format Registry) are less clear. However, care must be taken with format to ensure that the specific formats are supported by all relevant tools as unrecognized formats are ignored.

    Requiring input as pre-formatted, schema-validated strings also improves round-trip interoperability as not all programming languages and environments support the same data types.

    -

    C. Appendix C: Using RFC6570 Implementations

    -

    Serialization is defined in terms of [RFC6570] URI Templates in two scenarios:

    +

    C. Appendix C: Using RFC6570-Based Serialization

    +

    Serialization is defined in terms of [RFC6570] URI Templates in three scenarios:

    @@ -4956,6 +4885,10 @@

    OpenAPI Specification v3.1.1

    Header Object +

    + + @@ -5033,10 +4966,15 @@

    OpenAPI Specification v3.1.1

    schema: type: string -

    This example is equivalent to RFC6570’s {?foo*,bar}, and NOT {?foo*}{&bar}. The latter is problematic because if foo is not defined, the result will be an invalid URI. +

    This example is equivalent to RFC6570’s {?foo*,bar}, and NOT {?foo*}{&bar}. The latter is problematic because if foo is not defined, the result will be an invalid URI. The & prefix operator has no equivalent in the Parameter Object.

    -

    Note that RFC6570 does not specify behavior for compound values beyond the single level addressed by explode. The results of using objects or arrays where no behavior is clearly specified for them is implementation-defined.

    -

    C.2 Non-RFC6570 Field Values and Combinations

    +

    Note that RFC6570 does not specify behavior for compound values beyond the single level addressed by explode. The result of using objects or arrays where no behavior is clearly specified for them is implementation-defined.

    +

    C.2 Delimiters in Parameter Values

    +

    Delimiters used by RFC6570 expansion, such as the , used to join arrays or object values with style: "simple", are all automatically percent-encoded as long as allowReserved is false. +Note that since RFC6570 does not define a way to parse variables based on a URI Template, users must take care to first split values by delimiter before percent-decoding values that might contain the delimiter character.

    +

    When allowReserved is true, both percent-encoding (prior to joining values with a delimiter) and percent-decoding (after splitting on the delimiter) must be done manually at the correct time.

    +

    See Appendix E for additional guidance on handling delimiters for style values with no RFC6570 equivalent that already need to be percent-encoded when used as delimiters.

    +

    C.3 Non-RFC6570 Field Values and Combinations

    Configurations with no direct [RFC6570] equivalent SHOULD also be handled according to RFC6570. Implementations MAY create a properly delimited URI Template with variables for individual names and values using RFC6570 regular or reserved expansion (based on allowReserved).

    This includes:

    @@ -5047,7 +4985,7 @@

    OpenAPI Specification v3.1.1

    variable name syntax. A parameter name that includes characters outside of the allowed RFC6570 variable character set MUST be percent-encoded before it can be used in a URI Template.

    -

    C.3 Examples

    +

    C.4 Examples

    Let’s say we want to use the following data in a form query string, where formulas is exploded, and words is not:

    formulas:
   a: x+y
@@ -5058,7 +4996,7 @@ 
    OpenAPI Specification v3.1.1 
     
    - is
 - fun
    -

    C.3.1 RFC6570-Equivalent Expansion

    +

    C.4.1 RFC6570-Equivalent Expansion

    This array of Parameter Objects uses regular style: "form" expansion, fully supported by [RFC6570]:

    parameters:
 - name: formulas
@@ -5081,7 +5019,7 @@ 
    OpenAPI Specification v3.1.1 
     
    ?a=x%2By&b=x%2Fy&c=x%5Ey&words=math,is,fun
    -

    C.3.2 Expansion with Non-RFC6570-Supported Options

    +

    C.4.2 Expansion with Non-RFC6570-Supported Options

    But now let’s say that (for some reason), we really want that / in the b formula to show up as-is in the query string, and we want our words to be space-separated like in a written phrase. To do that, we’ll add allowReserved: true to formulas, and change to style: "spaceDelimited" for words:

    parameters:
@@ -5096,6 +5034,7 @@ 
    OpenAPI Specification v3.1.1 
     
    - name: words
   in: query
   style: spaceDelimited
+  explode: false
   schema:
     type: array
     items:
@@ -5124,7 +5063,7 @@ 
    OpenAPI Specification v3.1.1 
     
    ?a=x%2By&b=x/y&c=x%5Ey&words=math%20is%20fun

    The / and the pre-percent-encoded %2B have been left alone, but the disallowed ^ character (inside a value) and space characters (in the template but outside of the expanded variables) were percent-encoded.

    -

    C.3.3 Undefined Values and Manual URI Template Construction

    +

    C.4.3 Undefined Values and Manual URI Template Construction

    Care must be taken when manually constructing templates to handle the values that RFC6570 considers to be undefined correctly:

    formulas: {}
 words:
@@ -5145,7 +5084,7 @@ 
    OpenAPI Specification v3.1.1 
     
    ?words=hello%20world
    -

    C.3.4 Illegal Variable Names as Parameter Names

    +

    C.4.4 Illegal Variable Names as Parameter Names

    In this example, the heart emoji is not legal in URI Template names (or URIs):

    parameters:
 - name: ❤️
@@ -5173,7 +5112,7 @@ 
    OpenAPI Specification v3.1.1 
     
    , that delimiter would itself be percent-encoded, violating the general HTTP field syntax.
    
 
    Using style: "form" with in: "cookie" is ambiguous for a single value, and incorrect for multiple values.
 This is true whether the multiple values are the result of using explode: true or not.
    
-
    This style is specified to be equivalent to RFC6570 form expansion which includes the ? character (see Appendix C for more details), which is not part of the cookie syntax.
+
    This style is specified to be equivalent to RFC6570 form expansion which includes the ? character (see Appendix C for more details), which is not part of the cookie syntax.
 However, examples of this style in past versions of this specification have not included the ? prefix, suggesting that the comparison is not exact.
 Because implementations that rely on an RFC6570 implementation and those that perform custom serialization based on the style example will produce different results, it is implementation-defined as to which of the two results is correct.
    
 
    For multiple values, style: "form" is always incorrect as name=value pairs in cookies are delimited by ; (a semicolon followed by a space character) rather than &.
    
@@ -5192,7 +5131,7 @@ 
    OpenAPI Specification v3.1.1 
     
    Appendix C for an example of handling + in form values.
    
+This means that while these three characters are reserved-but-allowed in query strings by RFC3986, they must be percent-encoded in form-urlencoded query strings except when used for their form-urlencoded purposes; see Appendix C for an example of handling + in form values.

    E.2 Percent-Encoding and form-data

    [RFC7578] Section 2 suggests RFC3986-based percent-encoding as a mechanism to keep text-based per-part header data such as file names within the ASCII character set. This suggestion was not part of older (pre-2015) specifications for form-data, so care must be taken to ensure interoperability.

    @@ -5237,7 +5176,7 @@

    OpenAPI Specification v3.1.1

    Parameter Object when schema is present, and in the Encoding Object when at least one of style, explode, or allowReserved is present. -See Appendix C for more details of RFC6570’s two different approaches to percent-encoding, including an example involving +.

    +See Appendix C for more details of RFC6570’s two different approaches to percent-encoding, including an example involving +.

    Content-based serialization is defined by the Media Type Object, and used with the Parameter Object when the content field is present, and with the Encoding Object based on the contentType field when the fields style, explode, and allowReserved are absent. Each part is encoded based on the media type (e.g. text/plain or application/json), and must then be percent-encoded for use in a form-urlencoded string.

    Note that content-based serialization for form-data does not expect or require percent-encoding in the data, only in per-part header values.

    @@ -5254,7 +5193,7 @@

    OpenAPI Specification v3.1.1

    E.5 Percent-Encoding and Illegal or Reserved Delimiters

    -

    The [, ], |, and space characters, which are used as delimiters for the deepObject, pipeDelimited, and spaceDelimited styles, respectively, all MUST be percent-encoded to comply with[RFC3986]. +

    The [, ], |, and space characters, which are used as delimiters for the deepObject, pipeDelimited, and spaceDelimited styles, respectively, all MUST be percent-encoded to comply with [RFC3986]. This requires users to pre-encode the character(s) in some other way in parameter names and values to distinguish them from the delimiter usage when using one of these styles.

    The space character is always illegal and encoded in some way by all implementations of all versions of the relevant standards. While one could use the form-urlencoded convention of + to distinguish spaces in parameter names and values from spaceDelimited delimiters encoded as %20, the specifications define the decoding as a single pass, making it impossible to distinguish the different usages in the decoded result.

    @@ -5263,8 +5202,83 @@

    OpenAPI Specification v3.1.1

    RECOMMENDED to either define and document an additional escape convention while percent-encoding the delimiters for these styles, or to avoid these styles entirely. The exact method of additional encoding/escaping is left to the API designer, and is expected to be performed before serialization and encoding described in this specification, and reversed after this specification’s encoding and serialization steps are reversed. This keeps it outside of the processes governed by this specification.

    +

    F. Appendix F: Resolving Security Requirements in a Referenced Document

    +

    This appendix shows how to retrieve an HTTP-accessible multi-document OpenAPI Description (OAD) and resolve a Security Requirement Object in the referenced (non-entry) document. See Resolving Implicit Connections for more information.

    +

    First, the entry document is where parsing begins. It defines the MySecurity security scheme to be JWT-based, and it defines a Path Item as a reference to a component in another document:

    +
    GET /api/description/openapi HTTP/1.1
+Host: www.example.com
+Accept: application/openapi+json
+
    +
    "components": {
+  "securitySchemes": {
+    "MySecurity": {
+      "type": "http",
+      "scheme": "bearer",
+      "bearerFormat": "JWT"
+    }
+  }
+},
+"paths": {
+  "/foo": {
+    "$ref": "other#/components/pathItems/Foo"
+  }
+}
+
    +
    GET /api/description/openapi HTTP/1.1
+Host: www.example.com
+Accept: application/openapi+yaml
+
    +
    components:
+  securitySchemes:
+    MySecurity:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+paths:
+  /foo:
+    $ref: 'other#/components/pathItems/Foo'
+
    +

    This entry document references another document, other, without using a file extension. This gives the client the flexibility to choose an acceptable format on a resource-by-resource basis, assuming both representations are available:

    +
    GET /api/description/other HTTP/1.1
+Host: www.example.com
+Accept: application/openapi+json
+
    +
    "components": {
+  "securitySchemes": {
+    "MySecurity": {
+      "type": "http",
+      "scheme": "basic"
+    }
+  },
+  "pathItems": {
+    "Foo": {
+      "get": {
+        "security": [
+          "MySecurity": []
+        ]
+      }
+    }
+  }
+}
+
    +
    GET /api/description/other HTTP/1.1
+Host: www.example.com
+Accept: application/openapi+yaml
+
    +
    components:
+  securitySchemes:
+    MySecurity:
+      type: http
+      scheme: basic
+  pathItems:
+    Foo:
+      get:
+        security:
+          - MySecurity: []
+
    +

    In the other document, the referenced path item has a Security Requirement for a Security Scheme, MySecurity. The same Security Scheme exists in the original entry document. As outlined in Resolving Implicit Connections, MySecurity is resolved with an implementation-defined behavior. However, documented in that section, it is RECOMMENDED that tools resolve component names from the entry document. As with all implementation-defined behavior, it is important to check tool documentation to determine which behavior is supported.

    -

    F. References

    F.1 Normative references

    +

    G. References

    G.1 Normative references

    [ABNF]
    Augmented BNF for Syntax Specifications: ABNF. D. Crocker, Ed.; P. Overell. IETF. January 2008. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc5234 @@ -5339,7 +5353,7 @@

    OpenAPI Specification v3.1.1

    [YAML]
    YAML Ain’t Markup Language (YAML™) Version 1.2. Oren Ben-Kiki; Clark Evans; Ingy döt Net. 1 October 2009. URL: http://yaml.org/spec/1.2/spec.html

    -

    F.2 Informative references

    +

    G.2 Informative references

    [OpenAPI-Learn]
    OpenAPI - Getting started, and the specification explained. OpenAPI Initiative. URL: https://learn.openapis.org/

    When schema is present
    Encoding Object When encoding for application/x-www-form-urlencoded and any of style, explode, or allowReserved are used