Merge pull request OAI#1247 from OAI/earth2marsh-patch-1

Prefer `description` when referring to an OAS document

Author: Ron

versions/3.0.md

@@ -10,13 +10,13 @@ This document is licensed under [The Apache License, Version 2.0](http://www.apa
 
 The OpenAPI Specification (OAS) defines a standard, language-agnostic interface to RESTful APIs which allows both humans and computers to discover and understand the capabilities of the service without access to source code, documentation, or through network traffic inspection. When properly defined, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
 
-An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools and many other use cases.
+An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases.
 
 ## Table of Contents
 <!-- TOC depthFrom:1 depthTo:3 withLinks:1 updateOnSave:1 orderedList:0 -->
 
 - [Definitions](#definitions)
-	- [OpenAPI Definition](#oasDefinition)
+	- [OpenAPI Document](#oasDocument)
 	- [Path Templating](#pathTemplating)
 	- [Media Types](#mediaTypes)
 	- [HTTP Status Codes](#httpCodes)
@@ -67,8 +67,8 @@ An OpenAPI definition can then be used by documentation generation tools to disp
 
 ## Definitions
 
-##### <a name="oasDefinition"></a>OpenAPI Definition
-A document or set of documents which defines an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.
+##### <a name="oasDocument"></a>OpenAPI Document
+A document (or set of documents) that defines or describes an API. An OpenAPI definition uses and conforms to the OpenAPI Specification.
 
 ##### <a name="pathTemplating"></a>Path Templating
 Path templating refers to the usage of curly braces ({}) to mark a section of a URL path as replaceable using path parameters.
@@ -104,11 +104,11 @@ The `major`.`minor` portion of the semver (for example `3.0`) SHALL designate th
 
 Subsequent minor version releases of the OpenAPI Specification (incrementing the `minor` version number) SHOULD NOT interfere with tooling developed to a lower minor version and same major version.  Thus a hypothetical `3.1.0` specification SHOULD be usable with tooling designed for `3.0.0`.
 
-An OpenAPI definition compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 definition documents contain a top-level version field named [`swagger`](http://swagger.io/specification/#swaggerObject) and value `"2.0"`.)
+An OpenAPI document compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 documents contain a top-level version field named [`swagger`](http://swagger.io/specification/#swaggerObject) and value `"2.0"`.)
 
 ### Format
 
-An API 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:
 
@@ -128,22 +128,20 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA
 - Tags MUST be limited to those allowed by the [JSON Schema ruleset](http://www.yaml.org/spec/1.2/spec.html#id2803231).
 - Keys used in YAML maps MUST be limited to a scalar string, as defined by the [YAML Failsafe schema ruleset](http://yaml.org/spec/1.2/spec.html#id2802346).
 
-**Note:** While APIs are described by OpenAPI documents in YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
+**Note:** While APIs may be defined by OpenAPI documents in either YAML or JSON format, the API request and response bodies and other content are not required to be JSON or YAML.
 
 ### <a name="documentStructure"></a>Document Structure
 
-An OpenAPI definition MAY be made up of a single document.
-However, parts of the definitions MAY be split into separate documents, at the discretion of the user.
-This is applicable for `$ref` fields in the specification as follows from the [JSON Schema](http://json-schema.org) definitions.
+An OpenAPI document MAY be made up of a single document or be divided into multiple, connected parts at the discretion of the user. In the latter case, `$ref` fields MUST be used in the specification to reference those parts as follows from the [JSON Schema](http://json-schema.org) definitions.
 
-It is RECOMMENDED that the root OpenAPI definition document be named: `openapi.json` or `openapi.yaml`.
+It is RECOMMENDED that the root OpenAPI document be named: `openapi.json` or `openapi.yaml`.
 
 ### <a name="dataTypes"></a>Data Types
 
 Primitive data types in the OAS are based on the types supported by the [JSON Schema Specification Wright Draft 00](https://tools.ietf.org/html/draft-wright-json-schema-00#section-4.2). 
 Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. 
 `null` is not supported as a type (see [`nullable`](#schemaNullable) for an alternative solution).
-Models are described using the [Schema Object](#schemaObject) which is an extended subset of JSON Schema Specification Wright Draft 00.
+Models are defined using the [Schema Object](#schemaObject), which is an extended subset of JSON Schema Specification Wright Draft 00.
 
 <a name="dataTypeFormat"></a>Primitives have an optional modifier property: `format`.
 OAS uses several known formats to define in fine detail the data type being used.
@@ -184,13 +182,13 @@ In the following description, if a field is not explicitly **REQUIRED** or descr
 
 #### <a name="oasObject"></a>OpenAPI Object
 
-This is the root document object of the [OpenAPI definition](#oasDefinition).
+This is the root document object of the [OpenAPI document](#oasDocument).
 
 ##### Fixed Fields
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="oasVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](http://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI definition uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI definition. This is *not* related to the API [`info.version`](#infoVersion) string.
+<a name="oasVersion"></a>openapi | `string` | **REQUIRED**. This string MUST be the [semantic version number](http://semver.org/spec/v2.0.0.html) of the [OpenAPI Specification version](#versions) that the OpenAPI document uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI document. This is *not* related to the API [`info.version`](#infoVersion) string.
 <a name="oasInfo"></a>info | [Info Object](#infoObject) | **REQUIRED**. Provides metadata about the API. The metadata MAY be used by tooling as required.
 <a name="oasServers"></a>servers | [[Server Object](#serverObject)] | An array of Server Objects, which provide connectivity information to a target server. If the `servers` property is not provided, or is an empty array, the default value would be a [Server Object](#serverObject) with a [url](#serverUrl) value of `/`.
 <a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **REQUIRED**. The available paths and operations for the API.
@@ -215,7 +213,7 @@ Field Name | Type | Description
 <a name="infoTermsOfService"></a>termsOfService | `string` | A URL to the Terms of Service for the API. MUST be in the format of a URL.
 <a name="infoContact"></a>contact | [Contact Object](#contactObject) | The contact information for the exposed API.
 <a name="infoLicense"></a>license | [License Object](#licenseObject) | The license information for the exposed API.
-<a name="infoVersion"></a>version | `string` | **REQUIRED**. The version of the API definition (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version).
+<a name="infoVersion"></a>version | `string` | **REQUIRED**. The version of the OpenAPI document (which is distinct from the [OpenAPI Specification version](#oasVersion) or the API implementation version).
 
 
 This object MAY be extended with [Specification Extensions](#specificationExtensions).
@@ -319,7 +317,7 @@ An object representing a Server.
 
 Field Name | Type | Description
 ---|:---:|---
-<a name="serverUrl"></a>url | `string` | **REQUIRED**. A URL to the target host.  This URL supports Server Variables and MAY be relative, to indicate that the host ___location is relative to the ___location where the OpenAPI definition is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`.
+<a name="serverUrl"></a>url | `string` | **REQUIRED**. A URL to the target host.  This URL supports Server Variables and MAY be relative, to indicate that the host ___location is relative to the ___location where the OpenAPI document is being served. Variable substitutions will be made when a variable is named in `{`brackets`}`.
 <a name="serverDescription"></a>description | `string` | An optional string describing the host designated by the URL. [CommonMark syntax](http://spec.commonmark.org/) MAY be used for rich text representation.
 <a name="serverVariables"></a>variables | Map[`string`, [Server Variable Object](#serverVariableObject)] | A map between a variable name and its value.  The value is used for substitution in the server's URL template.