addressing Henry's comments and merging Henry's branch
authorNandana Mihindukulasooriya <nandana.cse@gmail.com>
Fri, 13 Jun 2014 13:14:24 +0200
changeset 641 006a4e4d1b1d
parent 640 371d88c20262
child 642 e5d0e49ffdb5
addressing Henry's comments and merging Henry's branch
ldp-primer/bcget_res.txt
ldp-primer/bug_create_req.txt
ldp-primer/bug_create_s1.txt
ldp-primer/bug_create_s2.txt
ldp-primer/bug_delete_s1.txt
ldp-primer/create_cr_req.txt
ldp-primer/create_cr_s1.txt
ldp-primer/create_cr_s2.txt
ldp-primer/create_cr_s3.txt
ldp-primer/getbc_res.txt
ldp-primer/ic_bug_create_req.txt
ldp-primer/ic_bug_create_s1.txt
ldp-primer/ic_bug_create_s2.txt
ldp-primer/ic_product_lookup_resp.txt
ldp-primer/ldp-primer.html
ldp-primer/product_lookup_resp.txt
--- a/ldp-primer/bcget_res.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/bcget_res.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -1,7 +1,7 @@
 HTTP/1.1 200 OK 
 Content-Type: text/turtle; charset=UTF-8
-Link: <http://www.w3.org/ns/ldp#Resource>; rel='type'
 Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel='type'
+Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH
 Content- Length: 245
 ETag: W/'123456789'
   
@@ -16,8 +16,8 @@
 
 HTTP/1.1 200 OK 
 Content-Type: application/ld+json; charset=UTF-8
-Link: <http://www.w3.org/ns/ldp#Resource>; rel='type'
 Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel='type'
+Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH
 Content- Length: 255
 ETag: W/'123456789'
   
--- a/ldp-primer/bug_create_req.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/bug_create_req.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -2,6 +2,9 @@
 Host: example.org
 Content-Type: text/turtle
 Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
+
[email protected] dcterms: <http://purl.org/dc/terms/> .
[email protected] bt: <http://example.org/vocab/bugtracker#> .
  
 <> a bt:BugReport;
   dcterms:title "LDP Demo crashes when shutting down.";
--- a/ldp-primer/bug_create_s1.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/bug_create_s1.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -1,3 +1,7 @@
[email protected] ldp: <http://www.w3.org/ns/ldp#> .
[email protected] dcterms: <http://purl.org/dc/terms/> .
[email protected] bt: <http://example.org/vocab/bugtracker#> .
+
 </tracker/ldp-demo/> ldp:DirectContainer;
   ldp:membershipResource </tracker/ldp-demo/#it>;
   ldp:hasMemberRelation bt:hasBug;
--- a/ldp-primer/bug_create_s2.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/bug_create_s2.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -1,3 +1,6 @@
[email protected] dcterms: <http://purl.org/dc/terms/> .
[email protected] bt: <http://example.org/vocab/bugtracker#> .
+
 </tracker/ldp-demo/bug67> a bt:Bug;
   dcterms:title "Product A crashes when shutting down.";
   dcterms:creator </tracker/users/johndoe>;
--- a/ldp-primer/bug_delete_s1.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/bug_delete_s1.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -1,3 +1,7 @@
[email protected] ldp: <http://www.w3.org/ns/ldp#> .
[email protected] dcterms: <http://purl.org/dc/terms/> .
[email protected] bt: <http://example.org/vocab/bugtracker#> .
+
 </tracker/ldp-demo/> a ldp:DirectContainer;
   ldp:membershipResource </tracker/ldp-demo/#it>;
   ldp:hasMemberRelation bt:hasBug;
--- a/ldp-primer/create_cr_req.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/create_cr_req.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -3,6 +3,9 @@
 Content-Type: text/turtle
 Link: <http://www.w3.org/ns/ldp/BasicContainer>; rel='type'
 Slug: photos
+
[email protected] ldp: <http://www.w3.org/ns/ldp#> .
[email protected] dcterms: <http://purl.org/dc/terms/> .
  
 <> a ldp:Container, ldp:BasicContainer;
    dcterms:title "Photos of Alice" ; 
--- a/ldp-primer/create_cr_s1.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/create_cr_s1.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -1,3 +1,6 @@
[email protected] ldp: <http://www.w3.org/ns/ldp#> .
[email protected] dcterms: <http://purl.org/dc/terms/> .
+
 <http://example.org/alice/> a ldp:Container, ldp:BasicContainer ;
     dcterms:title "Alice’s data storage on the Web" ;
     ldp:contains <http://example.org/alice/foaf> .
--- a/ldp-primer/create_cr_s2.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/create_cr_s2.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -1,3 +1,6 @@
[email protected] ldp: <http://www.w3.org/ns/ldp#> .
[email protected] dcterms: <http://purl.org/dc/terms/> .
+
 <http://example.org/alice/> a ldp:Container, ldp:BasicContainer ;
     dcterms:title "Alice’s data storage on the Web";
     ldp:contains <http://example.org/alice/foaf> , <http://example.org/alice/photos/> .
--- a/ldp-primer/create_cr_s3.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/create_cr_s3.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -1,3 +1,6 @@
[email protected] ldp: <http://www.w3.org/ns/ldp#> .
[email protected] dcterms: <http://purl.org/dc/terms/> .
+
 <http://example.org/alice/photos/> a ldp:Container, ldp:BasicContainer;
   dcterms:title "Photos of Alice" ;
   dcterms:description "This container will contain photos of Alice." .  
--- a/ldp-primer/getbc_res.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/getbc_res.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -1,7 +1,7 @@
 HTTP/1.1 200 OK 
 Content-Type: text/turtle; charset=UTF-8
-Link: <http://www.w3.org/ns/ldp#Resource>; rel='type'
 Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel='type'
+Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH
 Content-Length: 250
 ETag: W/'123456789'
 	
@@ -15,8 +15,8 @@
 
 HTTP/1.1 200 OK 
 Content-Type: application/ld+json; charset=UTF-8
-Link: <http://www.w3.org/ns/ldp#Resource>; rel='type'
 Link: <http://www.w3.org/ns/ldp#BasicContainer>; rel='type'
+Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH
 Content-Length: 270
 ETag: W/'123456789'
 	
--- a/ldp-primer/ic_bug_create_req.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/ic_bug_create_req.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -1,6 +1,9 @@
 POST /tracker/ldp-demo/ HTTP/1.1
 Host: example.org
 Content-Type: text/turtle
+
[email protected] dcterms: <http://purl.org/dc/terms/> .
[email protected] bt: <http://example.org/vocab/bugtracker#> .
  
 <> a bt:BugReport;
    foaf:primaryTopic <#it>;
--- a/ldp-primer/ic_bug_create_s1.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/ic_bug_create_s1.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -1,3 +1,7 @@
[email protected] ldp: <http://www.w3.org/ns/ldp#> .
[email protected] dcterms: <http://purl.org/dc/terms/> .
[email protected] bt: <http://example.org/vocab/bugtracker#> .
+
 </tracker/ldp-demo/> ldp:IndirectContainer;
   ldp:membershipResource </tracker/ldp-demo/#it>;
   ldp:hasMemberRelation bt:hasBug;
--- a/ldp-primer/ic_bug_create_s2.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/ic_bug_create_s2.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -1,3 +1,7 @@
[email protected] ldp: <http://www.w3.org/ns/ldp#> .
[email protected] dcterms: <http://purl.org/dc/terms/> .
[email protected] bt: <http://example.org/vocab/bugtracker#> .
+
 </tracker/ldp-demo/bug67> a bt:Bug;
      dcterms:title "Product A crashes when shutting down.";
      dcterms:creator </tracker/users/johndoe>;
--- a/ldp-primer/ic_product_lookup_resp.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/ic_product_lookup_resp.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -1,10 +1,14 @@
 HTTP/1.1 200 OK 
 Content-Type: text/turtle; charset=UTF-8
-Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
 Link: <http://www.w3.org/ns/ldp#IndirectContainer>; rel="type"
+Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH
 Content-Length: 256
 ETag: W/"123456789"
 
[email protected] ldp: <http://www.w3.org/ns/ldp#> .
[email protected] dcterms: <http://purl.org/dc/terms/> .
[email protected] bt: <http://example.org/vocab/bugtracker#> .
+
 </tracker/ldp-demo/> a ldp:IndirectContainer;
   ldp:membershipResource <#it>;
   ldp:hasMemberRelation bt:hasBug;
@@ -19,8 +23,8 @@
 
 HTTP/1.1 200 OK 
 Content-Type: application/ld+json; charset=UTF-8
-Link: <http://www.w3.org/ns/ldp/Resource>; rel="type"
 Link: <http://www.w3.org/ns/ldp#IndirectContainer>; rel="type"
+Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH
 Content-Length: 278
 ETag: W/"123456789"
 
--- a/ldp-primer/ldp-primer.html	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/ldp-primer.html	Fri Jun 13 13:14:24 2014 +0200
@@ -431,7 +431,7 @@
         </tr>
         <tr>
           <td>HEAD</td>
-          <td>Only retrieve metainformation about a resource</td>
+          <td>Only retrieve meta-information about a resource</td>
         </tr>
       </tbody>
     </table>
@@ -445,11 +445,11 @@
 
       <p>First Alice looks up her storage by retrieving the LDP Basic Container assigned to her to hold her documents. Alice's LDP client does this by doing a GET request on the URI, http://example.org/alice/. </p>
 
-      <pre title="Request - basic container retreival" class='example' data-include='getbc.txt' data-oninclude='fixCode'></pre> 
+      <pre title="Request - basic container retrieval" class='example' data-include='getbc.txt' data-oninclude='fixCode'></pre> 
       
       <p>As her document storage was just created, it is an empty container. </p>
 
-      <pre title="Response - basic container retreival" class='example' data-include='getbc_res.txt' data-oninclude='fixCode'></pre> 
+      <pre title="Response - basic container retrieval" class='example' data-include='getbc_res.txt' data-oninclude='fixCode'></pre> 
       
       <p> As shown in the example, in addition to the RDF representation of the Basic Container using the requested media type the server provides an E-tag of the resource representation and Link headers advertising that the requested resource is indeed an LDP Basic Container and it will support the LDP interaction model. </p>
       
@@ -474,7 +474,6 @@
 Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH
 Accept-Post: text/turtle, application/ld+json, image/bmp, image/jpeg
 Accept-Patch: example/patch
-Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel=&#39;type&#39;
 Link: &lt;http://www.w3.org/ns/ldp#BasicContainer&gt;; rel=&#39;type&#39;     
       </pre> 
 
@@ -488,7 +487,7 @@
       <h2> Creating a RDF resource (POST an RDF resource to an LDP-BC) </h2> 
 
       <p>
-        Alice can uplaod a social profile document to her store, by POSTing her FOAF personal profile document to her LDP-BC at the root of her document store. Note, the Slug header offers the server a hint about URL of the resource to be created.  
+        Alice can upload a social profile document to her store, by POSTing her FOAF personal profile document to her LDP-BC at the root of her document store. Note, the Slug header offers the server a hint about URL of the resource to be created.  
       </p>
 
       <pre title="Request - creating a RDF resource" class='example' data-include='bccreate.txt' data-oninclude='fixCode'></pre> 
@@ -504,13 +503,13 @@
       <p> The response to the create request provides a Link to the newly created resource using the Location header. In this case, the server has honored the hint provided by the Slug header and created the new resource in the URL http://example.org </p>
       <p>Knowing the URL of the newly created resource, Alice can check the container again to confirm that the container correctly contains the newly created resource.</p>
 
-      <pre title="Request - basic container retreival after resource created" class="example">
+      <pre title="Request - basic container retrieval after resource created" class="example">
     GET /alice/ HTTP/1.1
     Host: example.org
     Accept: text/turtle
      </pre>
 
-     <pre title="Response - basic container retreival after resource created" class='example' data-include='bcget_res.txt' data-oninclude='fixCode'/>
+     <pre title="Response - basic container retrieval after resource created" class='example' data-include='bcget_res.txt' data-oninclude='fixCode'/>
      <p>
        The ldp:contains containment triple discloses the newly created resource in the response. 
      </p>
@@ -567,7 +566,6 @@
       <pre title="Response - updating a RDF resource" class="example"> 
 HTTP/1.1 204 No Content 
 Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel=&quot;type&quot; 
-ETag: W/&quot;123454322&quot;  
       </pre>
 
       <p>If the operation is successful as shown above, the document will be updated with new information.</p>
@@ -589,15 +587,13 @@
 
       <pre title="Response - deleting a RDF resource" class="example"> 
 HTTP/1.1 204 No Content 
-Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel=&quot;type&quot; 
-ETag: W/&quot;123454322&quot;  
    </pre>
    
-     <p> Once the document is deleted, the containment triple will be removed from the container. For example, after deleting the resource the container representation will be:</p>
+     <p> As well as deleting the resource, the server removes the containment triple from the container. For example, a subsequent GET request on the container will return a graph isomorphic to the one shown in the following representation::</p>
      
      <pre title="Container representation after resource deletion" class="example" data-include='bc_after_del.txt' data-oninclude='fixCode'></pre> 
      
-     <p> For any subsequent request on the resource after the deletion, the server will respond with the appropriate HTTP response code. </p>
+     <p> For any subsequent request on the deleted resource, the server will respond with the appropriate HTTP response code. </p>
       <pre title="Request - after deletion" class="example">
     GET /alice/avatar HTTP/1.1
     Host: example.org
@@ -611,7 +607,7 @@
 
     <section>
       <h3 id="meta-structure">Structural Manipulation (Child Containers)</h3>
-      <p>In order for the client to introduce hierachy to the management of documents, the document store allows creation of documents which are containers. That enables Alice can to create a container hierarchy to organise her documents. This can be done by POSTing (a child) container representation to a (parent) container. This enables Alice to create a child container which she intends to use for image storage.
+      <p>In order for the client to introduce hierarchy to the management of documents, the document store allows creation of documents which are containers. That enables Alice to create a container hierarchy to organise her documents. This can be done by POSTing (a child) container representation to a (parent) container. This enables Alice to create a child container which she intends to use for image storage.
       </p>
 
       <pre title="State of Alice's document store before creating the photo (child) container" class='example' data-include='create_cr_s1.txt' data-oninclude='fixCode'></pre>  
@@ -637,7 +633,7 @@
   <section id="bugtracker">
     <h1>Bug Tracker Example (LDP Direct containers)</h1>
 
-    <p>The previous section provided practical examples of basic LDP interactions using LDP Basic Containers. One of the limitations of LDP Basic Containers is that a fixed LDP vocabulary is used to assert the relations between a container and its contained resources. However, some scenarios require domain specific vocabulary to be used to list the members of a container. For example, an application which already used Linked Data and its own vocabulary may like continue using the same vocabulary when migrating to LDP protocol. LDP Direct containers introduce the concept of membership triples allowing the flexibility to define the form of the membership. One of these flexibility points is the ability to select the predicate of the membership triple which can be from a domain-specific vocabulary. This is done using the ldp:hasMemberRelation or ldp:isMemberOfRelation predicate of the Direct Containers.</p>
+    <p>The previous section provided practical examples of basic LDP interactions using LDP Basic Containers. One of the limitations of LDP Basic Containers is that a fixed LDP vocabulary is used to assert the relations between a container and its contained resources. However, some scenarios require domain specific vocabulary to be used to list the members of a container. For example, an application which already used Linked Data and its own vocabulary may like to continue using the same vocabulary when migrating to LDP protocol. LDP Direct containers introduce the concept of membership triples allowing the flexibility to define the form of the membership. One of these flexibility points is the ability to select the predicate of the membership triple which can be from a domain-specific vocabulary. This is done using the ldp:hasMemberRelation or ldp:isMemberOfRelation predicate of the Direct Containers.</p>
 
     <p>In addition, in some scenarios it is necessary to add relationships between the newly created resource and some other resource (which is not necessarily the container or another document / information resource). This allows to define relationship between any other information resource or non-information resource (real world thing) by defining the membership constant subject or the object URI of the membership triples using ldp:membershipResource predicate of the Direct Container. The usage of the ldp:hasMemberRelation predicate as well as the ldp:membershipResource will be explained in the following examples. </p>
 
@@ -737,10 +733,10 @@
       </tbody>
     </table>
     
-    <p> In the examples in this section, we will only focus on the container representation, creation and deletion of resources because that is where the Basic Containers, Direct Containers, and Indirect Containers have their differences. Other operations such as updating a resource would be similar to what was illustrated in the previous example.</p>
+    <p> In the examples in this section, we will only focus on the container representation, creation and deletion of resources because that is where the Basic Containers, Direct Containers, and Indirect Containers differ. Other operations such as updating a resource would be similar to what was illustrated in the previous example.</p>
 
     <section id="navandret">
-      <h2>Navigation and Retreival (GET on an LDP-DC)</h2>
+      <h2>Navigation and Retrieval (GET on an LDP-DC)</h2>
 
       <p>One of the main use cases of the example bug tracker is to list a given product's bugs. Assuming that a user got a URL of a product by out of band means, she can look it up to get more information including the bugs associated with it. To get the description of the product, a user (or her LDP client) can do a GET request on the URI of the known product resource. LDPR servers must provide text/turtle representations of the requested LDPRs and may provide other RDF format representations such as JSON-LD or RDF/XML using standard HTTP content negotiation.</p>
       <pre class="example" title="Request - Product Lookup" data-include='product_lookup_req.txt' data-oninclude='fixCode'></pre>
@@ -806,7 +802,6 @@
       <p>If the  delete is successful, the server will respond with a success status code.</p>
       <pre class="example">
  HTTP/1.1 204 No Content
- ETag: W/"123454322"  
         </pre>  
         
        <p> After the deletion, the representation of the container will look like the following</p> 
@@ -825,7 +820,7 @@
     <p> In this next example, we will use the same scenario as in the previous example, but change the container type to a LDP Indirect Container to show the differences between LDP Direct Containers and Indirect Containers and when to use LDP Indirect Containers. Though LDP Direct Containers provide the flexibility to define the constant membership URI (the subject of the membership triple when using ldp:hasMemberRelation or the object of the membership triple when using ldp:isMemberOfRelation) and the membership predicate, when creating members the member derived URI is always the newly created document URL. LDP Indirect containers provide more flexibility by allowing the member derived URI to be any resource; it could be either a non-information resource or a document other than the newly created resource. This done by defining the predicate to look for in the representation of the resource to be created by setting the ldp:insertedContentRelation predicate of the LDP Indirect Container. How this done will be explained in the following examples. </p>
 
     <section id="navandretext">
-      <h2>Navigation and Retreival (GET on an LDP-IC) </h2>
+      <h2>Navigation and Retrieval (GET on an LDP-IC) </h2>
       
       <p> Similar to the previous LDP-DC example, first we will retrieve the representation of the LDP Indirect Container.</p>
       
@@ -904,7 +899,12 @@
       <li><a href="https://dvcs.w3.org/hg/ldpwg/raw-file/default/Test%20Cases/LDP%20Test%20Cases.html">Linked Data Platform 1.0 Test Cases</a>[[LDP-TESTS]]</li>
     </ul>
 
-  </section>
+  </section>
+  
+  	<section class='appendix'>
+		<h2>Acknowledgements</h2>
+		<p>Many thanks to John Arwe (IBM), Ashok Malhotra (Oracle), and Henry Story (Apache Software Foundation) for their thorough review on the LDP Primer document and proposed corrections. We also like to thank all members of the Linked Data Platform WG for the valuable feedback. </p>
+	</section>
 
   <section class='appendix informative' id="history">
     <h1>Change History</h1>
--- a/ldp-primer/product_lookup_resp.txt	Thu Jun 12 18:53:50 2014 +0200
+++ b/ldp-primer/product_lookup_resp.txt	Fri Jun 13 13:14:24 2014 +0200
@@ -1,10 +1,14 @@
 HTTP/1.1 200 OK 
 Content-Type: text/turtle; charset=UTF-8
-Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
 Link: <http://www.w3.org/ns/ldp#DirectContainer>; rel="type"
+Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH
 Content-Length: 246  
 ETag: W/"123456789"
 
[email protected] ldp: <http://www.w3.org/ns/ldp#> .
[email protected] dcterms: <http://purl.org/dc/terms/> .
[email protected] bt: <http://example.org/vocab/bugtracker#> .
+
 < > ldp:DirectContainer;
   ldp:membershipResource <#it>;
   ldp:hasMemberRelation bt:hasBug;
@@ -18,8 +22,8 @@
 
 HTTP/1.1 200 OK 
 Content-Type: application/ld+json; charset=UTF-8
-Link: <http://www.w3.org/ns/ldp#Resource>; rel="type"
 Link: <http://www.w3.org/ns/ldp#DirectContainer>; rel="type"
+Allow: OPTIONS,HEAD,GET,POST,PUT,PATCH
 Content-Length: 315
 ETag: W/"123456789"