Merge branch 'OpenAPI.next' of github.com:OAI/OpenAPI-Specification into feature/links

Author: fehguy

versions/3.0.md

@@ -6,7 +6,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "S
 
 The OpenAPI Specification is licensed under [The Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).
 
-## Introductions
+## Introduction
 
 The OpenAPI Specification is a project used to describe and document RESTful APIs.
 
@@ -27,10 +27,10 @@ Version | Date | Notes
 ##### <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.
 
-##### <a name="mimeTypes"></a>Mime Types
-Mime type definitions are spread across several resources. The mime type definitions should be in compliance with [RFC 6838](http://tools.ietf.org/html/rfc6838).
+##### <a name="mediaTypes"></a>Media Types
+Media type definitions are spread across several resources. The media type definitions should be in compliance with [RFC 6838](http://tools.ietf.org/html/rfc6838).
 
-Some examples of possible mime type definitions:
+Some examples of possible media type definitions:
 ```
   text/plain; charset=utf-8
   application/json
@@ -114,8 +114,8 @@ Field Name | Type | Description
 <a name="oasVersion"></a>openapi | `string` | **Required.** Specifies the OpenAPI Specification version being used. It can be used by tooling Specifications and clients to interpret the version.  The structure shall be `major`.`minor`.`patch`, where `patch` versions _must_ be compatible with the existing `major`.`minor` tooling. Typically patch versions will be introduced to address errors in the documentation, and tooling should typically be compatible with the corresponding `major`.`minor` (3.0.*). Patch versions will correspond to patches of this document.
 <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="oasHosts"></a>hosts | [Hosts Object](#hostsObject) | An array of Host objects which provide `scheme`, `host`, `port`, and `basePath` in an associative manner.
-<a name="oasConsumes"></a>consumes | [`string`] | A list of MIME types the APIs can consume. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under [Mime Types](#mimeTypes).
-<a name="oasProduces"></a>produces | [`string`] | A list of MIME types the APIs can produce. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under [Mime Types](#mimeTypes).
+<a name="oasConsumes"></a>consumes | [`string`] | A list of media types the APIs can consume. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under [Media Types](#mediaTypes).
+<a name="oasProduces"></a>produces | [`string`] | A list of media types the APIs can produce. This is global to all APIs but can be overridden on specific API calls. Value MUST be as described under [Media Types](#mediaTypes).
 <a name="oasResponses"></a>responses | [Responses]
 <a name="oasPaths"></a>paths | [Paths Object](#pathsObject) | **Required.** The available paths and operations for the API.
 <a name="oasSchemas"></a>components | [Components Object](#componentsObject) | An element to hold various schemas for the specification.
@@ -448,8 +448,8 @@ Field Name | Type | Description
 <a name="operationDescription"></a>description | `string` | A verbose explanation of the operation behavior. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
 <a name="operationExternalDocs"></a>externalDocs | [External Documentation Object](#externalDocumentationObject) | Additional external documentation for this operation.
 <a name="operationId"></a>operationId | `string` | Unique string used to identify the operation. The id MUST be unique among all operations described in the API. Tools and libraries MAY use the operationId to uniquely identify an operation, therefore, it is recommended to follow common programming naming conventions.
-<a name="operationConsumes"></a>consumes | [`string`] | A list of MIME types the operation can consume. This overrides the [`consumes`](#oasConsumes) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Mime Types](#mimeTypes).
-<a name="operationProduces"></a>produces | [`string`] | A list of MIME types the operation can produce. This overrides the [`produces`](#oasProduces) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Mime Types](#mimeTypes).
+<a name="operationConsumes"></a>consumes | [`string`] | A list of media types the operation can consume. This overrides the [`consumes`](#oasConsumes) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Media Types](#mediaTypes).
+<a name="operationProduces"></a>produces | [`string`] | A list of media types the operation can produce. This overrides the [`produces`](#oasProduces) definition at the OpenAPI Object. An empty value MAY be used to clear the global definition. Value MUST be as described under [Media Types](#mediaTypes).
 <a name="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) <span>&#124;</span> [Reference Object](#referenceObject)] | A list of parameters that are applicable for this operation. If a parameter is already defined at the [Path Item](#pathItemParameters), the new definition will override it, but can never remove it. The list MUST NOT include duplicated parameters. A unique parameter is defined by a combination of a [name](#parameterName) and [___location](#parameterIn). The list can use the [Reference Object](#referenceObject) to link to parameters that are defined at the [OpenAPI Object's parameters](#oasParameters).
 <a name="operationRequestBody"></a>requestBody | [[Request Body Object](#requestBodyObject) <span>&#124;</span> [Reference Object](#referenceObject)] | The request body applicable for this operation. 
 <a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation.
@@ -749,7 +749,7 @@ Field Name | Type | Description
 ---|:---:|---
 <a name="requestBodyDescription"></a>description | `string` | A brief description of the request body. This could contain examples of use.  [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
 <a name="requestBodySchema"></a>schema | [Schema Object](#schemaObject) | The schema defining the type used for the request body.
-<a name="requestBodyExamples"></a>examples | [Examples Object](#examplesObject) | Examples of the request body, referenced by mime type.
+<a name="requestBodyExamples"></a>examples | [Examples Object](#examplesObject) | Examples of the request body, referenced by media type.
 <a name="requestBodyRequired"></a>required | `boolean` | Determines if the request body is required in the request. Defaults to `true`.
 
 
@@ -944,7 +944,7 @@ Describes a single response from an API Operation, including design-time, static
 Field Name | Type | Description
 ---|:---:|---
 <a name="responseDescription"></a>description | `string` | **Required.** A short description of the response. [GFM syntax](https://help.github.com/articles/github-flavored-markdown) can be used for rich text representation.
-<a name="responseSchema"></a>schema | [Schema Object](#schemaObject) | A definition of the response structure. It can be a primitive, an array or an object. If this field does not exist, it means no content is returned as part of the response. As an extension to the [Schema Object](#schemaObject), its root `type` value may also be `"file"`. This SHOULD be accompanied by a relevant `produces` mime-type.
+<a name="responseSchema"></a>schema | [Schema Object](#schemaObject) | A definition of the response structure. It can be a primitive, an array or an object. If this field does not exist, it means no content is returned as part of the response. As an extension to the [Schema Object](#schemaObject), its root `type` value may also be `"file"`. This SHOULD be accompanied by a relevant `produces` media type.
 <a name="responseHeaders"></a>headers | [Headers Object](#headersObject) | A list of headers that are sent with the response.
 <a name="responseExamples"></a>examples | [Example Object](#exampleObject) | An example of the response message.
 <a name="responseLinks"></a>links | [Links Object](#linksObject) | An object representing operations related to the response payload.
@@ -1098,11 +1098,11 @@ Allows sharing examples for operation requests and responses.
 ##### Patterned Fields
 Field Pattern | Type | Description
 ---|:---:|---
-<a name="exampleMimeType"></a>{[mime type](#mimeTypes)} | Any | The name of the property MUST be one of the Operation `produces` values (either implicit or inherited). The value SHOULD be an example of what such a response would look like. 
+<a name="exampleMediaType"></a>{[media type](#mediaTypes)} | Any | The name of the property MUST be one of the Operation `produces` values (either implicit or inherited). The value SHOULD be an example of what such a response would look like. 
 
 ##### Example Object Example
 
-Example request or response for application/json mimetype of a Pet data type:
+Example request or response for application/json media type of a Pet data type:
 
 ```js
 {