From 97247492c72c393fcf112a2d05f80e7faf36410f Mon Sep 17 00:00:00 2001 From: Mike Ralphson Date: Thu, 13 May 2021 14:34:43 +0100 Subject: [PATCH] fix: regenerate respec versions, refs #2488 Signed-off-by: Mike Ralphson --- oas/v2.0.html | 1460 +++++++++++++-------------- oas/v3.0.0.html | 2482 ++++++++++++++++++++++----------------------- oas/v3.0.1.html | 2402 ++++++++++++++++++++++---------------------- oas/v3.0.2.html | 2546 +++++++++++++++++++++++------------------------ oas/v3.0.3.html | 1420 +++++++++++++------------- oas/v3.1.0.html | 188 ++-- 6 files changed, 5253 insertions(+), 5245 deletions(-) diff --git a/oas/v2.0.html b/oas/v2.0.html index d8c5f210ad..d269a5da5c 100644 --- a/oas/v2.0.html +++ b/oas/v2.0.html @@ -1,4 +1,4 @@ -OpenAPI Specification +OpenAPI Specification +OpenAPI Specification +OpenAPI Specification +OpenAPI Specification
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST 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 the specification is the GitHub markdown file referenced above.
+OpenAPI Specification + + +
The OpenAPI Specification (OAS) defines a standard, programming language-agnostic interface description for REST 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 the specification is the GitHub markdown file referenced above.

OpenAPI Specification

Version 3.0.3

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.

@@ -44,7 +52,7 @@

For example, if a field has an array value, the JSON array representation will be used:


 {
-   "field": [ 1, 2, 3 ]
+   "field": [ 1, 2, 3 ]
 }

All field names in the specification are case sensitive. @@ -250,19 +258,19 @@

Info Object Example


 {
-  "title": "Sample Pet Store App",
-  "description": "This is a sample server for a pet store.",
-  "termsOfService": "http://example.com/terms/",
-  "contact": {
-    "name": "API Support",
-    "url": "http://www.example.com/support",
-    "email": "support@example.com"
+  "title": "Sample Pet Store App",
+  "description": "This is a sample server for a pet store.",
+  "termsOfService": "http://example.com/terms/",
+  "contact": {
+    "name": "API Support",
+    "url": "http://www.example.com/support",
+    "email": "support@example.com"
   },
-  "license": {
-    "name": "Apache 2.0",
-    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
+  "license": {
+    "name": "Apache 2.0",
+    "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
   },
-  "version": "1.0.1"
+  "version": "1.0.1"
 }
 

@@ -311,9 +319,9 @@

Contact Object Example


 {
-  "name": "API Support",
-  "url": "http://www.example.com/support",
-  "email": "support@example.com"
+  "name": "API Support",
+  "url": "http://www.example.com/support",
+  "email": "support@example.com"
 }
 

@@ -349,8 +357,8 @@

License Object Example


 {
-  "name": "Apache 2.0",
-  "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
+  "name": "Apache 2.0",
+  "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
 }
 

@@ -391,8 +399,8 @@
 
A single server would be described as:

 

 {
-  "url": "https://development.gigantic-server.com/v1",
-  "description": "Development server"
+  "url": "https://development.gigantic-server.com/v1",
+  "description": "Development server"
 }
 

 

@@ -402,18 +410,18 @@
 
The following shows how multiple servers can be described, for example, at the OpenAPI Object’s servers:

 

 {
-  "servers": [
+  "servers": [
     {
-      "url": "https://development.gigantic-server.com/v1",
-      "description": "Development server"
+      "url": "https://development.gigantic-server.com/v1",
+      "description": "Development server"
     },
     {
-      "url": "https://staging.gigantic-server.com/v1",
-      "description": "Staging server"
+      "url": "https://staging.gigantic-server.com/v1",
+      "description": "Staging server"
     },
     {
-      "url": "https://api.gigantic-server.com/v1",
-      "description": "Production server"
+      "url": "https://api.gigantic-server.com/v1",
+      "description": "Production server"
     }
   ]
 }
@@ -430,24 +438,24 @@
 
The following shows how variables can be used for a server configuration:

 

 {
-  "servers": [
+  "servers": [
     {
-      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
-      "description": "The production API server",
-      "variables": {
-        "username": {
-          "default": "demo",
-          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
+      "url": "https://{username}.gigantic-server.com:{port}/{basePath}",
+      "description": "The production API server",
+      "variables": {
+        "username": {
+          "default": "demo",
+          "description": "this value is assigned by the service provider, in this example `gigantic-server.com`"
         },
-        "port": {
-          "enum": [
-            "8443",
-            "443"
+        "port": {
+          "enum": [
+            "8443",
+            "443"
           ],
-          "default": "8443"
+          "default": "8443"
         },
-        "basePath": {
-          "default": "v2"
+        "basePath": {
+          "default": "v2"
         }
       }
     }
@@ -465,9 +473,9 @@
       description: this value is assigned by the service provider, in this example `gigantic-server.com`
     port:
       enum:
-        - '8443'
-        - '443'
-      default: '8443'
+        - '8443'
+        - '443'
+      default: '8443'
     basePath:
       # open meaning there is the opportunity to use special base paths as assigned by the provider, default is `v2`
       default: v2
@@ -517,47 +525,47 @@
 
 
   schemas
-Map[string, Schema Object ¦ Reference Object]
+Map[string, Schema Object | Reference Object]
 An object to hold reusable Schema Objects.
 
 
   responses
-Map[string, Response Object ¦ Reference Object]
+Map[string, Response Object | Reference Object]
 An object to hold reusable Response Objects.
 
 
   parameters
-Map[string, Parameter Object ¦ Reference Object]
+Map[string, Parameter Object | Reference Object]
 An object to hold reusable Parameter Objects.
 
 
   examples
-Map[string, Example Object ¦ Reference Object]
+Map[string, Example Object | Reference Object]
 An object to hold reusable Example Objects.
 
 
   requestBodies
-Map[string, Request Body Object ¦ Reference Object]
+Map[string, Request Body Object | Reference Object]
 An object to hold reusable Request Body Objects.
 
 
   headers
-Map[string, Header Object ¦ Reference Object]
+Map[string, Header Object | Reference Object]
 An object to hold reusable Header Objects.
 
 
   securitySchemes
-Map[string, Security Scheme Object ¦ Reference Object]
+Map[string, Security Scheme Object | Reference Object]
 An object to hold reusable Security Scheme Objects.
 
 
   links
-Map[string, Link Object ¦ Reference Object]
+Map[string, Link Object | Reference Object]
 An object to hold reusable Link Objects.
 
 
   callbacks
-Map[string, Callback Object ¦ Reference Object]
+Map[string, Callback Object | Reference Object]
 An object to hold reusable Callback Objects.
 
 
@@ -574,99 +582,99 @@

Components Object Example


-"components": {
-  "schemas": {
-    "GeneralError": {
-      "type": "object",
-      "properties": {
-        "code": {
-          "type": "integer",
-          "format": "int32"
+"components": {
+  "schemas": {
+    "GeneralError": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "integer",
+          "format": "int32"
         },
-        "message": {
-          "type": "string"
+        "message": {
+          "type": "string"
         }
       }
     },
-    "Category": {
-      "type": "object",
-      "properties": {
-        "id": {
-          "type": "integer",
-          "format": "int64"
+    "Category": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "integer",
+          "format": "int64"
         },
-        "name": {
-          "type": "string"
+        "name": {
+          "type": "string"
         }
       }
     },
-    "Tag": {
-      "type": "object",
-      "properties": {
-        "id": {
-          "type": "integer",
-          "format": "int64"
+    "Tag": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "integer",
+          "format": "int64"
         },
-        "name": {
-          "type": "string"
+        "name": {
+          "type": "string"
         }
       }
     }
   },
-  "parameters": {
-    "skipParam": {
-      "name": "skip",
-      "in": "query",
-      "description": "number of items to skip",
-      "required": true,
-      "schema": {
-        "type": "integer",
-        "format": "int32"
+  "parameters": {
+    "skipParam": {
+      "name": "skip",
+      "in": "query",
+      "description": "number of items to skip",
+      "required": true,
+      "schema": {
+        "type": "integer",
+        "format": "int32"
       }
     },
-    "limitParam": {
-      "name": "limit",
-      "in": "query",
-      "description": "max records to return",
-      "required": true,
-      "schema" : {
-        "type": "integer",
-        "format": "int32"
+    "limitParam": {
+      "name": "limit",
+      "in": "query",
+      "description": "max records to return",
+      "required": true,
+      "schema" : {
+        "type": "integer",
+        "format": "int32"
       }
     }
   },
-  "responses": {
-    "NotFound": {
-      "description": "Entity not found."
+  "responses": {
+    "NotFound": {
+      "description": "Entity not found."
     },
-    "IllegalInput": {
-      "description": "Illegal input for operation."
+    "IllegalInput": {
+      "description": "Illegal input for operation."
     },
-    "GeneralError": {
-      "description": "General Error",
-      "content": {
-        "application/json": {
-          "schema": {
-            "$ref": "#/components/schemas/GeneralError"
+    "GeneralError": {
+      "description": "General Error",
+      "content": {
+        "application/json": {
+          "schema": {
+            "$ref": "#/components/schemas/GeneralError"
           }
         }
       }
     }
   },
-  "securitySchemes": {
-    "api_key": {
-      "type": "apiKey",
-      "name": "api_key",
-      "in": "header"
+  "securitySchemes": {
+    "api_key": {
+      "type": "apiKey",
+      "name": "api_key",
+      "in": "header"
     },
-    "petstore_auth": {
-      "type": "oauth2",
-      "flows": {
-        "implicit": {
-          "authorizationUrl": "http://example.org/api/oauth/dialog",
-          "scopes": {
-            "write:pets": "modify pets in your account",
-            "read:pets": "read your pets"
+    "petstore_auth": {
+      "type": "oauth2",
+      "flows": {
+        "implicit": {
+          "authorizationUrl": "http://example.org/api/oauth/dialog",
+          "scopes": {
+            "write:pets": "modify pets in your account",
+            "read:pets": "read your pets"
           }
         }
       }
@@ -728,7 +736,7 @@
       content:
         application/json:
           schema:
-            $ref: '#/components/schemas/GeneralError'
+            $ref: '#/components/schemas/GeneralError'
   securitySchemes:
     api_key:
       type: apiKey
@@ -759,7 +767,7 @@
 
  /{path}
 Path Item Object
-A relative path to an individual endpoint. The field name MUST begin with a forward slash (/). The path is appended (no relative URL resolution) to the expanded URL from the Server Object's url field in order to construct the full URL. Path templating is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it’s up to the tooling to decide which one to use.
+A relative path to an individual endpoint. The field name MUST begin with a forward slash (/). The path is appended (no relative URL resolution) to the expanded URL from the Server Object’s url field in order to construct the full URL. Path templating is allowed. When matching URLs, concrete (non-templated) paths would be matched before their templated counterparts. Templated paths with the same hierarchy but different templated names MUST NOT exist as they are identical. In case of ambiguous matching, it’s up to the tooling to decide which one to use.
 
 
 
@@ -783,18 +791,18 @@

Paths Object Example


 {
-  "/pets": {
-    "get": {
-      "description": "Returns all pets from the system that the user has access to",
-      "responses": {
-        "200": {          
-          "description": "A list of pets.",
-          "content": {
-            "application/json": {
-              "schema": {
-                "type": "array",
-                "items": {
-                  "$ref": "#/components/schemas/pet"
+  "/pets": {
+    "get": {
+      "description": "Returns all pets from the system that the user has access to",
+      "responses": {
+        "200": {          
+          "description": "A list of pets.",
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/components/schemas/pet"
                 }
               }
             }
@@ -810,14 +818,14 @@
   get:
     description: Returns all pets from the system that the user has access to
     responses:
-      '200':
+      '200':
         description: A list of pets.
         content:
           application/json:
             schema:
               type: array
               items:
-                $ref: '#/components/schemas/pet'
+                $ref: '#/components/schemas/pet'

Path Item Object

Describes the operations available on a single path. @@ -895,7 +903,7 @@ parameters -[Parameter Object ¦ Reference Object] +[Parameter Object | Reference Object] A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object’s components/parameters. @@ -904,49 +912,49 @@

Path Item Object Example


 {
-  "get": {
-    "description": "Returns pets based on ID",
-    "summary": "Find pets by ID",
-    "operationId": "getPetsById",
-    "responses": {
-      "200": {
-        "description": "pet response",
-        "content": {
-          "*/*": {
-            "schema": {
-              "type": "array",
-              "items": {
-                "$ref": "#/components/schemas/Pet"
+  "get": {
+    "description": "Returns pets based on ID",
+    "summary": "Find pets by ID",
+    "operationId": "getPetsById",
+    "responses": {
+      "200": {
+        "description": "pet response",
+        "content": {
+          "*/*": {
+            "schema": {
+              "type": "array",
+              "items": {
+                "$ref": "#/components/schemas/Pet"
               }
             }
           }
         }
       },
-      "default": {
-        "description": "error payload",
-        "content": {
-          "text/html": {
-            "schema": {
-              "$ref": "#/components/schemas/ErrorModel"
+      "default": {
+        "description": "error payload",
+        "content": {
+          "text/html": {
+            "schema": {
+              "$ref": "#/components/schemas/ErrorModel"
             }
           }
         }
       }
     }
   },
-  "parameters": [
+  "parameters": [
     {
-      "name": "id",
-      "in": "path",
-      "description": "ID of pet to use",
-      "required": true,
-      "schema": {
-        "type": "array",
-        "items": {
-          "type": "string"
+      "name": "id",
+      "in": "path",
+      "description": "ID of pet to use",
+      "required": true,
+      "schema": {
+        "type": "array",
+        "items": {
+          "type": "string"
         }
       },
-      "style": "simple"
+      "style": "simple"
     }
   ]
 }
@@ -957,20 +965,20 @@
   summary: Find pets by ID
   operationId: getPetsById
   responses:
-    '200':
+    '200':
       description: pet response
       content:
-        '*/*' :
+        '*/*' :
           schema:
             type: array
             items:
-              $ref: '#/components/schemas/Pet'
+              $ref: '#/components/schemas/Pet'
     default:
       description: error payload
       content:
-        'text/html':
+        'text/html':
           schema:
-            $ref: '#/components/schemas/ErrorModel'
+            $ref: '#/components/schemas/ErrorModel'
 parameters:
 - name: id
   in: path
@@ -1021,12 +1029,12 @@
 
 
  parameters
-[Parameter Object ¦ Reference Object]
+[Parameter Object | Reference Object]
 A list of parameters that are applicable for this operation. If a parameter is already defined at the Path Item, the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object’s components/parameters.
 
 
  requestBody
-Request Body Object ¦ Reference Object
+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.
 
 
@@ -1036,7 +1044,7 @@
 
 
  callbacks
-Map[string, Callback Object ¦ Reference Object]
+Map[string, Callback Object | Reference Object]
 A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses.
 
 
@@ -1060,63 +1068,63 @@

Operation Object Example


 {
-  "tags": [
-    "pet"
+  "tags": [
+    "pet"
   ],
-  "summary": "Updates a pet in the store with form data",
-  "operationId": "updatePetWithForm",
-  "parameters": [
+  "summary": "Updates a pet in the store with form data",
+  "operationId": "updatePetWithForm",
+  "parameters": [
     {
-      "name": "petId",
-      "in": "path",
-      "description": "ID of pet that needs to be updated",
-      "required": true,
-      "schema": {
-        "type": "string"
+      "name": "petId",
+      "in": "path",
+      "description": "ID of pet that needs to be updated",
+      "required": true,
+      "schema": {
+        "type": "string"
       }
     }
   ],
-  "requestBody": {
-    "content": {
-      "application/x-www-form-urlencoded": {
-        "schema": {
-          "type": "object",
-          "properties": {
-            "name": { 
-              "description": "Updated name of the pet",
-              "type": "string"
+  "requestBody": {
+    "content": {
+      "application/x-www-form-urlencoded": {
+        "schema": {
+          "type": "object",
+          "properties": {
+            "name": { 
+              "description": "Updated name of the pet",
+              "type": "string"
             },
-            "status": {
-              "description": "Updated status of the pet",
-              "type": "string"
+            "status": {
+              "description": "Updated status of the pet",
+              "type": "string"
             }
           },
-          "required": ["status"] 
+          "required": ["status"] 
         }
       }
     }
   },
-  "responses": {
-    "200": {
-      "description": "Pet updated.",
-      "content": {
-        "application/json": {},
-        "application/xml": {}
+  "responses": {
+    "200": {
+      "description": "Pet updated.",
+      "content": {
+        "application/json": {},
+        "application/xml": {}
       }
     },
-    "405": {
-      "description": "Method Not Allowed",
-      "content": {
-        "application/json": {},
-        "application/xml": {}
+    "405": {
+      "description": "Method Not Allowed",
+      "content": {
+        "application/json": {},
+        "application/xml": {}
       }
     }
   },
-  "security": [
+  "security": [
     {
-      "petstore_auth": [
-        "write:pets",
-        "read:pets"
+      "petstore_auth": [
+        "write:pets",
+        "read:pets"
       ]
     }
   ]
@@ -1136,7 +1144,7 @@
     type: string
 requestBody:
   content:
-    'application/x-www-form-urlencoded':
+    'application/x-www-form-urlencoded':
       schema:
        properties:
           name: 
@@ -1148,16 +1156,16 @@
        required:
          - status
 responses:
-  '200':
+  '200':
     description: Pet updated.
     content: 
-      'application/json': {}
-      'application/xml': {}
-  '405':
+      'application/json': {}
+      'application/xml': {}
+  '405':
     description: Method Not Allowed
     content: 
-      'application/json': {}
-      'application/xml': {}
+      'application/json': {}
+      'application/xml': {}
 security:
 - petstore_auth:
   - write:pets
@@ -1191,8 +1199,8 @@

External Documentation Object Example


 {
-  "description": "Find more info here",
-  "url": "https://example.com"
+  "description": "Find more info here",
+  "url": "https://example.com"
 }
 

@@ -1280,7 +1288,7 @@
 
 
  schema
-Schema Object ¦ Reference Object
+Schema Object | Reference Object
 The schema defining the type used for the parameter.
 
 
@@ -1290,7 +1298,7 @@
 
 
  examples
-Map[ string, Example Object ¦ Reference Object]
+Map[ string, Example Object | Reference Object]
 Examples of the parameter’s potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The examples field is mutually exclusive of the example field. Furthermore, if referencing a schema that contains an example, the examples value SHALL override the example provided by the schema.
 
 
@@ -1467,8 +1475,8 @@
 false
 n/a
 n/a
-blue¦black¦brown
-R¦100¦G¦200¦B¦150
+blue|black|brown
+R|100|G|200|B|150
 
 
 deepObject
@@ -1476,7 +1484,7 @@
 n/a
 n/a
 n/a
-color\R=100&color\G=200&color\B=150
+color[R]=100&color[G]=200&color[B]=150
 
 
 
@@ -1485,18 +1493,18 @@
 
A header parameter with an array of 64 bit integer numbers:

 

 {
-  "name": "token",
-  "in": "header",
-  "description": "token to be passed as a header",
-  "required": true,
-  "schema": {
-    "type": "array",
-    "items": {
-      "type": "integer",
-      "format": "int64"
+  "name": "token",
+  "in": "header",
+  "description": "token to be passed as a header",
+  "required": true,
+  "schema": {
+    "type": "array",
+    "items": {
+      "type": "integer",
+      "format": "int64"
     }
   },
-  "style": "simple"
+  "style": "simple"
 }
 

 

@@ -1514,12 +1522,12 @@
 
A path parameter of a string value:

 

 {
-  "name": "username",
-  "in": "path",
-  "description": "username to fetch",
-  "required": true,
-  "schema": {
-    "type": "string"
+  "name": "username",
+  "in": "path",
+  "description": "username to fetch",
+  "required": true,
+  "schema": {
+    "type": "string"
   }
 }
 

@@ -1534,18 +1542,18 @@
 
An optional query parameter of a string value, allowing multiple values by repeating the query parameter:

 

 {
-  "name": "id",
-  "in": "query",
-  "description": "ID of the object to fetch",
-  "required": false,
-  "schema": {
-    "type": "array",
-    "items": {
-      "type": "string"
+  "name": "id",
+  "in": "query",
+  "description": "ID of the object to fetch",
+  "required": false,
+  "schema": {
+    "type": "array",
+    "items": {
+      "type": "string"
     }
   },
-  "style": "form",
-  "explode": true
+  "style": "form",
+  "explode": true
 }
 

 

@@ -1563,15 +1571,15 @@
 
A free-form query parameter, allowing undefined parameters of a specific type:

 

 {
-  "in": "query",
-  "name": "freeForm",
-  "schema": {
-    "type": "object",
-    "additionalProperties": {
-      "type": "integer"
+  "in": "query",
+  "name": "freeForm",
+  "schema": {
+    "type": "object",
+    "additionalProperties": {
+      "type": "integer"
     },
   },
-  "style": "form"
+  "style": "form"
 }
 

 

@@ -1586,22 +1594,22 @@
 
A complex parameter using content to define serialization:

 

 {
-  "in": "query",
-  "name": "coordinates",
-  "content": {
-    "application/json": {
-      "schema": {
-        "type": "object",
-        "required": [
-          "lat",
-          "long"
+  "in": "query",
+  "name": "coordinates",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "object",
+        "required": [
+          "lat",
+          "long"
         ],
-        "properties": {
-          "lat": {
-            "type": "number"
+        "properties": {
+          "lat": {
+            "type": "number"
           },
-          "long": {
-            "type": "number"
+          "long": {
+            "type": "number"
           }
         }
       }
@@ -1659,43 +1667,43 @@
 
A request body with a referenced model definition.

 

 {
-  "description": "user to add to the system",
-  "content": {
-    "application/json": {
-      "schema": {
-        "$ref": "#/components/schemas/User"
+  "description": "user to add to the system",
+  "content": {
+    "application/json": {
+      "schema": {
+        "$ref": "#/components/schemas/User"
       },
-      "examples": {
-          "user" : {
-            "summary": "User Example", 
-            "externalValue": "http://foo.bar/examples/user-example.json"
+      "examples": {
+          "user" : {
+            "summary": "User Example", 
+            "externalValue": "http://foo.bar/examples/user-example.json"
           } 
         }
     },
-    "application/xml": {
-      "schema": {
-        "$ref": "#/components/schemas/User"
+    "application/xml": {
+      "schema": {
+        "$ref": "#/components/schemas/User"
       },
-      "examples": {
-          "user" : {
-            "summary": "User example in XML",
-            "externalValue": "http://foo.bar/examples/user-example.xml"
+      "examples": {
+          "user" : {
+            "summary": "User example in XML",
+            "externalValue": "http://foo.bar/examples/user-example.xml"
           }
         }
     },
-    "text/plain": {
-      "examples": {
-        "user" : {
-            "summary": "User example in Plain text",
-            "externalValue": "http://foo.bar/examples/user-example.txt" 
+    "text/plain": {
+      "examples": {
+        "user" : {
+            "summary": "User example in Plain text",
+            "externalValue": "http://foo.bar/examples/user-example.txt" 
         }
       } 
     },
-    "*/*": {
-      "examples": {
-        "user" : {
-            "summary": "User example in other format",
-            "externalValue": "http://foo.bar/examples/user-example.whatever"
+    "*/*": {
+      "examples": {
+        "user" : {
+            "summary": "User example in other format",
+            "externalValue": "http://foo.bar/examples/user-example.whatever"
         }
       }
     }
@@ -1705,41 +1713,41 @@
 

 description: user to add to the system
 content: 
-  'application/json':
+  'application/json':
     schema:
-      $ref: '#/components/schemas/User'
+      $ref: '#/components/schemas/User'
     examples:
       user:
         summary: User Example
-        externalValue: 'http://foo.bar/examples/user-example.json'
-  'application/xml':
+        externalValue: 'http://foo.bar/examples/user-example.json'
+  'application/xml':
     schema:
-      $ref: '#/components/schemas/User'
+      $ref: '#/components/schemas/User'
     examples:
       user:
         summary: User Example in XML
-        externalValue: 'http://foo.bar/examples/user-example.xml'
-  'text/plain':
+        externalValue: 'http://foo.bar/examples/user-example.xml'
+  'text/plain':
     examples:
       user:
         summary: User example in text plain format
-        externalValue: 'http://foo.bar/examples/user-example.txt'
-  '*/*':
+        externalValue: 'http://foo.bar/examples/user-example.txt'
+  '*/*':
     examples:
       user: 
         summary: User example in other format
-        externalValue: 'http://foo.bar/examples/user-example.whatever'
+        externalValue: 'http://foo.bar/examples/user-example.whatever'
 

 
A body parameter that is an array of string values:

 

 {
-  "description": "user to add to the system",
-  "content": {
-    "text/plain": {
-      "schema": {
-        "type": "array",
-        "items": {
-          "type": "string"
+  "description": "user to add to the system",
+  "content": {
+    "text/plain": {
+      "schema": {
+        "type": "array",
+        "items": {
+          "type": "string"
         }
       }
     }
@@ -1770,7 +1778,7 @@
 
 
  schema
-Schema Object ¦ Reference Object
+Schema Object | Reference Object
 The schema defining the content of the request, response, or parameter.
 
 
@@ -1780,7 +1788,7 @@
 
 
  examples
-Map[ string, Example Object ¦ Reference Object]
+Map[ string, Example Object | Reference Object]
 Examples of the media type.  Each example object SHOULD  match the media type and specified schema if present.  The examples field is mutually exclusive of the example field.  Furthermore, if referencing a schema which contains an example, the examples value SHALL override the example provided by the schema.
 
 
@@ -1794,33 +1802,33 @@

Media Type Examples


 {
-  "application/json": {
-    "schema": {
-         "$ref": "#/components/schemas/Pet"
+  "application/json": {
+    "schema": {
+         "$ref": "#/components/schemas/Pet"
     },
-    "examples": {
-      "cat" : {
-        "summary": "An example of a cat",
-        "value": 
+    "examples": {
+      "cat" : {
+        "summary": "An example of a cat",
+        "value": 
           {
-            "name": "Fluffy",
-            "petType": "Cat",
-            "color": "White",
-            "gender": "male",
-            "breed": "Persian"
+            "name": "Fluffy",
+            "petType": "Cat",
+            "color": "White",
+            "gender": "male",
+            "breed": "Persian"
           }
       },
-      "dog": {
-        "summary": "An example of a dog with a cat's name",
-        "value" :  { 
-          "name": "Puma",
-          "petType": "Dog",
-          "color": "Black",
-          "gender": "Female",
-          "breed": "Mixed"
+      "dog": {
+        "summary": "An example of a dog with a cat's name",
+        "value" :  { 
+          "name": "Puma",
+          "petType": "Dog",
+          "color": "Black",
+          "gender": "Female",
+          "breed": "Mixed"
         },
-      "frog": {
-          "$ref": "#/components/examples/frog-example"
+      "frog": {
+          "$ref": "#/components/examples/frog-example"
         }
       }
     }
@@ -1830,7 +1838,7 @@
 

 application/json: 
   schema:
-    $ref: "#/components/schemas/Pet"
+    $ref: "#/components/schemas/Pet"
   examples:
     cat:
       summary: An example of a cat
@@ -1841,7 +1849,7 @@
         gender: male
         breed: Persian
     dog:
-      summary: An example of a dog with a cat's name
+      summary: An example of a dog with a cat's name
       value:
         name: Puma
         petType: Dog
@@ -1849,7 +1857,7 @@
         gender: Female
         breed: Mixed
     frog:
-      $ref: "#/components/examples/frog-example"
+      $ref: "#/components/examples/frog-example"

Considerations for File Uploads

In contrast with the 2.0 specification, file input/output content in OpenAPI is described with the same semantics as any other schema type. Specifically:

@@ -1882,11 +1890,11 @@ requestBody: content: # a binary file of type png or jpeg - 'image/jpeg': + 'image/jpeg': schema: type: string format: binary - 'image/png': + 'image/png': schema: type: string format: binary @@ -1898,7 +1906,7 @@ multipart/form-data: schema: properties: - # The property name 'file' will be used for all files. + # The property name 'file' will be used for all files. file: type: array items: @@ -1922,10 +1930,10 @@ address: # complex types are stringified to support RFC 1866 type: object - properties: {} + properties: {}

In this example, the contents in the requestBody MUST be stringified per [[!RFC1866]] when passed to the server. In addition, the address field complex object will be stringified.

-

When passing complex objects in the application/x-www-form-urlencoded content type, the default serialization strategy of such properties is described in the Encoding Object's style property as form.

+

When passing complex objects in the application/x-www-form-urlencoded content type, the default serialization strategy of such properties is described in the Encoding Object’s style property as form.

Special Considerations for multipart Content

It is common to use multipart/form-data as a Content-Type when transferring request bodies to operations. In contrast to 2.0, a schema is REQUIRED to define the input parameters to the operation when using multipart content. This supports complex structures as well as supporting mechanisms for multiple file uploads.

When passing in multipart types, boundaries MAY be used to separate sections of the content being transferred — thus, the following default Content-Types are defined for multipart:

@@ -1948,7 +1956,7 @@ address: # default Content-Type for objects is `application/json` type: object - properties: {} + properties: {} profileImage: # default Content-Type for string/binary is `application/octet-stream` type: string @@ -1962,7 +1970,7 @@ # default Content-Type for arrays is based on the `inner` type (object shown, so `application/json` in this example) type: array items: - type: '#/components/schemas/Address' + type: '#/components/schemas/Address'

An encoding attribute is introduced to give you control over the serialization of parts of multipart request bodies. This attribute is only applicable to multipart and application/x-www-form-urlencoded request bodies.

Encoding Object

@@ -1984,7 +1992,7 @@ headers -Map[string, Header Object ¦ Reference Object] +Map[string, Header Object | Reference Object] A map allowing additional information to be provided as headers, for example Content-Disposition. Content-Type is described separately and SHALL be ignored in this section. This property SHALL be ignored if the request body media type is not a multipart. @@ -2020,12 +2028,12 @@ address: # default is application/json type: object - properties: {} + properties: {} historyMetadata: # need to declare XML format! description: metadata in XML format type: object - properties: {} + properties: {} profileImage: # default is application/octet-stream, need to declare an image type only! type: string @@ -2064,7 +2072,7 @@ default -Response Object ¦ Reference Object +Response Object | Reference Object The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses. A Reference Object can link to a response that the OpenAPI Object’s components/responses section defines. @@ -2081,7 +2089,7 @@ HTTP Status Code -Response Object ¦ Reference Object +Response Object | Reference Object Any HTTP status code can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. A Reference Object can link to a response that is defined in the OpenAPI Object’s components/responses section. This field MUST be enclosed in quotation marks (for example, “200”) for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character X. For example, 2XX represents all response codes between [200-299]. Only the following range definitions are allowed: 1XX, 2XX, 3XX, 4XX, and 5XX. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code. @@ -2091,22 +2099,22 @@

A 200 response for a successful operation and a default response for others (implying an error):


 {
-  "200": {
-    "description": "a pet to be returned",
-    "content": {
-      "application/json": {
-        "schema": {
-          "$ref": "#/components/schemas/Pet"
+  "200": {
+    "description": "a pet to be returned",
+    "content": {
+      "application/json": {
+        "schema": {
+          "$ref": "#/components/schemas/Pet"
         }
       }
     }
   },
-  "default": {
-    "description": "Unexpected error",
-    "content": {
-      "application/json": {
-        "schema": {
-          "$ref": "#/components/schemas/ErrorModel"
+  "default": {
+    "description": "Unexpected error",
+    "content": {
+      "application/json": {
+        "schema": {
+          "$ref": "#/components/schemas/ErrorModel"
         }
       }
     }
@@ -2114,18 +2122,18 @@
 }
 

-'200':
+'200':
   description: a pet to be returned
   content: 
     application/json:
       schema:
-        $ref: '#/components/schemas/Pet'
+        $ref: '#/components/schemas/Pet'
 default:
   description: Unexpected error
   content:
     application/json:
       schema:
-        $ref: '#/components/schemas/ErrorModel'
+        $ref: '#/components/schemas/ErrorModel'

Response Object

Describes a single response from an API Operation, including design-time, static @@ -2147,7 +2155,7 @@ headers -Map[string, Header Object ¦ Reference Object] +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. @@ -2157,7 +2165,7 @@ links -Map[string, Link Object ¦ Reference Object] +Map[string, Link Object | Reference Object] A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for Component Objects. @@ -2167,13 +2175,13 @@

Response of an array of a complex type:


 {
-  "description": "A complex object array response",
-  "content": {
-    "application/json": {
-      "schema": {
-        "type": "array",
-        "items": {
-          "$ref": "#/components/schemas/VeryComplexType"
+  "description": "A complex object array response",
+  "content": {
+    "application/json": {
+      "schema": {
+        "type": "array",
+        "items": {
+          "$ref": "#/components/schemas/VeryComplexType"
         }
       }
     }
@@ -2187,16 +2195,16 @@
     schema: 
       type: array
       items:
-        $ref: '#/components/schemas/VeryComplexType'
+        $ref: '#/components/schemas/VeryComplexType'

Response with a string type:


 {
-  "description": "A simple string response",
-  "content": {
-    "text/plain": {
-      "schema": {
-        "type": "string"
+  "description": "A simple string response",
+  "content": {
+    "text/plain": {
+      "schema": {
+        "type": "string"
       }
     }
   }
@@ -2213,32 +2221,32 @@
 
Plain text response with headers:

 

 {
-  "description": "A simple string response",
-  "content": {
-    "text/plain": {
-      "schema": {
-        "type": "string",
-        "example": "whoa!"
+  "description": "A simple string response",
+  "content": {
+    "text/plain": {
+      "schema": {
+        "type": "string",
+        "example": "whoa!"
       }
     }
   },
-  "headers": {
-    "X-Rate-Limit-Limit": {
-      "description": "The number of allowed requests in the current period",
-      "schema": {
-        "type": "integer"
+  "headers": {
+    "X-Rate-Limit-Limit": {
+      "description": "The number of allowed requests in the current period",
+      "schema": {
+        "type": "integer"
       }
     },
-    "X-Rate-Limit-Remaining": {
-      "description": "The number of remaining requests in the current period",
-      "schema": {
-        "type": "integer"
+    "X-Rate-Limit-Remaining": {
+      "description": "The number of remaining requests in the current period",
+      "schema": {
+        "type": "integer"
       }
     },
-    "X-Rate-Limit-Reset": {
-      "description": "The number of seconds left in the current period",
-      "schema": {
-        "type": "integer"
+    "X-Rate-Limit-Reset": {
+      "description": "The number of seconds left in the current period",
+      "schema": {
+        "type": "integer"
       }
     }
   }
@@ -2250,7 +2258,7 @@
   text/plain:
     schema:
       type: string
-    example: 'whoa!'
+    example: 'whoa!'
 headers:
   X-Rate-Limit-Limit:
     description: The number of allowed requests in the current period
@@ -2268,7 +2276,7 @@
 
Response with no return value:

 

 {
-  "description": "object created"
+  "description": "object created"
 }
 

 

@@ -2303,22 +2311,22 @@
 This includes accessing any part of a body that a JSON Pointer [[!RFC6901]] can reference.

 
For example, given the following HTTP request:

 

-POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1
-Host: example.org
-Content-Type: application/json
-Content-Length: 187
+POST /subscribe/myevent?queryUrl=http://clientdomain.com/stillrunning HTTP/1.1
+Host: example.org
+Content-Type: application/json
+Content-Length: 187
 
-{
-  "failedUrl" : "http://clientdomain.com/failed",
-  "successUrls" : [
-    "http://clientdomain.com/fast",
-    "http://clientdomain.com/medium",
-    "http://clientdomain.com/slow"
+{
+  "failedUrl" : "http://clientdomain.com/failed",
+  "successUrls" : [
+    "http://clientdomain.com/fast",
+    "http://clientdomain.com/medium",
+    "http://clientdomain.com/slow"
   ] 
 }
 
 201 Created
-Location: http://example.org/subscription/1
+Location: http://example.org/subscription/1
 

 
The following examples show how the various expressions evaluate, assuming the callback operation has a path parameter named eventType and a query parameter named queryUrl.

 
@@ -2367,31 +2375,31 @@
 
The following example uses the user provided queryUrl query string parameter to define the callback URL.  This is an example of how to use a callback object to describe a WebHook callback that goes with the subscription operation to enable registering for the WebHook.

 myCallback:
-  '{$request.query.queryUrl}':
+  '{$request.query.queryUrl}':
     post:
       requestBody:
         description: Callback payload
         content: 
-          'application/json':
+          'application/json':
             schema:
-              $ref: '#/components/schemas/SomePayload'
+              $ref: '#/components/schemas/SomePayload'
       responses:
-        '200':
+        '200':
           description: callback successfully processed
 
The following example shows a callback where the server is hard-coded, but the query string parameters are populated from the id and email property in the request body.

 transactionCallback:
-  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
+  'http://notificationServer.com?transactionId={$request.body#/id}&email={$request.body#/email}':
     post:
       requestBody:
         description: Callback payload
         content: 
-          'application/json':
+          'application/json':
             schema:
-              $ref: '#/components/schemas/SomePayload'
+              $ref: '#/components/schemas/SomePayload'
       responses:
-        '200':
+        '200':
           description: callback successfully processed
 
Example Object

@@ -2436,51 +2444,51 @@
 

 requestBody:
   content:
-    'application/json':
+    'application/json':
       schema:
-        $ref: '#/components/schemas/Address'
+        $ref: '#/components/schemas/Address'
       examples: 
         foo:
           summary: A foo example
-          value: {"foo": "bar"}
+          value: {"foo": "bar"}
         bar:
           summary: A bar example
-          value: {"bar": "baz"}
-    'application/xml':
+          value: {"bar": "baz"}
+    'application/xml':
       examples: 
         xmlExample:
           summary: This is an example in XML
-          externalValue: 'http://example.org/examples/address-example.xml'
-    'text/plain':
+          externalValue: 'http://example.org/examples/address-example.xml'
+    'text/plain':
       examples:
         textExample: 
           summary: This is a text example
-          externalValue: 'http://foo.bar/examples/address-example.txt'
+          externalValue: 'http://foo.bar/examples/address-example.txt'
 

 
In a parameter:

 

 parameters:
-  - name: 'zipCode'
-    in: 'query'
+  - name: 'zipCode'
+    in: 'query'
     schema:
-      type: 'string'
-      format: 'zip-code'
+      type: 'string'
+      format: 'zip-code'
     examples:
       zip-example: 
-        $ref: '#/components/examples/zip-example'
+        $ref: '#/components/examples/zip-example'
 

 
In a response:

 

 responses:
-  '200':
+  '200':
     description: your car appointment has been booked
     content: 
       application/json:
         schema:
-          $ref: '#/components/schemas/SuccessResponse'
+          $ref: '#/components/schemas/SuccessResponse'
         examples:
           confirmation-success:
-            $ref: '#/components/examples/confirmation-success'
+            $ref: '#/components/examples/confirmation-success'
 

 
Link Object

 
The Link object represents a possible design-time link for a response.
@@ -2509,12 +2517,12 @@
 
 

-
+
-
+
@@ -2548,7 +2556,7 @@
         type:stringget:responses:
-        '200':
+        '200':description:theuserbeingreturnedcontent:application/json:
@@ -2578,8 +2586,8 @@
     get:operationId:getUserAddressresponses:
-        '200':
-          description:theuser'saddress
+        '200':
+          description:theuser'saddress
When a runtime expression fails to evaluate, no parameter value is passed to the target operation.
Values from the response body can be used to drive a linked operation.

@@ -2600,8 +2608,8 @@
 

 links:
   UserRepositories:
-    # returns array of '#/components/schemas/repository'
-    operationRef: '#/paths/~12.0~1repositories~1{username}/get'
+    # returns array of '#/components/schemas/repository'
+    operationRef: '#/paths/~12.0~1repositories~1{username}/get'
     parameters:
       username: $response.body#/username
 

@@ -2609,8 +2617,8 @@
 

 links:
   UserRepositories:
-    # returns array of '#/components/schemas/repository'
-    operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get'
+    # returns array of '#/components/schemas/repository'
+    operationRef: 'https://na2.gigantic-server.com/#/paths/~12.0~1repositories~1{username}/get'
     parameters:
       username: $response.body#/username
 

@@ -2621,22 +2629,22 @@
 This mechanism is used by Link Objects and Callback Objects.
The runtime expression is defined by the following [ABNF] syntax

-      expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
+      expression = ( "$url" / "$method" / "$statusCode" / "$request." source / "$response." source )
       source = ( header-reference / query-reference / path-reference / body-reference )
-      header-reference = "header." token
-      query-reference = "query." name  
-      path-reference = "path." name
-      body-reference = "body" ["#" json-pointer ]
-      json-pointer    = *( "/" reference-token )
+      header-reference = "header." token
+      query-reference = "query." name  
+      path-reference = "path." name
+      body-reference = "body" ["#" json-pointer ]
+      json-pointer    = *( "/" reference-token )
       reference-token = *( unescaped / escaped )
       unescaped       = %x00-2E / %x30-7D / %x7F-10FFFF
-         ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
-      escaped         = "~" ( "0" / "1" )
-        ; representing '~' and '/', respectively
+         ; %x2F ('/') and %x7E ('~') are excluded from 'unescaped'
+      escaped         = "~" ( "0" / "1" )
+        ; representing '~' and '/', respectively
       name = *( CHAR )
       token = 1*tchar
-      tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
-        "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
+      tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
+        "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
 
Here, json-pointer is taken from [[!RFC6901]], char from [[!RFC7159]] and token from [[!RFC7230]].
The name identifier is case-sensitive, whereas token is not.

@@ -2701,9 +2709,9 @@
 
A simple header of type integer:

 {
-  "description": "The number of allowed requests in the current period",
-  "schema": {
-    "type": "integer"
+  "description": "The number of allowed requests in the current period",
+  "schema": {
+    "type": "integer"
   }
 }
 

@@ -2746,8 +2754,8 @@
 
Tag Object Example

 

 {
-	"name": "pet",
-	"description": "Pets operations"
+	"name": "pet",
+	"description": "Pets operations"
 }
 

 

@@ -2779,16 +2787,16 @@
 
Reference Object Example

 

 {
-	"$ref": "#/components/schemas/Pet"
+	"$ref": "#/components/schemas/Pet"
 }
 

 

-$ref: '#/components/schemas/Pet'
+$ref: '#/components/schemas/Pet'
 

 
Relative Schema Document Example

 

 {
-  "$ref": "Pet.json"
+  "$ref": "Pet.json"
 }
 

 

@@ -2797,7 +2805,7 @@
 
Relative Documents With Embedded Schema Example

 

 {
-  "$ref": "definitions.json#/Pet"
+  "$ref": "definitions.json#/Pet"
 }
 

 

@@ -2919,8 +2927,8 @@
 
Primitive Sample

 

 {
-  "type": "string",
-  "format": "email"
+  "type": "string",
+  "format": "email"
 }
 

 

@@ -2930,21 +2938,21 @@
 
Simple Model

 

 {
-  "type": "object",
-  "required": [
-    "name"
+  "type": "object",
+  "required": [
+    "name"
   ],
-  "properties": {
-    "name": {
-      "type": "string"
+  "properties": {
+    "name": {
+      "type": "string"
     },
-    "address": {
-      "$ref": "#/components/schemas/Address"
+    "address": {
+      "$ref": "#/components/schemas/Address"
     },
-    "age": {
-      "type": "integer",
-      "format": "int32",
-      "minimum": 0
+    "age": {
+      "type": "integer",
+      "format": "int32",
+      "minimum": 0
     }
   }
 }
@@ -2957,7 +2965,7 @@
   name:
     type: string
   address:
-    $ref: '#/components/schemas/Address'
+    $ref: '#/components/schemas/Address'
   age:
     type: integer
     format: int32
@@ -2967,9 +2975,9 @@
 
For a simple string to string mapping:

 

 {
-  "type": "object",
-  "additionalProperties": {
-    "type": "string"
+  "type": "object",
+  "additionalProperties": {
+    "type": "string"
   }
 }
 

@@ -2981,36 +2989,36 @@
 
For a string to model mapping:

 

 {
-  "type": "object",
-  "additionalProperties": {
-    "$ref": "#/components/schemas/ComplexModel"
+  "type": "object",
+  "additionalProperties": {
+    "$ref": "#/components/schemas/ComplexModel"
   }
 }
 

 

 type: object
 additionalProperties:
-  $ref: '#/components/schemas/ComplexModel'
+  $ref: '#/components/schemas/ComplexModel'
 

 
Model with Example

 

 {
-  "type": "object",
-  "properties": {
-    "id": {
-      "type": "integer",
-      "format": "int64"
+  "type": "object",
+  "properties": {
+    "id": {
+      "type": "integer",
+      "format": "int64"
     },
-    "name": {
-      "type": "string"
+    "name": {
+      "type": "string"
     }
   },
-  "required": [
-    "name"
+  "required": [
+    "name"
   ],
-  "example": {
-    "name": "Puma",
-    "id": 1
+  "example": {
+    "name": "Puma",
+    "id": 1
   }
 }
 

@@ -3031,38 +3039,38 @@
 
Models with Composition

 

 {
-  "components": {
-    "schemas": {
-      "ErrorModel": {
-        "type": "object",
-        "required": [
-          "message",
-          "code"
+  "components": {
+    "schemas": {
+      "ErrorModel": {
+        "type": "object",
+        "required": [
+          "message",
+          "code"
         ],
-        "properties": {
-          "message": {
-            "type": "string"
+        "properties": {
+          "message": {
+            "type": "string"
           },
-          "code": {
-            "type": "integer",
-            "minimum": 100,
-            "maximum": 600
+          "code": {
+            "type": "integer",
+            "minimum": 100,
+            "maximum": 600
           }
         }
       },
-      "ExtendedErrorModel": {
-        "allOf": [
+      "ExtendedErrorModel": {
+        "allOf": [
           {
-            "$ref": "#/components/schemas/ErrorModel"
+            "$ref": "#/components/schemas/ErrorModel"
           },
           {
-            "type": "object",
-            "required": [
-              "rootCause"
+            "type": "object",
+            "required": [
+              "rootCause"
             ],
-            "properties": {
-              "rootCause": {
-                "type": "string"
+            "properties": {
+              "rootCause": {
+                "type": "string"
               }
             }
           }
@@ -3089,7 +3097,7 @@
           maximum: 600
     ExtendedErrorModel:
       allOf:
-      - $ref: '#/components/schemas/ErrorModel'
+      - $ref: '#/components/schemas/ErrorModel'
       - type: object
         required:
         - rootCause
@@ -3100,72 +3108,72 @@
 
Models with Polymorphism Support

 

 {
-  "components": {
-    "schemas": {
-      "Pet": {
-        "type": "object",
-        "discriminator": {
-          "propertyName": "petType"
+  "components": {
+    "schemas": {
+      "Pet": {
+        "type": "object",
+        "discriminator": {
+          "propertyName": "petType"
         },
-        "properties": {
-          "name": {
-            "type": "string"
+        "properties": {
+          "name": {
+            "type": "string"
           },
-          "petType": {
-            "type": "string"
+          "petType": {
+            "type": "string"
           }
         },
-        "required": [
-          "name",
-          "petType"
+        "required": [
+          "name",
+          "petType"
         ]
       },
-      "Cat": {
-        "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
-        "allOf": [
+      "Cat": {
+        "description": "A representation of a cat. Note that `Cat` will be used as the discriminator value.",
+        "allOf": [
           {
-            "$ref": "#/components/schemas/Pet"
+            "$ref": "#/components/schemas/Pet"
           },
           {
-            "type": "object",
-            "properties": {
-              "huntingSkill": {
-                "type": "string",
-                "description": "The measured skill for hunting",
-                "default": "lazy",
-                "enum": [
-                  "clueless",
-                  "lazy",
-                  "adventurous",
-                  "aggressive"
+            "type": "object",
+            "properties": {
+              "huntingSkill": {
+                "type": "string",
+                "description": "The measured skill for hunting",
+                "default": "lazy",
+                "enum": [
+                  "clueless",
+                  "lazy",
+                  "adventurous",
+                  "aggressive"
                 ]
               }
             },
-            "required": [
-              "huntingSkill"
+            "required": [
+              "huntingSkill"
             ]
           }
         ]
       },
-      "Dog": {
-        "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.",
-        "allOf": [
+      "Dog": {
+        "description": "A representation of a dog. Note that `Dog` will be used as the discriminator value.",
+        "allOf": [
           {
-            "$ref": "#/components/schemas/Pet"
+            "$ref": "#/components/schemas/Pet"
           },
           {
-            "type": "object",
-            "properties": {
-              "packSize": {
-                "type": "integer",
-                "format": "int32",
-                "description": "the size of the pack the dog is from",
-                "default": 0,
-                "minimum": 0
+            "type": "object",
+            "properties": {
+              "packSize": {
+                "type": "integer",
+                "format": "int32",
+                "description": "the size of the pack the dog is from",
+                "default": 0,
+                "minimum": 0
               }
             },
-            "required": [
-              "packSize"
+            "required": [
+              "packSize"
             ]
           }
         ]
@@ -3189,10 +3197,10 @@
       required:
       - name
       - petType
-    Cat:  ## "Cat" will be used as the discriminator value
+    Cat:  ## "Cat" will be used as the discriminator value
       description: A representation of a cat
       allOf:
-      - $ref: '#/components/schemas/Pet'
+      - $ref: '#/components/schemas/Pet'
       - type: object
         properties:
           huntingSkill:
@@ -3205,10 +3213,10 @@
             - aggressive
         required:
         - huntingSkill
-    Dog:  ## "Dog" will be used as the discriminator value
+    Dog:  ## "Dog" will be used as the discriminator value
       description: A representation of a dog
       allOf:
-      - $ref: '#/components/schemas/Pet'
+      - $ref: '#/components/schemas/Pet'
       - type: object
         properties:
           packSize:
@@ -3250,25 +3258,25 @@
 

 MyResponseType:
   oneOf:
-  - $ref: '#/components/schemas/Cat'
-  - $ref: '#/components/schemas/Dog'
-  - $ref: '#/components/schemas/Lizard'
+  - $ref: '#/components/schemas/Cat'
+  - $ref: '#/components/schemas/Dog'
+  - $ref: '#/components/schemas/Lizard'
 

 
which means the payload MUST, by validation, match exactly one of the schemas described by Cat, Dog, or Lizard.  In this case, a discriminator MAY act as a “hint” to shortcut validation and selection of the matching schema which may be a costly operation, depending on the complexity of the schema. We can then describe exactly which field tells us which schema to use:

 

 MyResponseType:
   oneOf:
-  - $ref: '#/components/schemas/Cat'
-  - $ref: '#/components/schemas/Dog'
-  - $ref: '#/components/schemas/Lizard'
+  - $ref: '#/components/schemas/Cat'
+  - $ref: '#/components/schemas/Dog'
+  - $ref: '#/components/schemas/Lizard'
   discriminator:
     propertyName: petType
 

 
The expectation now is that a property with name petType MUST be present in the response payload, and the value will correspond to the name of a schema defined in the OAS document.  Thus the response payload:

 

 {
-  "id": 12345,
-  "petType": "Cat"
+  "id": 12345,
+  "petType": "Cat"
 }
 

 
Will indicate that the Cat schema be used in conjunction with this payload.

@@ -3276,15 +3284,15 @@
 

 MyResponseType:
   oneOf:
-  - $ref: '#/components/schemas/Cat'
-  - $ref: '#/components/schemas/Dog'
-  - $ref: '#/components/schemas/Lizard'
-  - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json'
+  - $ref: '#/components/schemas/Cat'
+  - $ref: '#/components/schemas/Dog'
+  - $ref: '#/components/schemas/Lizard'
+  - $ref: 'https://gigantic-server.com/schemas/Monster/schema.json'
   discriminator:
     propertyName: petType
     mapping:
-      dog: '#/components/schemas/Dog'
-      monster: 'https://gigantic-server.com/schemas/Monster/schema.json'
+      dog: '#/components/schemas/Dog'
+      monster: 'https://gigantic-server.com/schemas/Monster/schema.json'
 

 
Here the discriminator value of dog will map to the schema #/components/schemas/Dog, rather than the default (implicit) value of Dog.  If the discriminator value does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail. Mapping keys MUST be string values, but tooling MAY convert response values to strings for comparison.

 
When used in conjunction with the anyOf construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload.

@@ -3306,7 +3314,7 @@
           dog: Dog
     Cat:
       allOf:
-      - $ref: '#/components/schemas/Pet'
+      - $ref: '#/components/schemas/Pet'
       - type: object
         # all other properties specific to a `Cat`
         properties:
@@ -3314,7 +3322,7 @@
             type: string
     Dog:
       allOf:
-      - $ref: '#/components/schemas/Pet'
+      - $ref: '#/components/schemas/Pet'
       - type: object
         # all other properties specific to a `Dog`
         properties:
@@ -3322,7 +3330,7 @@
             type: string
     Lizard:
       allOf:
-      - $ref: '#/components/schemas/Pet'
+      - $ref: '#/components/schemas/Pet'
       - type: object
         # all other properties specific to a `Lizard`
         properties:
@@ -3332,15 +3340,15 @@
 
a payload like this:

 

 {
-  "petType": "Cat",
-  "name": "misty"
+  "petType": "Cat",
+  "name": "misty"
 }
 

 
will indicate that the Cat schema be used.  Likewise this schema:

 

 {
-  "petType": "dog",
-  "bark": "soft"
+  "petType": "dog",
+  "bark": "soft"
 }
 

 
will map to Dog because of the definition in the mappings element.

@@ -3392,8 +3400,8 @@
 
Basic string property:

 

 {
-    "animals": {
-        "type": "string"
+    "animals": {
+        "type": "string"
     }
 }
 

@@ -3407,10 +3415,10 @@
 
Basic string array property (wrapped is false by default):

 

 {
-    "animals": {
-        "type": "array",
-        "items": {
-            "type": "string"
+    "animals": {
+        "type": "array",
+        "items": {
+            "type": "string"
         }
     }
 }
@@ -3429,10 +3437,10 @@
 
XML Name Replacement

 

 {
-  "animals": {
-    "type": "string",
-    "xml": {
-      "name": "animal"
+  "animals": {
+    "type": "string",
+    "xml": {
+      "name": "animal"
     }
   }
 }
@@ -3450,21 +3458,21 @@
 
In this example, a full model definition is shown.

 

 {
-  "Person": {
-    "type": "object",
-    "properties": {
-      "id": {
-        "type": "integer",
-        "format": "int32",
-        "xml": {
-          "attribute": true
+  "Person": {
+    "type": "object",
+    "properties": {
+      "id": {
+        "type": "integer",
+        "format": "int32",
+        "xml": {
+          "attribute": true
         }
       },
-      "name": {
-        "type": "string",
-        "xml": {
-          "namespace": "http://example.com/schema/sample",
-          "prefix": "sample"
+      "name": {
+        "type": "string",
+        "xml": {
+          "namespace": "http://example.com/schema/sample",
+          "prefix": "sample"
         }
       }
     }
@@ -3487,20 +3495,20 @@
         prefix: sample
 

 

-<Person id="123">
-    <sample:name xmlns:sample="http://example.com/schema/sample">example</sample:name>
+<Person id="123">
+    <sample:name xmlns:sample="http://example.com/schema/sample">example</sample:name>
 </Person>
 

 
XML Arrays

 
Changing the element names:

 

 {
-  "animals": {
-    "type": "array",
-    "items": {
-      "type": "string",
-      "xml": {
-        "name": "animal"
+  "animals": {
+    "type": "array",
+    "items": {
+      "type": "string",
+      "xml": {
+        "name": "animal"
       }
     }
   }
@@ -3521,16 +3529,16 @@
 
The external name property has no effect on the XML:

 

 {
-  "animals": {
-    "type": "array",
-    "items": {
-      "type": "string",
-      "xml": {
-        "name": "animal"
+  "animals": {
+    "type": "array",
+    "items": {
+      "type": "string",
+      "xml": {
+        "name": "animal"
       }
     },
-    "xml": {
-      "name": "aliens"
+    "xml": {
+      "name": "aliens"
     }
   }
 }
@@ -3552,13 +3560,13 @@
 
Even when the array is wrapped, if a name is not explicitly defined, the same name will be used both internally and externally:

 

 {
-  "animals": {
-    "type": "array",
-    "items": {
-      "type": "string"
+  "animals": {
+    "type": "array",
+    "items": {
+      "type": "string"
     },
-    "xml": {
-      "wrapped": true
+    "xml": {
+      "wrapped": true
     }
   }
 }
@@ -3580,16 +3588,16 @@
 
To overcome the naming problem in the example above, the following definition can be used:

 

 {
-  "animals": {
-    "type": "array",
-    "items": {
-      "type": "string",
-      "xml": {
-        "name": "animal"
+  "animals": {
+    "type": "array",
+    "items": {
+      "type": "string",
+      "xml": {
+        "name": "animal"
       }
     },
-    "xml": {
-      "wrapped": true
+    "xml": {
+      "wrapped": true
     }
   }
 }
@@ -3613,17 +3621,17 @@
 
Affecting both internal and external names:

 

 {
-  "animals": {
-    "type": "array",
-    "items": {
-      "type": "string",
-      "xml": {
-        "name": "animal"
+  "animals": {
+    "type": "array",
+    "items": {
+      "type": "string",
+      "xml": {
+        "name": "animal"
       }
     },
-    "xml": {
-      "name": "aliens",
-      "wrapped": true
+    "xml": {
+      "name": "aliens",
+      "wrapped": true
     }
   }
 }
@@ -3648,14 +3656,14 @@
 
If we change the external element but not the internal ones:

 

 {
-  "animals": {
-    "type": "array",
-    "items": {
-      "type": "string"
+  "animals": {
+    "type": "array",
+    "items": {
+      "type": "string"
     },
-    "xml": {
-      "name": "aliens",
-      "wrapped": true
+    "xml": {
+      "name": "aliens",
+      "wrapped": true
     }
   }
 }
@@ -3744,8 +3752,8 @@
 
Basic Authentication Sample

 

 {
-  "type": "http",
-  "scheme": "basic"
+  "type": "http",
+  "scheme": "basic"
 }
 

 

@@ -3755,9 +3763,9 @@
 
API Key Sample

 

 {
-  "type": "apiKey",
-  "name": "api_key",
-  "in": "header"
+  "type": "apiKey",
+  "name": "api_key",
+  "in": "header"
 }
 

 

@@ -3768,9 +3776,9 @@
 
JWT Bearer Sample

 

 {
-  "type": "http",
-  "scheme": "bearer",
-  "bearerFormat": "JWT",
+  "type": "http",
+  "scheme": "bearer",
+  "bearerFormat": "JWT",
 }
 

 

@@ -3781,13 +3789,13 @@
 
Implicit OAuth2 Sample

 

 {
-  "type": "oauth2",
-  "flows": {
-    "implicit": {
-      "authorizationUrl": "https://example.com/api/oauth/dialog",
-      "scopes": {
-        "write:pets": "modify pets in your account",
-        "read:pets": "read your pets"
+  "type": "oauth2",
+  "flows": {
+    "implicit": {
+      "authorizationUrl": "https://example.com/api/oauth/dialog",
+      "scopes": {
+        "write:pets": "modify pets in your account",
+        "read:pets": "read your pets"
       }
     }
   }
@@ -3880,21 +3888,21 @@
 
OAuth Flow Object Examples

 

 {
-  "type": "oauth2",
-  "flows": {
-    "implicit": {
-      "authorizationUrl": "https://example.com/api/oauth/dialog",
-      "scopes": {
-        "write:pets": "modify pets in your account",
-        "read:pets": "read your pets"
+  "type": "oauth2",
+  "flows": {
+    "implicit": {
+      "authorizationUrl": "https://example.com/api/oauth/dialog",
+      "scopes": {
+        "write:pets": "modify pets in your account",
+        "read:pets": "read your pets"
       }
     },
-    "authorizationCode": {
-      "authorizationUrl": "https://example.com/api/oauth/dialog",
-      "tokenUrl": "https://example.com/api/oauth/token",
-      "scopes": {
-        "write:pets": "modify pets in your account",
-        "read:pets": "read your pets"
+    "authorizationCode": {
+      "authorizationUrl": "https://example.com/api/oauth/dialog",
+      "tokenUrl": "https://example.com/api/oauth/token",
+      "scopes": {
+        "write:pets": "modify pets in your account",
+        "read:pets": "read your pets"
       }
     }
   }
@@ -3942,18 +3950,18 @@
 
Non-OAuth2 Security Requirement

 

 {
-  "api_key": []
+  "api_key": []
 }
 

 

-api_key: []
+api_key: []
 

 
OAuth2 Security Requirement

 

 {
-  "petstore_auth": [
-    "write:pets",
-    "read:pets"
+  "petstore_auth": [
+    "write:pets",
+    "read:pets"
   ]
 }
 

@@ -3966,12 +3974,12 @@
 
Optional OAuth2 security as would be defined in an OpenAPI Object or an Operation Object:

 

 {
-  "security": [
+  "security": [
     {},
     {
-      "petstore_auth": [
-        "write:pets",
-        "read:pets"
+      "petstore_auth": [
+        "write:pets",
+        "read:pets"
       ]
     }
   ]
@@ -3979,7 +3987,7 @@
 

 

 security:
-  - {}
+  - {}
   - petstore_auth:
     - write:pets
     - read:pets
diff --git a/oas/v3.1.0.html b/oas/v3.1.0.html
index e9ba775ffc..751f55370c 100644
--- a/oas/v3.1.0.html
+++ b/oas/v3.1.0.html
@@ -162,7 +162,7 @@
 

-
+
@@ -521,47 +521,47 @@
 
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
@@ -578,99 +578,99 @@
 
 
Components Object Example

 

-"components": {
-  "schemas": {
-    "GeneralError": {
-      "type": "object",
-      "properties": {
-        "code": {
-          "type": "integer",
-          "format": "int32"
+"components": {
+  "schemas": {
+    "GeneralError": {
+      "type": "object",
+      "properties": {
+        "code": {
+          "type": "integer",
+          "format": "int32"
         },
-        "message": {
-          "type": "string"
+        "message": {
+          "type": "string"
         }
       }
     },
-    "Category": {
-      "type": "object",
-      "properties": {
-        "id": {
-          "type": "integer",
-          "format": "int64"
+    "Category": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "integer",
+          "format": "int64"
         },
-        "name": {
-          "type": "string"
+        "name": {
+          "type": "string"
         }
       }
     },
-    "Tag": {
-      "type": "object",
-      "properties": {
-        "id": {
-          "type": "integer",
-          "format": "int64"
+    "Tag": {
+      "type": "object",
+      "properties": {
+        "id": {
+          "type": "integer",
+          "format": "int64"
         },
-        "name": {
-          "type": "string"
+        "name": {
+          "type": "string"
         }
       }
     }
   },
-  "parameters": {
-    "skipParam": {
-      "name": "skip",
-      "in": "query",
-      "description": "number of items to skip",
-      "required": true,
-      "schema": {
-        "type": "integer",
-        "format": "int32"
+  "parameters": {
+    "skipParam": {
+      "name": "skip",
+      "in": "query",
+      "description": "number of items to skip",
+      "required": true,
+      "schema": {
+        "type": "integer",
+        "format": "int32"
       }
     },
-    "limitParam": {
-      "name": "limit",
-      "in": "query",
-      "description": "max records to return",
-      "required": true,
-      "schema" : {
-        "type": "integer",
-        "format": "int32"
+    "limitParam": {
+      "name": "limit",
+      "in": "query",
+      "description": "max records to return",
+      "required": true,
+      "schema" : {
+        "type": "integer",
+        "format": "int32"
       }
     }
   },
-  "responses": {
-    "NotFound": {
-      "description": "Entity not found."
+  "responses": {
+    "NotFound": {
+      "description": "Entity not found."
     },
-    "IllegalInput": {
-      "description": "Illegal input for operation."
+    "IllegalInput": {
+      "description": "Illegal input for operation."
     },
-    "GeneralError": {
-      "description": "General Error",
-      "content": {
-        "application/json": {
-          "schema": {
-            "$ref": "#/components/schemas/GeneralError"
+    "GeneralError": {
+      "description": "General Error",
+      "content": {
+        "application/json": {
+          "schema": {
+            "$ref": "#/components/schemas/GeneralError"
           }
         }
       }
     }
   },
-  "securitySchemes": {
-    "api_key": {
-      "type": "apiKey",
-      "name": "api_key",
-      "in": "header"
+  "securitySchemes": {
+    "api_key": {
+      "type": "apiKey",
+      "name": "api_key",
+      "in": "header"
     },
-    "petstore_auth": {
-      "type": "oauth2",
-      "flows": {
-        "implicit": {
-          "authorizationUrl": "https://example.org/api/oauth/dialog",
-          "scopes": {
-            "write:pets": "modify pets in your account",
-            "read:pets": "read your pets"
+    "petstore_auth": {
+      "type": "oauth2",
+      "flows": {
+        "implicit": {
+          "authorizationUrl": "https://example.org/api/oauth/dialog",
+          "scopes": {
+            "write:pets": "modify pets in your account",
+            "read:pets": "read your pets"
           }
         }
       }
@@ -899,7 +899,7 @@
 
 

-
+
@@ -1025,12 +1025,12 @@
 
 
-
+
-
+
@@ -1040,7 +1040,7 @@
 
-
+
@@ -1295,7 +1295,7 @@
 
-
+
@@ -1472,8 +1472,8 @@
 
-
-
+
+
@@ -1481,7 +1481,7 @@
 
-
+

 
 
 
 

  parametersMap[string, Any ¦ {expression}]Map[string, Any | {expression}]
 A map representing parameters to pass to an operation as specified with operationId or identified via operationRef. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation.  The parameter name can be qualified using the parameter location [{in}.]{name} for operations that use the same parameter name in different locations (e.g. path.id).
 

 

  requestBodyAny ¦ {expression}Any | {expression}
 A literal value or {expression} to use as a request body when calling the target operation.
 

 
 
     
       
               
           
             
        
             
 
 
 
 
 
 
 
 

 

  webhooksMap[string, Path Item Object ¦ Reference Object] ]Map[string, Path Item Object | Reference Object] ]
 The incoming webhooks that MAY be received as part of this API and that the API consumer MAY choose to implement. Closely related to the callbacks feature, this section describes requests initiated other than by an API call, for example by an out of band registration. The key name is a unique string to refer to each webhook, while the (optionally referenced) Path Item Object describes a request that may be initiated by the API provider and the expected responses. An example is available.
 

 

 

   responsesMap[string, Response Object ¦ Reference Object]Map[string, Response Object | Reference Object]
 An object to hold reusable Response Objects.
 

 

   parametersMap[string, Parameter Object ¦ Reference Object]Map[string, Parameter Object | Reference Object]
 An object to hold reusable Parameter Objects.
 

 

   examplesMap[string, Example Object ¦ Reference Object]Map[string, Example Object | Reference Object]
 An object to hold reusable Example Objects.
 

 

   requestBodiesMap[string, Request Body Object ¦ Reference Object]Map[string, Request Body Object | Reference Object]
 An object to hold reusable Request Body Objects.
 

 

   headersMap[string, Header Object ¦ Reference Object]Map[string, Header Object | Reference Object]
 An object to hold reusable Header Objects.
 

 

   securitySchemesMap[string, Security Scheme Object ¦ Reference Object]Map[string, Security Scheme Object | Reference Object]
 An object to hold reusable Security Scheme Objects.
 

 

   linksMap[string, Link Object ¦ Reference Object]Map[string, Link Object | Reference Object]
 An object to hold reusable Link Objects.
 

 

   callbacksMap[string, Callback Object ¦ Reference Object]Map[string, Callback Object | Reference Object]
 An object to hold reusable Callback Objects.
 

 

   pathItemsMap[string, Path Item Object ¦ Reference Object]Map[string, Path Item Object | Reference Object]
 An object to hold reusable Path Item Object.
 

 

  parameters[Parameter Object ¦ Reference Object][Parameter Object | Reference Object]
 A list of parameters that are applicable for all the operations described under this path. These parameters can be overridden at the operation level, but cannot be removed there. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object’s components/parameters.
 

 

  parameters[Parameter Object ¦ Reference Object][Parameter Object | Reference Object]
 A list of parameters that are applicable for this operation. If a parameter is already defined at the Path Item, the new definition will override it but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a name and location. The list can use the Reference Object to link to parameters that are defined at the OpenAPI Object’s components/parameters.
 

 

  requestBodyRequest Body Object ¦ Reference ObjectRequest 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]section-4.3.1), [HEAD]section-4.3.2) and [DELETE]section-4.3.5)), requestBody is permitted but does not have well-defined semantics and SHOULD be avoided if possible.
 

 

 

  callbacksMap[string, Callback Object ¦ Reference Object]Map[string, Callback Object | Reference Object]
 A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses.
 

 

 

  examplesMap[ string, Example Object ¦ Reference Object]Map[ string, Example Object | Reference Object]
 Examples of the parameter’s potential value. Each example SHOULD contain a value in the correct format as specified in the parameter encoding. The examples field is mutually exclusive of the example field. Furthermore, if referencing a schema that contains an example, the examples value SHALL override the example provided by the schema.
 

 
false
 n/a
 n/ablue¦black¦brownR¦100¦G¦200¦B¦150blue|black|brownR|100|G|200|B|150
 

 

 deepObjectn/a
 n/a
 n/acolor\R=100&color\G=200&color\B=150color[R]=100&color[G]=200&color[B]=150
 

 
 

@@ -1786,7 +1786,7 @@
 
 
  examples
-Map[ string, Example Object ¦ Reference Object]
+Map[ string, Example Object | Reference Object]
 Examples of the media type.  Each example object SHOULD  match the media type and specified schema if present.  The examples field is mutually exclusive of the example field.  Furthermore, if referencing a schema which contains an example, the examples value SHALL override the example provided by the schema.
 
 
@@ -1994,7 +1994,7 @@
 
 
  headers
-Map[string, Header Object ¦ Reference Object]
+Map[string, Header Object | Reference Object]
 A map allowing additional information to be provided as headers, for example Content-Disposition.  Content-Type is described separately and SHALL be ignored in this section. This property SHALL be ignored if the request body media type is not a multipart.
 
 
@@ -2072,7 +2072,7 @@
 
 
  default
-Response Object ¦ Reference Object
+Response Object | Reference Object
 The documentation of responses other than the ones declared for specific HTTP response codes. Use this field to cover undeclared responses.
 
 
@@ -2089,7 +2089,7 @@
 
 
  HTTP Status Code
-Response Object ¦ Reference Object
+Response Object | Reference Object
 Any HTTP status code can be used as the property name, but only one property per code, to describe the expected response for that HTTP status code. This field MUST be enclosed in quotation marks (for example, “200”) for compatibility between JSON and YAML. To define a range of response codes, this field MAY contain the uppercase wildcard character X. For example, 2XX represents all response codes between [200-299]. Only the following range definitions are allowed: 1XX, 2XX, 3XX, 4XX, and 5XX. If a response is defined using an explicit code, the explicit code definition takes precedence over the range definition for that code.
 
 
@@ -2155,7 +2155,7 @@
 
 
  headers
-Map[string, Header Object  ¦ Reference Object]
+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.
 
 
@@ -2165,7 +2165,7 @@
 
 
  links
-Map[string, Link Object ¦ Reference Object]
+Map[string, Link Object | Reference Object]
 A map of operations links that can be followed from the response. The key of the map is a short name for the link, following the naming constraints of the names for Component Objects.
 
 
@@ -2299,7 +2299,7 @@
 
 
  {expression}
-Path Item Object ¦ Reference Object
+Path Item Object | Reference Object
 A Path Item Object, or a reference to one, used to define a callback request and expected responses.  A complete example is available.
 
 
@@ -2518,12 +2518,12 @@
 
 
  parameters
-Map[string, Any ¦ {expression}]
+Map[string, Any | {expression}]
 A map representing parameters to pass to an operation as specified with operationId or identified via operationRef. The key is the parameter name to be used, whereas the value can be a constant or an expression to be evaluated and passed to the linked operation.  The parameter name can be qualified using the parameter location [{in}.]{name} for operations that use the same parameter name in different locations (e.g. path.id).
 
 
  requestBody
-Any ¦ {expression}
+Any | {expression}
 A literal value or {expression} to use as a request body when calling the target operation.