Merge pull request #3954 from ralfhandl/v3.0.4/sync-with-3.1.1

Align 3.0.4 with 3.1.1

versions/3.0.4.md

@@ -1649,7 +1649,8 @@ However, if all three of `style`, `explode`, and `allowReserved` fields are abse
 * All three keywords are to be entirely ignored, rather than treated as having their default values
 * Encoding is to be based on `contentType` alone, whether it is present with an explicit value or absent and treated as having its default value
 
-This makes the presence of at least one of `style`, `explode`, or `allowReserved` with an explicit value equivalent to using `schema` with `in: query` Parameter Objects, and their absence the equivalent of using `content`, but with the media type specified in `contentType` rather than through a Media Type Object.
+Note that the presence of at least one of `style`, `explode`, or `allowReserved` with an explicit value is equivalent to using `schema` with `in: query` Parameter Objects.
+The absence of all three of those fields is the equivalent of using `content`, but with the media type specified in `contentType` rather than through a Media Type Object.
 
 ##### Encoding the `x-www-form-urlencoded` Media Type
 
@@ -1998,9 +1999,9 @@ Plain text response with headers:
   "content": {
     "text/plain": {
       "schema": {
-        "type": "string",
-        "example": "whoa!"
-      }
+        "type": "string"
+      },
+      "example": "whoa!"
     }
   },
   "headers": {
@@ -2681,7 +2682,7 @@ These types can be objects, but also primitives and arrays.
 This object is an extended subset of the [JSON Schema Specification Wright Draft 00](https://json-schema.org/).
 
 For more information about the properties, see [JSON Schema Core](https://tools.ietf.org/html/draft-wright-json-schema-00) and [JSON Schema Validation](https://tools.ietf.org/html/draft-wright-json-schema-validation-00).
-Unless stated otherwise, the property definitions follow the JSON Schema.
+Unless stated otherwise, the property definitions follow those of JSON Schema and do not add any additional semantics.
 
 ##### Properties 
 
@@ -2727,11 +2728,11 @@ Other than the JSON Schema subset fields, the following fields MAY be used for f
 Field Name | Type | Description
 ---|:---:|---
 <a name="schemaNullable"></a>nullable | `boolean` | A `true` value adds `"null"` to the allowed type specified by the `type` keyword, only if `type` is explicitly defined within the same Schema Object. Other Schema Object constraints retain their defined behavior, and therefore may disallow the use of `null` as a value. A `false` value leaves the specified or default `type` unmodified. The default value is `false`.
-<a name="schemaDiscriminator"></a>discriminator | [Discriminator Object](#discriminatorObject) | Adds support for polymorphism. The discriminator is an object name that is used to differentiate between other schemas which may satisfy the payload description. See [Composition and Inheritance](#schemaComposition) for more details.
+<a name="schemaDiscriminator"></a>discriminator | [Discriminator Object](#discriminatorObject) | Adds support for polymorphism. The discriminator is used to determine which of a set of schemas a payload is expected to satisfy. See [Composition and Inheritance](#schemaComposition) for more details.
 <a name="schemaReadOnly"></a>readOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as `readOnly` being `true` and is in the `required` list, the `required` will take effect on the response only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`.
 <a name="schemaWriteOnly"></a>writeOnly | `boolean` | Relevant only for Schema `"properties"` definitions. Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as `writeOnly` being `true` and is in the `required` list, the `required` will take effect on the request only. A property MUST NOT be marked as both `readOnly` and `writeOnly` being `true`. Default value is `false`.
 <a name="schemaXml"></a>xml | [XML Object](#xmlObject) | This MAY be used only on properties schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property.
-<a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema. 
+<a name="schemaExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this schema.
 <a name="schemaExample"></a>example | Any | A free-form property to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.
 <a name="schemaDeprecated"></a> deprecated | `boolean` | Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is `false`.
 
@@ -2740,11 +2741,11 @@ This object MAY be extended with [Specification Extensions](#specificationExtens
 ###### <a name="schemaComposition"></a>Composition and Inheritance (Polymorphism)
 
 The OpenAPI Specification allows combining and extending model definitions using the `allOf` property of JSON Schema, in effect offering model composition.
-`allOf` takes an array of object definitions that are validated *independently* but together compose a single object. 
+`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` field.
-When used, the `discriminator` will be the name of the property that decides which schema definition validates the structure of the model.
+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.
@@ -3136,8 +3137,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`.  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:
-
+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:
@@ -3261,7 +3261,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:
 
 * Version 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.