Prefer description when referring to an OAS document

earth2marsh · web-flow · commit ccf4651b2065 · 2017-06-30T13:10:40.000-07:00
Usage of description and definition to refer to an OAS document was mixed. This makes it more consistent, and prefers "description" of the service, since as a possible-truth it is more broad than "definition," which suggests an actual truth. (note: definition does still occur in the doc, but those refer to specific parts of the document rather than the document as a whole)
diff --git a/versions/3.0.md b/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 defined, 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 described, 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 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.
 
 ## Table of Contents
 <!-- TOC depthFrom:1 depthTo:3 withLinks:1 updateOnSave:1 orderedList:0 -->
 
 - [Definitions](#definitions)
-	- [OpenAPI Definition](#oasDefinition)
+	- [OpenAPI Description](#oasDescription)
 	- [Path Templating](#pathTemplating)
 	- [Media Types](#mediaTypes)
 	- [HTTP Status Codes](#httpCodes)
@@ -66,8 +66,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="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="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,7 +103,7 @@ 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 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"`.)
 
 ### Format
 
@@ -131,11 +131,11 @@ In order to preserve the ability to round-trip between YAML and JSON formats, YA
 
 ### <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.
+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.
 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 definition document be named: `openapi.json` or `openapi.yaml`.
+It is RECOMMENDED that the root OpenAPI description document be named: `openapi.json` or `openapi.yaml`.
 
 ### <a name="dataTypes"></a>Data Types
 
@@ -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 definition](#oasDefinition).
+This is the root document object of the [OpenAPI description](#oasDescription).
 
 ##### 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 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="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 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 API description (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 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 description 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.
 
