Remaining unnecessary differences

ralfhandl · ralfhandl · commit 9312d0813bd5 · 2024-06-26T16:58:49.000+02:00
diff --git a/versions/3.0.4.md b/versions/3.0.4.md
@@ -2604,7 +2604,7 @@ It is not mandatory to have a Tag Object per tag defined in the Operation Object
 Field Name | Type | Description
 ---|:---:|---
 <a name="tagName"></a>name | `string` | **REQUIRED**. The name of the tag.
-<a name="tagDescription"></a>description | `string` | A short description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+<a name="tagDescription"></a>description | `string` | A description for the tag. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
 <a name="tagExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this tag.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
@@ -2626,7 +2626,7 @@ description: Pets operations
 
 #### <a name="referenceObject"></a>Reference Object
 
-A simple object to allow referencing other components in the specification, internally and externally.
+A simple object to allow referencing other components in the OpenAPI document, internally and externally.
 
 The Reference Object is defined by [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules. 
 
@@ -3157,7 +3157,7 @@ The expectation now is that a property with name `petType` _MUST_ be present in
 }
 ```
 
-Will indicate that the `Cat` schema be used in conjunction with this payload.
+Will indicate that the `Cat` schema is expected to match this payload.
 
 In scenarios where the value of the discriminator field does not match the schema name or implicit mapping is not possible, an optional `mapping` definition MAY be used:
 
@@ -3177,7 +3177,7 @@ MyResponseType:
 
 Here the discriminating value of `dog` will map to the schema `#/components/schemas/Dog`, rather than the default (implicit) value of `#/components/schemas/dog`.  If the discriminating value does not match an implicit or explicit mapping, no schema can be determined and validation SHOULD fail.
 
-When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity where multiple schemas may satisfy a single payload.
+When used in conjunction with the `anyOf` construct, the use of the discriminator can avoid ambiguity for serializers/deserializers where multiple schemas may satisfy a single payload.
 
 This example shows the `allOf` usage, which avoids needing to reference all child schemas in the parent:
 
@@ -3221,7 +3221,7 @@ components:
             type: boolean
 ```
 
-a payload like this:
+Validated against the `Pet` schema, a payload like this:
 
 ```json
 {
@@ -3230,7 +3230,7 @@ a payload like this:
 }
 ```
 
-will indicate that the `Cat` schema be used.  Likewise this schema:
+will indicate that the `#/components/schemas/Cat` schema is expected to match.  Likewise this payload:
 
 ```json
 {
@@ -3239,7 +3239,7 @@ will indicate that the `Cat` schema be used.  Likewise this schema:
 }
 ```
 
-will map to `Dog` because of the definition in the `mappings` element.
+will map to `#/components/schemas/Dog` because the `dog` entry in the `mapping` element maps to `Dog` which is the schema name for `#/components/schemas/Dog`.
 
 
 #### <a name="xmlObject"></a>XML Object
@@ -3362,7 +3362,7 @@ In this example, a full model definition is shown.
       "name": {
         "type": "string",
         "xml": {
-          "namespace": "http://example.com/schema/sample",
+          "namespace": "https://example.com/schema/sample",
           "prefix": "sample"
         }
       }
@@ -3383,13 +3383,13 @@ Person:
     name:
       type: string
       xml:
-        namespace: http://example.com/schema/sample
+        namespace: https://example.com/schema/sample
         prefix: sample
 ```
 
 ```xml
 <Person id="123">
-    <sample:name xmlns:sample="http://example.com/schema/sample">example</sample:name>
+    <sample:name xmlns:sample="https://example.com/schema/sample">example</sample:name>
 </Person>
 ```
 
@@ -3611,7 +3611,7 @@ Supported schemes are HTTP authentication, an API key (either as a header, a coo
 Field Name | Type | Applies To | Description
 ---|:---:|---|---
 <a name="securitySchemeType"></a>type | `string` | Any | **REQUIRED**. The type of the security scheme. Valid values are `"apiKey"`, `"http"`, `"oauth2"`, `"openIdConnect"`.
-<a name="securitySchemeDescription"></a>description | `string` | Any | A short description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
+<a name="securitySchemeDescription"></a>description | `string` | Any | A description for security scheme. [CommonMark syntax](https://spec.commonmark.org/) MAY be used for rich text representation.
 <a name="securitySchemeName"></a>name | `string` | `apiKey` | **REQUIRED**. The name of the header, query or cookie parameter to be used.
 <a name="securitySchemeIn"></a>in | `string` | `apiKey` | **REQUIRED**. The location of the API key. Valid values are `"query"`, `"header"` or `"cookie"`.
 <a name="securitySchemeScheme"></a>scheme | `string` | `http` | **REQUIRED**. The name of the HTTP Authentication scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-5.1).  The values used SHOULD be registered in the [IANA Authentication Scheme registry](https://www.iana.org/assignments/http-authschemes/http-authschemes.xhtml).  The value is case-insensitive, as defined in [RFC7235](https://datatracker.ietf.org/doc/html/rfc7235#section-2.1).
@@ -3642,14 +3642,14 @@ scheme: basic
 ```json
 {
   "type": "apiKey",
-  "name": "api_key",
+  "name": "api-key",
   "in": "header"
 }
 ```
 
 ```yaml
 type: apiKey
-name: api_key
+name: api-key
 in: header
 ```
 
@@ -3659,7 +3659,7 @@ in: header
 {
   "type": "http",
   "scheme": "bearer",
-  "bearerFormat": "JWT",
+  "bearerFormat": "JWT"
 }
 ```
 
@@ -3717,9 +3717,9 @@ Configuration details for a supported OAuth Flow
 ##### Fixed Fields
 Field Name | Type | Applies To | Description
 ---|:---:|---|---
-<a name="oauthFlowAuthorizationUrl"></a>authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL.
-<a name="oauthFlowTokenUrl"></a>tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL.
-<a name="oauthFlowRefreshUrl"></a>refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL.
+<a name="oauthFlowAuthorizationUrl"></a>authorizationUrl | `string` | `oauth2` (`"implicit"`, `"authorizationCode"`) | **REQUIRED**. The authorization URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+<a name="oauthFlowTokenUrl"></a>tokenUrl | `string` | `oauth2` (`"password"`, `"clientCredentials"`, `"authorizationCode"`) | **REQUIRED**. The token URL to be used for this flow. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
+<a name="oauthFlowRefreshUrl"></a>refreshUrl | `string` | `oauth2` | The URL to be used for obtaining refresh tokens. This MUST be in the form of a URL. The OAuth2 standard requires the use of TLS.
 <a name="oauthFlowScopes"></a>scopes | Map[`string`, `string`] | `oauth2` | **REQUIRED**. The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it. The map MAY be empty.
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
@@ -3960,7 +3960,7 @@ While not part of the specification itself, certain libraries MAY choose to allo
 
 Two examples of this:
 
-1. The [Paths Object](#pathsObject) MAY be empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They'd still have access to the [Info Object](#infoObject) which may contain additional information regarding authentication.
+1. The [Paths Object](#pathsObject) MAY be present but empty. It may be counterintuitive, but this may tell the viewer that they got to the right place, but can't access any documentation. They would still have access to at least the [Info Object](#infoObject) which may contain additional information regarding authentication.
 2. The [Path Item Object](#pathItemObject) MAY be empty. In this case, the viewer will be aware that the path exists, but will not be able to see any of its operations or parameters. This is different from hiding the path itself from the [Paths Object](#pathsObject), because the user will be aware of its existence. This allows the documentation provider to finely control what the viewer can see.
 
 ## Security Considerations
@@ -4030,7 +4030,7 @@ To control the serialization of numbers, booleans, and `null` (or other values R
 The resulting strings would not require any further type conversion.
 
 The `format` keyword can assist in serialization.
-Some formats (such as `date-time` or `byte`) are unambiguous, while others (such as [`decimal`](https://spec.openapis.org/registry/format/decimal.html) in the [Format Registry](https://spec.openapis.org/registry/format/)) are less clear.
+Some formats (such as `date-time`) are unambiguous, while others (such as [`decimal`](https://spec.openapis.org/registry/format/decimal.html) in the [Format Registry](https://spec.openapis.org/registry/format/)) are less clear.
 However, care must be taken with `format` to ensure that the specific formats are supported by all relevant tools as unrecognized formats are ignored.
 
 Requiring input as pre-formatted, schema-validated strings also improves round-trip interoperability as not all programming languages and environments support the same data types.
