Refactoring based on PR discussion

Author: jharmn

guidelines/REUSE.md

@@ -9,33 +9,40 @@ The following types are reusable, as defined by the spec:
 * Parameters
 * Models (or Schema Objects in general)
 * Responses
-* Operations (_Operations can only be referenced externally_)
+* Operations (_Operations can only be remote references_)
 
 ## Reuse strategy
 
-When reusing components in an API design, a pointer is created from the definition to target design.  The references are maintained in the structure, and can be updated by modifying the source definitions.  This is different from a "copy on design" approach where references are injected into the design itself.
+When reusing components in an API design, a reference is created from the definition to target entity. The references are maintained in the structure, and can be updated by modifying the source definitions. This is different from a "copy on design" approach where references are injected into the design itself.
 
 The reuse technique is transparent between JSON or YAML and is lossless when converting between the two.
 
 YAML anchors are technically allowed but break the general reuse strategy in OpenAPI Specification, since anchors are "injected" into a single document.  They are not recommended.
 
-Referenes can be made either internal to the OpenApi Specification file or to external files. 
-
 ## Techniques
 
 ### Guidelines for Referencing
 
-Whether you reference definitions internally or externally, you can never override or change their definitions from the referring ___location. The definitions can only be used as-is.
+All references should follow the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) specification.
+
+JSON Reference provides guidance on the resolution of references, notably:
+
+> If the URI contained in the JSON Reference value is a relative URI,
+then the base URI resolution MUST be calculated according to
+[RFC3986], section 5.2. Resolution is performed relative to the
+referring document.
+
+Whether you reference definitions locally or remote, you can never override or change their definitions from the referring ___location. The definitions can only be used as-is.
 
-#### Internal references
+#### Local references
 
-When referencing internally, the target references have designated locations:
+When referencing locally (within the current document), the target references should follow the conventions, as defined by the spec:
 
 * Parameters -> `#/parameters`
 * Responses -> `#/responses`
-* Models (and general Schema Objects) -> `#/definitions`
+* Definitions (Models/Schema) -> `#/definitions`
 
-All references are canonical and must be a qualified [JSON Pointer, per RFC6901](http://tools.ietf.org/html/rfc6901). For example, simply referencing a model `Pet` is not allowed, even if there are no other definitions of it in the file.
+An example of a local definition reference:
 
 _Example from https://github.com/OAI/OpenAPI-Specification/blob/master/examples/v2.0/json/petstore.json_
 ``` json
@@ -49,77 +56,11 @@ _Example from https://github.com/OAI/OpenAPI-Specification/blob/master/examples/
             }
 ```
 
-#### External references
+#### Remote references
 
-If your referenced file contains only one root-level definition, you can refer to the file directly.
+##### Relative path
 
-To reference the example below: 
-
-`"$ref": "definitions/Model.json""`
-
-or
-
-`"$ref": "https://my.company.com/definitions/Model.json"`.
-
-_Assuming file https://my.company.com/definitions/Model.json_
-```json
-{
-  "description": "A simple model",
-  "type": "object",
-  "properties": {
-    "id": {
-      "type": "integer"
-    }
-  }
-}
-```
-
-To reference `Model` in the example below:
-
-_Note this approach potentially combines URL, JSON Reference, and JSON Pointer_
-
-`"$ref": "definitions/models.json#/models/Model"`
-
- or 
- 
-`"$ref": "https://my.company.com/definitions/models.json#/models/Model"`
-
-
-_Assuming file https://my.company.com/definitions/models.json_
-```json
-{
-  "models": {
-    "Model": {
-      "description": "A simple model",
-      "type": "object",
-      "properties": {
-        "id": {
-          "type": "integer"
-        }
-    },
-    "Tag": {
-      "description": "A tag entity in the system",
-      "type": "object",
-      "properties": {
-        "name": {
-          "type": "string"
-        }
-      }
-    }
-  }
-}
-```
-
-#### External by relative reference
-
-All external relative references should follow the [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) specification.
-
-Per the JSON Reference spec:
-
-> If the URI contained in the JSON Reference value is a relative URI,
-then the base URI resolution MUST be calculated according to
-[RFC3986], section 5.2. Resolution is performed relative to the
-referring document.
+Files can be referred to in relative paths to the current document. 
 
 _Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json_
 
@@ -134,7 +75,7 @@ _Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/
 }
 ```
 
-External references may also utilize [JSON Pointer](http://tools.ietf.org/html/rfc6901) to reference properties within the relative external file.
+Remote references may also reference properties within the relative remote file.
 
 _Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/v2.0/json/petstore-separate/spec/swagger.json_
 ``` json
@@ -149,14 +90,12 @@ _Example from https://github.com/OAI/OpenAPI-Specification/tree/master/examples/
 ```
 
 
-#### External by URL
+##### URL
 
-External files can be hosted on an HTTP server (rather than the local file system). 
+Remote files can be hosted on an HTTP server (rather than the local file system). 
 
 One risk of this approach is that environment specific issues could arise if DNS is not taken into account (as the reference can only contain one hostname).
 
-Resolution of URLs should follow [RFC3986](https://tools.ietf.org/html/rfc3986).
-
 _Assuming file https://my.company.com/definitions/Model.json_
 ```json
 {
@@ -175,7 +114,7 @@ _Assuming file https://my.company.com/definitions/Model.json_
 }
 ```
 
-External references may also utilize a URL + JSON Pointer to reference properties within the external file.
+Remote references may also reference properties within the remote file.
 
 _Assuming file https://my.company.com/definitions/models.json_
 ```json
@@ -213,14 +152,14 @@ _Assuming file https://my.company.com/definitions/models.json_
 
 Reuse schema definitions by creating a repository of definitions.  This is done by simply hosting a file or set of files for commonly used definitions across a company or organization.
 
-Refer to [External references](#external-references) for referencing strategies.
+Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies.
 
 
 ### Parameters
 
 Similar to model schemas, you can create a repository of `parameters` to describe the common entities that appear throughout a set of systems.  
 
-Refer to [External references](#external-references) for referencing strategies.
+Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies.
 
 Using the same technique as above, you can host on either a single or multiple files.  For simplicity, the example below assumes a single file.
 
@@ -296,7 +235,7 @@ To include these parameters, you would need to add them individually as such:
 
 Again, Operations can be shared across files.  Although the reusability of operations will be less than with Parameters and models. For this example, we will share a common `health` resource so that all APIs can reference it:
 
-Refer to [External references](#external-references) for additional referencing strategies.
+Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies.
 
 ```json
 {
@@ -338,7 +277,7 @@ Remember, you cannot override the definitions, but in this case, you can add add
 
 ### Responses
 
-Refer to [External references](#external-references) for additional referencing strategies.
+Refer to [Guidelines for Referencing](#guidelines-for-referencing) for referencing strategies.
 
 Assume the file `responses.json`: