Merge pull request OAI#1091 from MikeRalphson/rfc-formatting

Ron · web-flow · commit 6c4fd243f37f · 2017-05-08T11:58:58.000-07:00
Make RFC references more consistent
diff --git a/versions/3.0.md b/versions/3.0.md
@@ -2,7 +2,7 @@
 
 #### Version 3.0.0-rc2
 
-The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](http://www.ietf.org/rfc/rfc2119.txt).
+The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119](http://www.ietf.org/rfc/rfc2119.txt).
 
 This document is licensed under [The Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0.html).
 
@@ -81,7 +81,7 @@ Path templating refers to the usage of curly braces ({}) to mark a section of a
 
 ##### <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).
+The media type definitions SHOULD be in compliance with [RFC6838](http://tools.ietf.org/html/rfc6838).
 
 Some examples of possible media type definitions:
 ```
@@ -98,7 +98,7 @@ Some examples of possible media type definitions:
 ```
 ##### <a name="httpCodes"></a>HTTP Status Codes
 The HTTP Status Codes are used to indicate the status of the executed operation. 
-The available status codes are defined by [RFC 7231](http://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
+The available status codes are defined by [RFC7231](http://tools.ietf.org/html/rfc7231#section-6) and registered status codes are listed in the [IANA Status Code Registry](http://www.iana.org/assignments/http-status-codes/http-status-codes.xhtml).
 
 ## Specification
 
@@ -172,7 +172,7 @@ OpenAPI compliant tooling MUST support [CommonMark 0.27](http://spec.commonmark.
 
 ### <a name="relativeReferences"></a>Relative References in URLs
 
-Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC 3986](https://tools.ietf.org/html/rfc3986#section-4.2).
+Unless specified otherwise, all properties that are URLs MAY be relative references as defined by [RFC3986](https://tools.ietf.org/html/rfc3986#section-4.2).
 Relative references are resolved using the URLs defined in the [`Server Object`](#serverObject) as a Base URI.
 
 Relative references used in `$ref` are processed as per [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03), i.e. using the URL of the current document as the base URI. See also the [Reference Object](#referenceObject).
@@ -769,7 +769,7 @@ Field Name | Type | Description
 <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="operationParameters"></a>parameters | [[Parameter Object](#parameterObject) \| [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 components/parameters](#componentsParameters).
-<a name="operationRequestBody"></a>requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation.  The `requestBody` is only supported in HTTP methods where the [HTTP 1.1 specification](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies.  In other cases where the HTTP spec is vague, `requestBody` SHALL be ignored by consumers.
+<a name="operationRequestBody"></a>requestBody | [Request Body Object](#requestBodyObject) \| [Reference Object](#referenceObject) | The request body applicable for this operation.  The `requestBody` is only supported in HTTP methods where the HTTP 1.1 specification [RFC7231](https://tools.ietf.org/html/rfc7231#section-4.3.1) has explicitly defined semantics for request bodies.  In other cases where the HTTP spec is vague, `requestBody` SHALL be ignored by consumers.
 <a name="operationResponses"></a>responses | [Responses Object](#responsesObject) | **Required.** The list of possible responses as they are returned from executing this operation.
 <a name="operationCallbacks"></a>callbacks | [Callbacks Object](#callbacksObject) | The list of possible callbacks as they are returned from executing this operation.
 <a name="operationDeprecated"></a>deprecated | `boolean` | Declares this operation to be deprecated. Consumers SHOULD refrain from usage of the declared operation. Default value is `false`.
@@ -922,7 +922,7 @@ A unique parameter is defined by a combination of a [name](#parameterName) and [
 There are four possible parameter locations (as specified with the `in` field):
 * path - Used together with [Path Templating](#pathTemplating), where the parameter value is actually part of the operation's URL. This does not include the host or base path of the API. For example, in `/items/{itemId}`, the path parameter is `itemId`.
 * query - Parameters that are appended to the URL. For example, in `/items?id=###`, the query parameter is `id`.
-* header - Custom headers that are expected as part of the request. Note that [RFC 7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
+* header - Custom headers that are expected as part of the request. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
 * cookie - Used to pass a specific cookie value to the API.
 
 
@@ -1452,7 +1452,7 @@ requestBody:
 
 ##### Support for x-www-form-urlencoded request bodies
 
-To submit content using form url encoding via RFC 1866, the following
+To submit content using form url encoding via [RFC1866](https://tools.ietf.org/html/rfc1866), the following
 definition may be used:
 
 ```yaml
@@ -1466,12 +1466,12 @@ requestBody:
             type: string
             format: uuid
           address:
-            # complex types are stringified to support RFC1866
+            # complex types are stringified to support RFC 1866
             type: object
             properties: {}
 ```
 
-Note that in the above example, the contents in the `requestBody` MUST be stringified per RFC1866 when being passed to the server.  In addition, the `address` field complex object will be stringified as well.
+Note that in the above example, the contents in the `requestBody` MUST be stringified per [RFC1866](https://tools.ietf.org/html/rfc1866/) when being passed to the server.  In addition, the `address` field complex object will be stringified as well.
 
 When passing complex objects in the `x-www-form-urlencoded` content type, the default serialization strategy of such properties is described in the `parameterContent` section as `form`.
 
@@ -1809,7 +1809,7 @@ This object can be extended with [Specification Extensions](#specificationExtens
 The key used to identify the [Path Item Object](#pathItemObject) is a variable expression that can be evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request.
 A simple example might be `$request.body#/url`.
 However, using [variable substitution](#variableSubstitution) syntax the complete HTTP message can be accessed.
-This includes accessing any part of a body that can be accessed using a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901). 
+This includes accessing any part of a body that can be accessed using a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901).
 
 For example, given the following HTTP request:
 
@@ -1869,7 +1869,7 @@ myWebhook:
 
 
 #### <a name="headersObject"></a>Headers Object
-Lists the headers that can be sent in a response or forwarded via a link. Note that [RFC 7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
+Lists the headers that can be sent in a response or forwarded via a link. Note that [RFC7230](https://tools.ietf.org/html/rfc7230#page-22) states header names are case insensitive.
 
 ##### Patterned Fields
 Field Pattern | Type | Description
@@ -2104,10 +2104,10 @@ The variable expression is defined by the following [ABNF](https://tools.ietf.or
       query-reference = "query." name  
       path-reference = "path." name
       body-reference = "body#" fragment
-      fragment = a JSON Pointer [RFC 6901](https://tools.ietf.org/html/rfc6901)  
+      fragment = a JSON Pointer [RFC6901](https://tools.ietf.org/html/rfc6901)
       name = *( char )
-      char = as per RFC [7159](https://tools.ietf.org/html/rfc7159#section-7)
-      token = as per RFC [7230](https://tools.ietf.org/html/rfc7230#section-3.2.6)
+      char = as per [RFC7159](https://tools.ietf.org/html/rfc7159#section-7)
+      token = as per [RFC7230](https://tools.ietf.org/html/rfc7230#section-3.2.6)
 ```
 
 The `name` identifier is case-sensitive, whereas `token` is not. 
@@ -3378,7 +3378,7 @@ Field Name | Type | Validity | Description
 <a name="securitySchemeDescription"></a>description | `string` | Any | A short description for security scheme. [CommonMark syntax](http://spec.commonmark.org/) can be used for rich text representation.
 <a name="securitySchemeName"></a>name | `string` | `apiKey` | **Required.** The name of the header or query parameter to be used.
 <a name="securitySchemeIn"></a>in | `string` | `apiKey` | **Required.** The ___location of the API key. Valid values are `"query"` or `"header"`.
-<a name="securitySchemeScheme"></a>scheme | `string` | `http` | **Required.** The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC 7235](https://tools.ietf.org/html/rfc7235#section-4.2).
+<a name="securitySchemeScheme"></a>scheme | `string` | `http` | **Required.** The name of the HTTP Authorization scheme to be used in the [Authorization header as defined in RFC7235](https://tools.ietf.org/html/rfc7235#section-4.2).
 <a name="securitySchemeBearerFormat"></a>bearerFormat | `string` | `http` (`"bearer"`) | A hint to the client to identify how the bearer token is formatted.  Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
 <a name="securitySchemeFlows"></a>flows | [OAuth Flows Object](#oauthFlowsObject) | `oauth2` | **Required.** An object containing configuration information for the flow types supported. 
 <a name="securitySchemeOpenIdConnectUrl"></a>openIdConnectUrl | `string` | `openIdConnect` | **Required.** OpenId Connect URL to discover OAuth2 configuration values. This MUST be in the form of a URL. 
