Updates based on TDC Meeting

Author: mikekistler

versions/3.0.4.md

@@ -22,6 +22,10 @@ For extension registries and other specifications published by the OpenAPI Initi
 
 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.
 
+### OpenAPI Document
+
+An OpenAPI Document is a single JSON or YAML document that conforms to the OpenAPI Specification.
+
 ### Schema
 
 A "schema" is a formal description of syntax and structure.
@@ -89,11 +93,11 @@ 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 Description compatible with OAS 3.\*.\* contains a required [`openapi`](#oas-version) field which designates the version of the OAS that it uses.
+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 Description that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML 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.
 
 For example, if a field has an array value, the JSON array representation will be used:
 
@@ -119,7 +123,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 structured as a single JSON or YAML document or composed from elements distributed across multiple documents 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 documents containing 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, 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**.
 
@@ -129,7 +133,7 @@ It is RECOMMENDED that the entry document of an OAD be named: `openapi.json` or
 
 JSON or YAML objects within an OAD are interpreted as specific Objects (such as [Operation Objects](#operation-object), [Response Objects](#response-object), [Reference Objects](#reference-object), etc.) based on their context. Depending on how references are arranged, a given JSON or YAML object can be interpreted in multiple different contexts:
 
-* The root object of the entry document is interpreted as an OpenAPI Object
+* As the root object of the [entry document](#openapi-description-structure), which is always interpreted as an OpenAPI Object
 * As the Object type implied by its parent Object within the OpenAPI Description
 * As a reference target, with the Object type matching the reference source's context
 
@@ -252,7 +256,7 @@ This is the root object of the [OpenAPI Description](#openapi-description).
 
 | Field Name | Type | Description |
 | ---- | :----: | ---- |
-| <a name="oas-version"></a>openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the OpenAPI Specification that the OpenAPI Description uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI Description. This is _not_ related to the API [`info.version`](#info-version) string. |
+| <a name="oas-version"></a>openapi | `string` | **REQUIRED**. This string MUST be the [version number](#versions) of the OpenAPI Specification that the OpenAPI Document uses. The `openapi` field SHOULD be used by tooling to interpret the OpenAPI Document. This is _not_ related to the API [`info.version`](#info-version) string. |
 | <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. |
@@ -277,7 +281,7 @@ The metadata MAY be used by the clients if needed, and MAY be presented in editi
 | <a name="info-terms-of-service"></a>termsOfService | `string` | A URL for the Terms of Service for the API. This MUST be in the form of a URL. |
 | <a name="info-contact"></a>contact | [Contact Object](#contact-object) | The contact information for the exposed API. |
 | <a name="info-license"></a>license | [License Object](#license-object) | The license information for the exposed API. |
-| <a name="info-version"></a>version | `string` | **REQUIRED**. The version of the OpenAPI Description (which is distinct from the [OpenAPI Specification version](#oas-version) or the version of the API being described). |
+| <a name="info-version"></a>version | `string` | **REQUIRED**. The version of the OpenAPI Document (which is distinct from the [OpenAPI Specification version](#oas-version) or the version of the API being described or the version of the OpenAPI Description). |
 
 This object MAY be extended with [Specification Extensions](#specification-extensions).
 
@@ -3073,7 +3077,7 @@ However, the exact nature of such conversions are implementation-defined.
 
 ##### Examples
 
-For these examples, assume all schemas are in a single-document OpenAPI Description; for handling of `discriminator` in referenced documents see [Resolving Implicit Connections](#resolving-implicit-connections).
+For these examples, assume all schemas are in the [entry document](#openapi-description-structure) of the OAD; for handling of `discriminator` in referenced documents see [Resolving Implicit Connections](#resolving-implicit-connections).
 
 In OAS 3.0, a response payload MAY be described to be exactly one of any number of types: