Merge pull request #3953 from ralfhandl/v3.1.1/sync-with-3.0.4

Align 3.1.1 with 3.0.4

Author: ralfhandl

versions/3.1.1.md

@@ -365,7 +365,6 @@ Field Name | Type | Description
 <a name="oasTags"></a>tags | [[Tag Object](#tagObject)] | A list of tags used by the document with additional metadata. The order of the tags can be used to reflect on their order by the parsing tools. Not all tags that are used by the [Operation Object](#operationObject) must be declared. The tags that are not declared MAY be organized randomly or based on the tools' logic. Each tag name in the list MUST be unique.
 <a name="oasExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation.
 
-
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
 #### <a name="infoObject"></a>Info Object
@@ -433,7 +432,7 @@ Contact information for the exposed API.
 Field Name | Type | Description
 ---|:---:|---
 <a name="contactName"></a>name | `string` | The identifying name of the contact person/organization.
-<a name="contactUrl"></a>url | `string` | The URI for to the contact information. This MUST be in the form of a URI.
+<a name="contactUrl"></a>url | `string` | The URI for the contact information. This MUST be in the form of a URI.
 <a name="contactEmail"></a>email | `string` | The email address of the contact person/organization. This MUST be in the form of an email address.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
@@ -819,13 +818,13 @@ components:
 #### <a name="pathsObject"></a>Paths Object
 
 Holds the relative paths to the individual endpoints and their operations.
-The path is appended to the URL from the [`Server Object`](#serverObject) in order to construct the full URL.  The Paths MAY be empty, due to [Access Control List (ACL) constraints](#securityFiltering).
+The path is appended to the URL from the [Server Object](#serverObject) in order to construct the full URL.  The Paths Object MAY be empty, due to [Access Control List (ACL) constraints](#securityFiltering).
 
 ##### Patterned Fields
 
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="pathsPath"></a>/{path} | [Path Item Object](#pathItemObject) | 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`](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) 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 name="pathsPath"></a>/{path} | [Path Item Object](#pathItemObject) | 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](#serverObject)'s `url` field in order to construct the full URL. [Path templating](#pathTemplating) 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.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -1113,12 +1112,12 @@ requestBody:
       schema:
        type: object
        properties:
-          name:
-            description: Updated name of the pet
-            type: string
-          status:
-            description: Updated status of the pet
-            type: string
+         name:
+           description: Updated name of the pet
+           type: string
+         status:
+           description: Updated status of the pet
+           type: string
        required:
          - status
 responses:
@@ -1512,7 +1511,7 @@ content:
       $ref: '#/components/schemas/User'
     examples:
       user:
-        summary: User Example
+        summary: User example
         externalValue: https://foo.bar/examples/user-example.json
   application/xml:
     schema:
@@ -1524,7 +1523,7 @@ content:
   text/plain:
     examples:
       user:
-        summary: User example in Plain text
+        summary: User example in plain text
         externalValue: https://foo.bar/examples/user-example.txt
   '*/*':
     examples:
@@ -1850,7 +1849,6 @@ requestBody:
             # subschema, which is an object, so `application/json`
             type: array
             items:
-              type: object
               $ref: '#/components/schemas/Address'
 ```
 
@@ -1926,9 +1924,9 @@ The documentation is not necessarily expected to cover all possible HTTP respons
 However, documentation is expected to cover a successful operation response and any known errors.
 
 The `default` MAY be used as a default response object for all HTTP codes 
-that are not covered individually by the `Responses Object`.
+that are not covered individually by the Responses Object.
 
-The `Responses Object` MUST contain at least one response code, and if only one
+The Responses Object MUST contain at least one response code, and if only one
 response code is provided it SHOULD be the response for a successful operation
 call.
 
@@ -2137,7 +2135,7 @@ To describe incoming requests from the API provider independent from another API
 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="callbackExpression"></a>{expression} | [Path Item Object](#pathItemObject) | A Path Item Object, used to define a callback request and expected responses.  A [complete example](../examples/v3.0/callback-example.yaml) is available.
+<a name="callbackExpression"></a>{expression} | [Path Item Object](#pathItemObject) | A Path Item Object used to define a callback request and expected responses.  A [complete example](../examples/v3.0/callback-example.yaml) is available.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
@@ -2394,7 +2392,7 @@ In this example, the JSON string had to be serialized before encoding it into th
 
 #### <a name="linkObject"></a>Link Object
 
-The `Link object` represents a possible design-time link for a response.
+The Link Object represents a possible design-time link for a response.
 The presence of a link does not guarantee the caller's ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.
 
 Unlike _dynamic_ links (i.e. links provided **in** the response payload), the OAS linking mechanism does not require link information in the runtime response.
@@ -2790,8 +2788,12 @@ The OpenAPI Specification allows combining and extending model definitions using
 `allOf` takes an array of object definitions that are validated *independently* but together compose a single object.
 
 While composition offers model extensibility, it does not imply a hierarchy between the models.
-To support polymorphism, the OpenAPI Specification adds the `discriminator` keyword.
+To support polymorphism, the OpenAPI Specification adds the [`discriminator`](#schemaDiscriminator) field.
 When used, the `discriminator` indicates the name of the property that hints which schema definition is expected to validate the structure of the model.
+As such, the `discriminator` field MUST be a required field.
+There are two ways to define the value of a discriminator for an inheriting instance.
+- Use the schema name.
+- [Override the schema name](#discriminatorMapping) by overriding the property with a new value. If a new value exists, this takes precedence over the schema name.
 
 ###### Generic (Template) Data Structures
 
@@ -3313,7 +3315,7 @@ MyResponseType:
   - $ref: '#/components/schemas/Lizard'
 ```
 
-which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Deserialization of a `oneOf` can be a costly operation, as it requires determining which schema matches the payload and thus should be used in deserialization. This problem also exists for `anyOf` schemas. A `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` keyword cannot change the validation result of the `oneOf`, it can only help make the deserialization more efficient and provide better error messaging. We can specify the exact field that tells us which schema is expected to match the instance:
+which means the payload _MUST_, by validation, match exactly one of the schemas described by `Cat`, `Dog`, or `Lizard`. Deserialization of a `oneOf` can be a costly operation, as it requires determining which schema matches the payload and thus should be used in deserialization. This problem also exists for `anyOf` schemas. A `discriminator` MAY be used as a "hint" to improve the efficiency of selection of the matching schema. The `discriminator` field cannot change the validation result of the `oneOf`, it can only help make the deserialization more efficient and provide better error messaging. We can specify the exact field that tells us which schema is expected to match the instance:
 
 ```yaml
 MyResponseType:
@@ -3437,7 +3439,7 @@ Field Name | Type | Description
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
 
-The `namespace` keyword is intended to match the syntax of [XML namespaces](https://www.w3.org/TR/xml-names11/), although there are a few caveats:
+The `namespace` field is intended to match the syntax of [XML namespaces](https://www.w3.org/TR/xml-names11/), although there are a few caveats:
 
 * Versions 3.1.0, 3.0.3, and earlier of this specification erroneously used the term "absolute URI" instead of "non-relative URI", so authors using namespaces that include a fragment should check tooling support carefully.
 * XML allows but discourages relative URI-references, while this specification outright forbids them.
@@ -3881,7 +3883,7 @@ description: Cert must be signed by example.com CA
 
 ```yaml
 type: oauth2
-flows: 
+flows:
   implicit:
     authorizationUrl: https://example.com/api/oauth/dialog
     scopes:
@@ -4186,7 +4188,7 @@ Certain properties allow the use of Markdown which can contain HTML including sc
 
 Version   | Date       | Notes
 ---       | ---        | ---
-3.1.1     | TBD        | TBD
+3.1.1     | TBD        | Patch release of the OpenAPI Specification 3.1.1
 3.1.0     | 2021-02-15 | Release of the OpenAPI Specification 3.1.0 
 3.1.0-rc1 | 2020-10-08 | rc1 of the 3.1 specification
 3.1.0-rc0 | 2020-06-18 | rc0 of the 3.1 specification