Complete rework of JSON Reference

Author: webron

versions/3.0.md

@@ -2212,10 +2212,9 @@ definitions:
 
 #### <a name="referenceObject"></a>Reference Object
 
-A simple object to allow referencing other definitions in the specification.
-It can be used to reference parameters and responses that are defined at the top level for reuse.
+A simple object to allow referencing other definitions in the specification, internally and externally.
 
-The Reference Object is a [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) that uses a [JSON Pointer](http://tools.ietf.org/html/rfc6901) as its value.
+The Reference Object is defined by [JSON Reference](https://tools.ietf.org/html/draft-pbryan-zyp-json-ref-03) and follows the same structure, behavior and rules.
 
 For this specification, reference resolution is done as defined by the JSON Reference specification and not by the JSON Schema specification.
 
@@ -2228,12 +2227,12 @@ Field Name | Type | Description
 
 ```json
 {
-	"$ref": "#/definitions/Pet"
+	"$ref": "#/components/definitions/Pet"
 }
 ```
 
 ```yaml
-$ref: '#/definitions/Pet'
+$ref: '#/components/definitions/Pet'
 ```
 
 ##### Relative Schema File Example
@@ -2244,7 +2243,7 @@ $ref: '#/definitions/Pet'
 ```
 
 ```yaml
-$ref: 'Pet.yaml'
+$ref: Pet.yaml
 ```
 
 ##### Relative Files With Embedded Schema Example
@@ -2255,7 +2254,7 @@ $ref: 'Pet.yaml'
 ```
 
 ```yaml
-$ref: 'definitions.yaml#/Pet'
+$ref: definitions.yaml#/Pet
 ```
 
 #### <a name="schemaObject"></a>Schema Object