Merge pull request #125 from apiaryio/pksunkara/1A7

Lazy Referencing for Resource Models. To be released with Snow Crash v0.16.0

API Blueprint Specification.md

@@ -1,12 +1,12 @@
 ---
 
 Author: [email protected]
-Version: 1A6
+Version: 1A7
 
 ---
 
 # API Blueprint
-#### Format 1A revision 6
+#### Format 1A revision 7
 
 ## [I. API Blueprint Language](#def-api-blueprint-language)
 1. [Introduction](#def-introduction)
@@ -366,7 +366,7 @@ This section **should** include at least one following nested sections:
 If there is no nested section the content of the payload section is considered as content of the [Body section](#def-body-section).
 
 #### Referencing
-Instead of providing a payload section content a previously defined [model payload section](#def-model-section) can be referenced using the Markdown implicit [reference syntax][]:
+Instead of providing a payload section content a [model payload section](#def-model-section) can be referenced using the Markdown implicit [reference syntax][]:
 
     [<identifier>][]
 
@@ -613,7 +613,7 @@ Defined by the `Model` keyword followed by an optional media type:
 A [resource manifestation](http://www.w3.org/TR/di-gloss/#def-resource-manifestation) - one exemplar representation of the resource in the form of a [payload](#def-payload-section).
 
 #### Referencing
-The payload defined in this section **may** be referenced later using parent section's identifier. You can refer to this payload in any of the following [Request](#def-request-section) or [Response](#def-response-section) payload sections using the Markdown implicit [reference syntax][].
+The payload defined in this section **may** be referenced in any response or request section in the document using parent section's identifier. You can refer to this payload in any of the following [Request](#def-request-section) or [Response](#def-response-section) payload sections using the Markdown implicit [reference syntax][].
 
 #### Example
 

Tutorial.md

@@ -246,7 +246,7 @@ The *"id"* variable of the URI template is a parameter to every action on this r
                     "content": "String contents"
                 }
 
-Resource Model is an example representation of the Gist resource. It can be referenced later at any point where a response (or request) payload is expected. A resource model has *exactly* the same structure as a response payload. In this case it also includes additional description. A Resource Model may not include a response status code.
+Resource Model is an example representation of the Gist resource. It can be referenced elsewhere at any point where a response (or request) payload is expected. A resource model has *exactly* the same structure as a response payload. In this case it also includes additional description. A Resource Model may not include a response status code.
 
 <a name="refer_model"></a>
 #### Referring the Resource Model
@@ -258,7 +258,7 @@ Resource Model is an example representation of the Gist resource. It can be refe
 
 With Gist Resource Model in place it is super easy to define an action that retrieves a single gist.
 
-> **NOTE:** The syntax for referencing a resource model is `[<resource identifier>][]`.  You can only refer to *already defined models*. The model must be referred as "whole" - you can't reuse just a model's body or headers.
+> **NOTE:** The syntax for referencing a resource model is `[<resource identifier>][]`. The model must be referred as "whole" - you can't reuse just a model's body or headers.
 
 ## Modifying a Resource
 Let's add an action to our Gist Resource that will allow us to modify its state and another action that deletes a Gist Resource as whole.

examples/8. Resource Model.md

@@ -3,7 +3,7 @@ FORMAT: 1A
 # Resource Model API
 Resource model is a [resource manifestation](http://www.w3.org/TR/di-gloss/#def-resource-manifestation). One particular representation of your resource. 
 
-Furthermore, in API Blueprint, any `resource model` you have defined can be referenced later saving you lots of time maintaining your API blueprint. You simply define a resource model as any payload (e. g. [request](https://github.com/apiaryio/api-blueprint/blob/master/examples/6.%20Requests.md) or [response](https://github.com/apiaryio/api-blueprint/blob/master/examples/5.%20Responses.md)) and then reference it later where you would normally write a `request` or `response`.
+Furthermore, in API Blueprint, any `resource model` you have defined can be referenced in a request or response section, saving you lots of time maintaining your API blueprint. You simply define a resource model as any payload (e. g. [request](https://github.com/apiaryio/api-blueprint/blob/master/examples/6.%20Requests.md) or [response](https://github.com/apiaryio/api-blueprint/blob/master/examples/5.%20Responses.md)) and then reference it later where you would normally write a `request` or `response`.
 
 ## API Blueprint
 + [Previous: Parameters](7.%20Parameters.md)