Address more PR review comments

Author: mikekistler

versions/3.0.4.md

@@ -20,11 +20,11 @@ For extension registries and other specifications published by the OpenAPI Initi
 
 ### OpenAPI Description
 
-An OpenAPI Description (OAD) formally describes the surface of an API and its semantics. It is composed of an [entry document](#openapi-description-structure) and any/all of its referenced documents. An OAD uses and conforms to the OpenAPI Specification.
+An OpenAPI Description (OAD) formally describes the surface of an API and its semantics. It is composed of an [entry document](#openapi-description-structure), which must be an OpenAPI Document, and any/all of its referenced documents. An OAD uses and conforms to the OpenAPI Specification.
 
 ### OpenAPI Document
 
-An OpenAPI Document is a single JSON or YAML document that conforms to the OpenAPI Specification.
+An OpenAPI Document is a single JSON or YAML document that conforms to the OpenAPI Specification. An OpenAPI Document compatible with OAS 3.\*.\* contains a required [`openapi`](#oas-version) field which designates the version of the OAS that it uses.
 
 ### Schema
 
@@ -93,8 +93,6 @@ The OpenAPI Specification is versioned using a `major`.`minor`.`patch` versionin
 
 Occasionally, non-backwards compatible changes may be made in `minor` versions of the OAS where impact is believed to be low relative to the benefit provided.
 
-An OpenAPI Document compatible with OAS 3.\*.\* contains a required [`openapi`](#oas-version) field which designates the version of the OAS that it uses.
-
 ### Format
 
 An OpenAPI Document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.
@@ -123,7 +121,7 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA
 
 ### OpenAPI Description Structure
 
-An OpenAPI Description (OAD) MAY be made up of a single JSON or YAML document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Object](#reference-object) and [Path Item Object](#path-item-object) `$ref` keywords, as well as the [Link Object](#link-object) `operationRef` keyword, are used to identify the referenced elements.
+An OpenAPI Description (OAD) MAY be made up of a single JSON or YAML document or be divided into multiple, connected parts at the discretion of the author. In the latter case, [Reference Object](#reference-object) and [Path Item Object](#path-item-object) `$ref` keywords, as well as the [Link Object](#link-object) `operationRef` keyword, and the URI form of the [Discriminator Object](#discriminator-object) mapping keyword, are used to identify the referenced elements.
 
 In a multi-document OAD, the document containing the OpenAPI Object where parsing begins is known as that OAD's **entry document**.
 
@@ -260,7 +258,7 @@ This is the root object of the [OpenAPI Description](#openapi-description).
 | <a name="oas-info"></a>info | [Info Object](#info-object) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required. |
 | <a name="oas-servers"></a>servers | [[Server Object](#server-object)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` field is not provided, or is an empty array, the default value would be a [Server Object](#server-object) with a [url](#server-url) value of `/`. |
 | <a name="oas-paths"></a>paths | [Paths Object](#paths-object) | **REQUIRED**. The available paths and operations for the API. |
-| <a name="oas-components"></a>components | [Components Object](#components-object) | An element to hold various schemas for the description. |
+| <a name="oas-components"></a>components | [Components Object](#components-object) | An element to hold various Objects for the description. |
 | <a name="oas-security"></a>security | [[Security Requirement Object](#security-requirement-object)] | A declaration of which security mechanisms can be used across the API. The list of values includes alternative Security Requirement Objects that can be used. Only one of the Security Requirement Objects need to be satisfied to authorize a request. Individual operations can override this definition. The list can be incomplete, up to being empty or absent. To make security explicitly optional, an empty security requirement (`{}`) can be included in the array. |
 | <a name="oas-tags"></a>tags | [[Tag Object](#tag-object)] | A list of tags used by the description 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](#operation-object) 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="oas-external-docs"></a>externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation. |
@@ -2153,7 +2151,7 @@ Because examples using these fields represent the final serialized form of the d
 The singular `example` field in the Parameter or Media Type Object is concise and convenient for simple examples, but does not offer any other advantages over using Example Objects under `examples`.
 
 Some examples cannot be represented directly in JSON or YAML.
-For all three ways of providing examples, these can be shown as string values with any escaping necessary to make the string valid in the JSON or YAML format of the OpenAPI Description.
+For all three ways of providing examples, these can be shown as string values with any escaping necessary to make the string valid in the JSON or YAML format of documents that comprise the OpenAPI Description.
 With the Example Object, such values can alternatively be handled through the `externalValue` field.
 
 ##### Example Object Examples
@@ -2303,7 +2301,7 @@ For computing links and providing instructions to execute them, a [runtime expre
 
 | Field Name | Type | Description |
 | ---- | :----: | ---- |
-| <a name="link-operation-ref"></a>operationRef | `string` | A relative or absolute URI reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operation-object). Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operation-object) in the OpenAPI Description. |
+| <a name="link-operation-ref"></a>operationRef | `string` | A URI reference to an OAS operation. This field is mutually exclusive of the `operationId` field, and MUST point to an [Operation Object](#operation-object). Relative `operationRef` values MAY be used to locate an existing [Operation Object](#operation-object) in the OpenAPI Description. |
 | <a name="link-operation-id"></a>operationId | `string` | The name of an _existing_, resolvable OAS operation, as defined with a unique `operationId`. This field is mutually exclusive of the `operationRef` field. |
 | <a name="link-parameters"></a>parameters | Map[`string`, Any \| [{expression}](#runtime-expressions)] | 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 (optionally qualified with the parameter location, e.g. `path.id` for an `id` parameter in the path), whereas the value can be a constant or an expression to be evaluated and passed to the linked operation. |
 | <a name="link-request-body"></a>requestBody | Any \| [{expression}](#runtime-expressions) | A literal value or [{expression}](#runtime-expressions) to use as a request body when calling the target operation. |
@@ -2402,7 +2400,7 @@ links:
       username: $response.body#/username
 ```
 
-or an absolute `operationRef`:
+or a URI `operationRef`:
 
 ```yaml
 links: