Use document in place of description or definition

Author: earth2marsh

versions/3.0.md

@@ -8,15 +8,15 @@ This document is licensed under [The Apache License, Version 2.0](http://www.apa
 
 ## Introduction
 
-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 described, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
+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 documented, a consumer can understand and interact with the remote service with a minimal amount of implementation logic.
 
-An OpenAPI description 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 document 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 Description](#oasDescription)
+	- [OpenAPI Document](#oasDocument)
 	- [Path Templating](#pathTemplating)
 	- [Media Types](#mediaTypes)
 	- [HTTP Status Codes](#httpCodes)
@@ -66,8 +66,8 @@ An OpenAPI description can then be used by documentation generation tools to dis
 
 ## Definitions
 
-##### <a name="oasDescription"></a>OpenAPI Description
-A document or set of documents that describe an API. An OpenAPI description uses and conforms to the OpenAPI Specification.
+##### <a name="oasDocument"></a>OpenAPI Document
+A document or set of files that document an API. An OpenAPI document 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.
@@ -103,11 +103,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 description compatible with OAS 3.\*.\* contains a required [`openapi`](#oasVersion) field which designates the semantic version of the OAS that it uses. (OAS 2.0 description 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:
 
@@ -127,22 +127,22 @@ 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 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.
 
 ### <a name="documentStructure"></a>Document Structure
 
-An OpenAPI description MAY be made up of a single document.
-However, parts of the description MAY be split into separate documents, at the discretion of the user.
+An OpenAPI document MAY be made up of a single document.
+However, parts of the document MAY be split into separate files, 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.
 
-It is RECOMMENDED that the root OpenAPI description 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.
@@ -183,13 +183,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 description](#oasDescription).
+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 description uses. The `openapi` field SHOULD be used by tooling specifications and clients to interpret the OpenAPI description. 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 can be used by the clients if needed.
 <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.
@@ -214,7 +214,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 description (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 can be extended with [Specification Extensions](#specificationExtensions). 
@@ -318,7 +318,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 description 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/) can 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.