Wording changes

Author: geraintluff

proposals/json-schema-hypermedia.xml

@@ -225,8 +225,8 @@
                     </t>
                     <figure>
                         <preamble>
-                            For example, this schema describes a format for news posts, accessed via HTTP.
-                            The links describe how to access the comments for a news post, how to search the comments, and how to submit new comments, all with the same URI:</preamble>
+                            For example, this schema describes a format for blog posts, accessed via HTTP.
+                            The links describe how to access the comments for the post, how to search the comments, and how to submit new comments, all with the same URI:</preamble>
                         <artwork>
 <![CDATA[{
     "title": "News post",
@@ -256,7 +256,8 @@
             }
         },
         {
-            "rel": "post-comment",
+            "title": "Post a comment",
+            "rel": "create",
             "href": "/{id}/comments",
             "method": "POST",
             "schema": {
@@ -275,9 +276,16 @@
                     </figure>
                     <t>
                         If the client follows the first link, the URI might be expanded to "/15/comments".
-                        For the second link, the method is "GET" (the default for HTTP) so the parameters are added to the URL to produce something like: "/15/comments?searchTerm=JSON&itemsPerPage=50".
-                        The third link might have a URI of "/15/comments", but the text content of the new comment is posted as JSON.
+                        For the second link, the method is "GET" (the default for HTTP) so a client following this link would add the parameters to the URL to produce something like: "/15/comments?searchTerm=JSON&amp;itemsPerPage=50".
+                        The third link defines a possible interaction where a client would POST to a URI (such as "/15/comments"), where the post-data was a JSON representation of the new comment, for example:
                     </t>
+                    <figure>
+                        <artwork>
+<![CDATA[{
+    "message": "This is an example comment"
+}]]>
+                        </artwork>
+                    </figure>
                 </section>
             </section>