--- a/ldp-primer/ldp-primer.html Sun Jun 01 09:31:35 2014 +0200
+++ b/ldp-primer/ldp-primer.html Sun Jun 01 11:12:50 2014 +0200
@@ -322,17 +322,25 @@
<img src="images/resources.png" />
</p>
<p>
- The LDP protocols covers read and write interactions with Resources. Writable aspects include creation of new resources (using POST or PUT), updates (using PUT or PATCH), deletion of resources and importantly creation. Resource creation is an essential feature providing structured creation of resources. Affordances published by the server show that some Resources can be used to create other Resources. This common pattern is often seen in cases where one resource is be made up of a number of others, e.g. a Document Store consists of Documents, a Bug Tracker consists of Bugs, a Photo Album consists of Photos, a Networth of a person consists of Assets and Liabilities. This special kind of Resource is a Container (LDPC), and this is able to respond to requests to create new resources. During creation the created resource is appended to its Container and a containment link between the Container and the new entry is made.
+ The LDP protocols covers read and write interactions with Resources.
+ Writable aspects include creation of new resources (using POST or PUT), updates (using PUT or PATCH), deletion of resources and importantly creation.
+ Resource creation is an essential feature providing structured creation of resources.
+Affordances published by the server show that some Resources can be used to create other Resources.
+ This common pattern is often seen in cases where one resource is be made up of a number of others, e.g. a Document Store consists of Documents, a Bug Tracker consists of Bugs, a Photo Album consists of Photos, a Networth of a person consists of Assets and Liabilities.
+ This special kind of Resource is a Container (LDPC), and this is able to respond to requests to create new resources. During creation the created resource is appended to its Container and a containment link between the Container and the new entry is made.
</p>
<p>
- Therefore a LDPC is a specialization of a LDP-RS representing a collection of links to LDPRs or information resources [[WEBARCH]] that responds to client requests for creation, modification, and/or enumeration of its linked members and documents. The simplest container is the Basic Container (LDP-BC). It defines the basic containment described using generic vocabularly. This can be used in a generic storage service to manage a containment hierarchy of arbitrary resources.
+ Therefore a LDPC is a specialization of a LDP-RS representing a collection of links to LDPRs or information resources [[WEBARCH]] that responds to client requests for creation, modification, and/or enumeration of its linked members and documents.
+ The simplest container is the Basic Container (LDP-BC).
+ It defines the basic containment described using generic vocabularly. This can be used in a generic storage service to manage a containment hierarchy of arbitrary resources.
</p>
<figure id="fig-bc">
<img src="images/bc.png" alt=".." />
<figcaption>Generic document storage using a Basic Container.</figcaption>
</figure>
<p>
- Such servers do not impose any restriction on LDPRs and generally act as storage systems without any domain specific application logic and vocabularies. The first scenarion in this document concerns a document storage system based on Basic Containers.
+ Such servers do not impose any restriction on LDPRs and generally act as storage systems without any domain specific application logic and vocabularies.
+ The first scenarion in this document concerns a document storage system based on Basic Containers.
</p>
<p>
A Direct Container allows to use some domain specific vocabulary to relate the resources of the hierarchy. The additional assertion is called the membership property.
@@ -356,12 +364,15 @@
<figcaption>Managing multiple facets of a Bug with two Direct Containers.</figcaption>
</figure>
<p>
- Existing applications with their own data model and business logic can expose their data using the LDP specification. These systems impose restrictions on LDPRs since the LDP interaction should be compliant with the underlying business logic and data model. The bug tracker example presented in the latter part of the primer is an example of an application specific LDP server.
+ Existing applications with their own data model and business logic can expose their data using the LDP specification.
+ These systems impose restrictions on LDPRs since the LDP interaction should be compliant with the underlying business logic and data model.
+ The bug tracker example presented in the latter part of the primer is an example of an application specific LDP server.
</p>
<p class="note">Formal definitions of two terms LDPR and LDPC and other concepts introduced by LDP can be found in the 'Terminology' section of the Linked Data Platform 1.0 specification [[LDP]]</p>
- <p>The following provide a set of examples to show the Linked Data Platform interactions. Note, this is a primer and should not be considered as a canonical example of ideal LDP modeling.</p>
+ <p>The following provide a set of examples to show the Linked Data Platform interactions.
+ Note, this is a primer and should not be considered as a canonical example of ideal LDP modeling.</p>
</section>
@@ -369,10 +380,18 @@
<h1>Online document store example (LDP Basics)</h1>
<p>
- This section provides a set of examples of using an online document store application. These examples will demonstrate the behaviour of both types of LDPRs and LDP Basic Containers. Registration with the online document store application by a user results in some data storage space (a root Basic Container) where web resources that are supported by Linked Data Platform can be stored. Using this root Basic Container a user can create new documents and also child containers to further organize her documents stored in this application.
+ This section provides a set of examples of using an online document store application.
+ These examples will demonstrate the behaviour of both types of LDPRs and LDP Basic Containers.
+ Registration with the online document store application by a user results in some data storage space (a root Basic Container) where web resources that are supported by Linked Data Platform can be stored.
+ Using this root Basic Container a user can create new documents and also child containers to further organize her documents stored in this application.
+
</p>
<p>
- APIs of web applications are commonly documented by listing valid operations which can operate on URLs, where the URLs are described as templates. A description of a LDP based document store is contained in the following table. We note with emphasis that it is important for servers to use links as the main mechanism to reveal the location of resources. If it would be necessary to encode such templates into client applications, this would be a strong indicator that the design breaches a number of good design principles. </p>
+ APIs of web applications are commonly documented by listing valid operations which can operate on URLs, where the URLs are described as templates.
+ A description of a LDP based document store is contained in the following table.
+ We note with emphasis that it is important for servers to use links as the main mechanism to reveal the location of resources.
+ If it would be necessary to encode such templates into client applications, this would be a strong indicator that the design breaches a number of good design principles.
+ </p>
</p>
<table class="simple">
@@ -441,13 +460,19 @@
</table>
<p>
- In this example, we will see how Alice, a user of this system, does read / write management of documents using the LDP protocol. A typical interaction with the system would start with Alice registering as a user. It is likely that registration would be a LDP based interaction, but this aspect is out of scope of this example. A consequence of the registration is allocation of space for the storage of documents, and communication of this URL to the user, e.g. a basic container at http://data.example.org/alice/. This section describes a typical flow of interactions where Alice firsts reads the root document and discovers its affordances. This is followed by subsequent examples of creation, update and delete, and finishes with how the client is able to create nested structure from the containers.
+ In this example, we will see how Alice, a user of this system, does read / write management of documents using the LDP protocol.
+ A typical interaction with the system would start with Alice registering as a user.
+ It is likely that registration would be a LDP based interaction, but this aspect is out of scope of this example.
+ A consequence of the registration is allocation of space for the storage of documents, and communication of this URL to the user, e.g. a basic container at http://data.example.org/alice/.
+ This section describes a typical flow of interactions where Alice firsts reads the root document and discovers its affordances.
+ This is followed by subsequent examples of creation, update and delete, and finishes with how the client is able to create nested structure from the containers.
</p>
<section id="filelookup">
<h2>Looking up a basic container (GET on an LDP-BC) </h2>
- <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://data.example.org/alice/. </p>
+ <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://data.example.org/alice/. </p>
<pre title="Request - basic container retreival" class='example' data-include='getbc.txt' data-oninclude='fixCode'></pre>
@@ -455,7 +480,8 @@
<pre title="Response - basic container retreival" 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>
+ <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>
<p class="note">The Linked Data Platform 1.0 specification [[LDP]] says that all LDP servers MUST support Turtle media type for LDP-RS resources and SHOULD support JSON-LD media type.</p>
@@ -465,7 +491,8 @@
<h2> Discovering the affordances (OPTIONS on an LDP-BC) </h2>
<p>
- Now, Alice wants to know what she can do in her document space. She can use the OPTIONS operation to learn of the permitted operations LDP-BC that she retrieved in the previous example.
+ Now, Alice wants to know what she can do in her document space.
+ She can use the OPTIONS operation to learn of the permitted operations LDP-BC that she retrieved in the previous example.
</p>
<pre title="Request - retreiving OPTIONS of a basic container" class='example'>
@@ -483,9 +510,12 @@
Content-Length: 0
</pre>
- <p>According to the response, HTTP operations {OPTIONS,HEAD, GET,POST,PUT,PATCH} are allowed on her root container. In addition to the allowed operations, Accept-Post and Accept-Patch provides which media types are supported by the respective operations. The rel="type" Link header advertises that this resource supports LDP protocol and it is an LDP Basic Container.</p>
+ <p>According to the response, HTTP operations {OPTIONS,HEAD, GET,POST,PUT,PATCH} are allowed on her root container.
+ In addition to the allowed operations, Accept-Post and Accept-Patch provides which media types are supported by the respective operations.
+ The rel="type" Link header advertises that this resource supports LDP protocol and it is an LDP Basic Container.</p>
- <p>In this case, the response tells Alice's LDP client that this is an LDP-Basic Container and the container allows her to POST things of both RDF types (text/turtle, application/ld+json) and images (image/bmp and image/jpeg).</p>
+ <p>In this case, the response tells Alice's LDP client that this is an LDP-Basic Container and the container allows her to POST things of both RDF types (text/turtle, application/ld+json) and images (image/bmp and image/jpeg).
+</p>
</section>
@@ -493,7 +523,8 @@
<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 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.
</p>
<pre title="Request - creating a RDF resource" class='example' data-include='bccreate.txt' data-oninclude='fixCode'></pre>
@@ -507,7 +538,8 @@
Content-Length: 0
</pre>
<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://data.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>
+ <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">
GET /alice/ HTTP/1.1
@@ -525,7 +557,8 @@
<section>
<h2> Creating a non-RDF (binary) resource (POST an image to an LDP-BC) </h2>
- <p>Next, Alice wants to upload a photo of her to the document storage. She can create an image by POSTing it in the same way she created the RDF document.</p>
+ <p>Next, Alice wants to upload a photo of her to the document storage.
+ She can create an image by POSTing it in the same way she created the RDF document.</p>
<pre title="Request - creating a non-RDF resource" class="example">
POST /alice/ HTTP/1.1
@@ -548,9 +581,14 @@
<p> </p>
- <p>The outcome of creating a non-RDF is similar to creating a RDF resource. If successful, the server will return a 201 success code with a Location header that points to the created resource. Furthermore, in the case of binary resources the server may create an additional file to maintain the metadata about the binary file. In the above example, the server creates a new LDP-RS to maintain metadata about the binary resource such as creation date, owner, etc. and this metadata resource is advised using a Link header with the relation "describedby". </p>
+ <p>The outcome of creating a non-RDF is similar to creating a RDF resource.
+ If successful, the server will return a 201 success code with a Location header that points to the created resource.
+ Furthermore, in the case of binary resources the server may create an additional file to maintain the metadata about the binary file.
+ In the above example, the server creates a new LDP-RS to maintain metadata about the binary resource such as creation date, owner, etc. and this metadata resource is advised using a Link header with the relation "describedby". </p>
- <p> Similar to creating a RDF resource (LDP-RS), a containment triple will be added to the container when a non-RDF (LDP-NR) is created. Thus, the representation of the LDP container after creating the image looks like the following. </p>
+ <p> Similar to creating a RDF resource (LDP-RS), a containment triple will be added to the container when a non-RDF (LDP-NR) is created.
+ Thus, the representation of the LDP container after creating the image looks like the following.
+ </p>
<pre title="Container representation after the non-RDF resource creation" class='example' data-include='bc_after_bin.txt' data-oninclude='fixCode'></pre>
</section>
@@ -565,8 +603,11 @@
-->
- <p>After creating the image as shown in the previous example, Alice now wants to update her FOAF profile with a link to the image. After retrieving her FOAF profile using a HTTP GET operation, she uses HTTP PUT to update the document by amending the RDF with a link to her photo.</p>
- <p> In this example, Alice's LDP client send the E-tag of the resource representation that it retrieved previously to prevent any lost update problems. </p>
+ <p>After creating the image as shown in the previous example, Alice now wants to update her FOAF profile with a link to the image.
+ After retrieving her FOAF profile using a HTTP GET operation, she uses HTTP PUT to update the document by amending the RDF with a link to her photo.
+</p>
+ <p> In this example, Alice's LDP client send the E-tag of the resource representation that it retrieved previously to prevent any lost update problems.
+ </p>
<pre title="Request - updating a RDF resource" class="example" data-include='foafupdate.txt' data-oninclude='fixCode'></pre>
<pre title="Response - updating a RDF resource" class="example">
@@ -598,11 +639,14 @@
ETag: W/"123454322"
</pre>
- <p> Once the document is deleted, the containment triple will be removed from the container. For example, after the deleting the resource the container representation will be as the following. </p>
+ <p> Once the document is deleted, the containment triple will be removed from the container.
+ For example, after the deleting the resource the container representation will be as the following.
+ </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 resource after the deletion, 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
@@ -616,14 +660,20 @@
<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 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>
<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>
- <p>To create a new container for managing photos, Alice POSTs a representation of a container (LDP-BC) to the root container. Alice express her intention that the newly created resource should be an LDP Basic Container by including a Link header in the request with the relationship 'type'. </p>
+ <p>To create a new container for managing photos, Alice POSTs a representation of a container (LDP-BC) to the root container.
+ Alice express her intention that the newly created resource should be an LDP Basic Container by including a Link header in the request with the relationship 'type'.
+ </p>
<pre title="Request - creating a new container" class='example' data-include='create_cr_req.txt' data-oninclude='fixCode'></pre>
- <p>If the create is successful, the server responds with location of the newly created container for the photos.</p>
+ <p>If the create is successful, the server responds with location of the newly created container for the photos.
+</p>
<pre title="Response - creating the new container" class="example">
HTTP/1.1 201 Created
Location: /alice/photos/
@@ -642,14 +692,27 @@
<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 the the 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 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 the the 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 a 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>
+ <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 a 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>
<p class="note">For more information on information resources (documents) vs real world entities (things) separation please refer to <a href="http://www.w3.org/TR/webarch/#id-resources">Web Arch (Section 2.2. URI/Resource Relationships) </a>, , <a href="http://www.w3.org/TR/cooluris/#semweb">Cool URIs (Section 3. URIs for Real-World Objects)</a>, <a href="http://www.w3.org/TR/urls-in-data/#landing-pages">URLs in Data (Section 3. Landing Pages and Records)</a>.</p>
<p>
- The examples in this section will revolve around a very simple Bug Tracker application. Bug Tracker application records the bugs of several products allowing reporting, updating and deleting bugs and products. In contrast to the online document store example, the bug tracker wants to use a simple domain vocabulary, e.g. has_bug, to express membership relationships in the containers. LDP provides the additional interaction capability in the protocol to add the domain specific triples based on the properties defined in the LDP Direct Container.
+ The examples in this section will revolve around a very simple Bug Tracker application.
+ Bug Tracker application records the bugs of several products allowing reporting, updating and deleting bugs and products.
+ In contrast to the online document store example, the bug tracker wants to use a simple domain vocabulary, e.g. has_bug, to express membership relationships in the containers.
+LDP provides the additional interaction capability in the protocol to add the domain specific triples based on the properties defined in the LDP Direct Container.
+
</p>
<p>A RESTful API for a simple Bug Tracker system might be described as follows.</p>
@@ -742,27 +805,42 @@
</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 will 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 have their differences.
+ Other operations such as updating a resource will be similar to what was illustrated in the previous example.
+</p>
<section id="navandret">
<h2>Navigation and Retreival (GET on an LDP-DC)</h2>
- <p>One of the main use cases of the example bug tracker is to list of the bugs of a given product. 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>
+ <p>One of the main use cases of the example bug tracker is to list of the bugs of a given product.
+ 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>
<p>If the product resource is available, the server responds with the RDF representation of the Direct Container that corresponds to the given product using the requested media type,
<code>text/turtle</code> or <code>application/ld+json</code> in this case.</p>
<pre title="Response - Product Lookup" class='example' data-include='product_lookup_resp.txt' data-oninclude='fixCode'></pre>
- <p>The representation of the product contains both information about the product such as the title and the bugs associated with the product and information about the product description such as the title of the product description and other properties of the LDP Container. </p>
+ <p>The representation of the product contains both information about the product such as the title and the bugs associated with the product and information about the product description such as the title of the product description and other properties of the LDP Container.
+ </p>
- <p>As you can see from the Link Header that is returned and the RDF representation of the container, this example uses an LDP Direct Container. LDP-DCs contain both containment triples and membership triples and provide the flexibility to the applications to use domain specific vocabulary in the membership triples. For example, in the above example the LDP-DC manages the member relationship, (<?productURI>, bt:hasBug, <?bugURI>), using the application-specific vocabulary term, bt:hasBug. This is done by defining the ldp:hasMemberRelation predicate of the Direct Container to bt:hasBug (<?directContainerURI>, ldp:hasMemberRelation, bt:hasbug). </p>
+ <p>As you can see from the Link Header that is returned and the RDF representation of the container, this example uses an LDP Direct Container.
+ LDP-DCs contain both containment triples and membership triples and provide the flexibility to the applications to use domain specific vocabulary in the membership triples.
+ For example, in the above example the LDP-DC manages the member relationship, (<?productURI>, bt:hasBug, <?bugURI>), using the application-specific vocabulary term, bt:hasBug.
+ This is done by defining the ldp:hasMemberRelation predicate of the Direct Container to bt:hasBug (<?directContainerURI>, ldp:hasMemberRelation, bt:hasbug).
+ </p>
- <p class="note"> Direct Container shown in the above example has the membership triple pattern ( membership-constant-URI , membership-predicate , member-derived-URI ) using ldp:hasMemberRelation where the constant membership is resource is in the subject of the triple and the newly created resources will be added as the object of the triple. It is also possible for the Direct Container to have the membership triple pattern ( member-derived-URI , membership-predicate , membership-constant-URI ) using ldp:isMemberOfRelation predicate where the constant member resource will be the object of the triple and the newly created resource will be added as the subject of the triple. </p>
+ <p class="note"> Direct Container shown in the above example has the membership triple pattern ( membership-constant-URI , membership-predicate , member-derived-URI ) using ldp:hasMemberRelation where the constant membership is resource is in the subject of the triple and the newly created resources will be added as the object of the triple.
+ It is also possible for the Direct Container to have the membership triple pattern ( member-derived-URI , membership-predicate , membership-constant-URI ) using ldp:isMemberOfRelation predicate where the constant member resource will be the object of the triple and the newly created resource will be added as the subject of the triple.
+ </p>
- <p> In addition, in this example the bugs are associated with the product resource (a non-information resource with a # URI) and not with the product description Direct Container itself. This is done by defining the ldp:membershipResource predicate of the LDP Direct Container as the the product non-information resource URI (<?directContainerURI>, ldp:membershipResource, </tracker/product1/#it>). By doing so one can define the subject of the membership triple any resource of interest.
+ <p> In addition, in this example the bugs are associated with the product resource (a non-information resource with a # URI) and not with the product description Direct Container itself.
+ This is done by defining the ldp:membershipResource predicate of the LDP Direct Container as the the product non-information resource URI (<?directContainerURI>, ldp:membershipResource, </tracker/product1/#it>).
+ By doing so one can define the subject of the membership triple any resource of interest.
</p>
- <p>The next example illustrates the behaviour of LDP Direct containers when new resources are created and how aforementioned predicates of the Direct Containers affect the interaction model of LDP.</p>
+ <p>The next example illustrates the behaviour of LDP Direct containers when new resources are created and how aforementioned predicates of the Direct Containers affect the interaction model of LDP.
+</p>
<!-- <p>Looking up a bug is similar to looking up a product. Based on links in the representation of the Product, the client uses GET to navigate to a known Bug resource.</p>
@@ -778,22 +856,28 @@
<section>
<h3 id="BugCreate">Creation (POST a resource to an LDP-DC)</h3>
- <p>Continuing from the previous example, we can report a Bug against "LDP Demo" product by creating a Bug report (an LDPR representing the bug) under the "LDP Demo" product description LDPC by posting RDF representation of the Bug report to the LDPC associated with the product description. </p>
+ <p>Continuing from the previous example, we can report a Bug against "LDP Demo" product by creating a Bug report (an LDPR representing the bug) under the "LDP Demo" product description LDPC by posting RDF representation of the Bug report to the LDPC associated with the product description.
+ </p>
<pre title="A request for creating a bug" class='example' data-include='bug_create_req.txt' data-oninclude='fixCode'></pre>
- <p>If the creation is successful, the server responds with location of the newly created resource.</p>
+ <p>If the creation is successful, the server responds with location of the newly created resource.
+</p>
<pre title="A response of creating new a bug" class='example' data-oninclude='fixCode'>
HTTP/1.1 201 Created
Location: /tracker/ldp-demo/67
Content-Length: 0
</pre>
- <p>If the creation fails, the server will respond with an appropriate status code depending on the error. If successful, the LDP Demo product description LDPC will have the following representation after the creation of new resource.</p>
+ <p>If the creation fails, the server will respond with an appropriate status code depending on the error.
+ If successful, the LDP Demo product description LDPC will have the following representation after the creation of new resource.
+</p>
<pre title="The state of the product LDPC after the bug creation" class='example' data-include='bug_create_s1.txt' data-oninclude='fixCode'></pre>
- <p> As you can see two new triples are added to the container. That is (</tracker/ldp-demo/>, <ldp:contains>, </tracker/ldp-demo/bug67>) and
- (</tracker/ldp-demo/#it>, <bt:hasbug>, </tracker/ldp-demo/bug67>). The former is added in any type of container and the latter is defined by the direct
- container properties. </p>
- <p>And the created Bug resource will have the following representation. Note that server has added a server managed property, creation date (dcterms:created), and a default value for the state (bt:isInState) to the Bug in addition to what was being POSTed.</p>
+ <p> As you can see two new triples are added to the container.
+ That is (</tracker/ldp-demo/>, <ldp:contains>, </tracker/ldp-demo/bug67>) and (</tracker/ldp-demo/#it>, <bt:hasbug>, </tracker/ldp-demo/bug67>).
+ The former is added in any type of container and the latter is defined by the direct container properties. </p>
+ <p>And the created Bug resource will have the following representation.
+ Note that server has added a server managed property, creation date (dcterms:created), and a default value for the state (bt:isInState) to the Bug in addition to what was being POSTed.
+</p>
<pre title="The state of the bug LDPR" class='example' data-include='bug_create_s2.txt' data-oninclude='fixCode'></pre>
</section>
@@ -808,7 +892,8 @@
Host: example.org
If-Match: W/"123454322"
</pre>
- <p>If the delete is successful, the server will respond with a success status code.</p>
+ <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"
@@ -818,7 +903,8 @@
<pre title="The state of the product LDPC after the bug deletion" class='example' data-include='bug_delete_s1.txt' data-oninclude='fixCode'></pre>
- <p> As seen from the LDP Direct Container representation above both containment triple (</tracker/ldp-demo/>, ldp:contains, </tracker/ldp-demo/bug3>) and the membership triple (</tracker/ldp-demo/#it>, bt:hasBug, </tracker/ldp-demo/bug3>) are removed from the container representation. </p>
+ <p> As seen from the LDP Direct Container representation above both containment triple (</tracker/ldp-demo/>, ldp:contains, </tracker/ldp-demo/bug3>) and the membership triple (</tracker/ldp-demo/#it>, bt:hasBug, </tracker/ldp-demo/bug3>) are removed from the container representation.
+ </p>
</section>
@@ -827,18 +913,31 @@
<section id="bugtrackerextd">
<h1>Extended Bug Tracker Example (LDP Indirect containers)</h1>
- <p> In this example, we will use the same scenario as in the previous example but using an 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, the member derived URI or the URI of the member is always set to the newly created document URL. LDP Indirect containers provide more flexibility by allowing the member URI to be any resource i.e. 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>
+ <p> In this example, we will use the same scenario as in the previous example but using an 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, the member derived URI or the URI of the member is always set to the newly created document URL.
+ LDP Indirect containers provide more flexibility by allowing the member URI to be any resource i.e. 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>
- <p> Similar to the previous LDP-DC example, first we will retrieve the representation of the LDP Indirect Container.</p>
+ <p> Similar to the previous LDP-DC example, first we will retrieve the representation of the LDP Indirect Container.
+</p>
<pre class="example" title="Product lookup request" data-include='product_lookup_req.txt' data-oninclude='fixCode'></pre>
- <p> As a response to the GET request, the server responds with the representation of the product description container.</p>
+ <p> As a response to the GET request, the server responds with the representation of the product description container.
+</p>
<pre title="HTTP response for product lookup" class='example' data-include='ic_product_lookup_resp.txt' data-oninclude='fixCode'></pre>
- <p> Now the product container is an LDP Indirect container and we can notice one main difference. The container has an additional predicate called "ldp:insertedContentRelation". Further, we can notice that the object of the containment triples and the membership triples are not the same. While the object of the containment triple is the same (e.g. </tracker/ldp-demo/bug3>, an information resource) the object of the membership triple is now (e.g. </tracker/ldp-demo/bug3#it>, a non-information resource or real world thing). This distinction is because of the ldp:insertedContentRelation definition. How this works will be explained in the next example on creating a new resource. </p>
+ <p> Now the product container is an LDP Indirect container and we can notice one main difference.
+ The container has an additional predicate called "ldp:insertedContentRelation".
+ Further, we can notice that the object of the containment triples and the membership triples are not the same.
+ While the object of the containment triple is the same (e.g. </tracker/ldp-demo/bug3>, an information resource) the object of the membership triple is now (e.g. </tracker/ldp-demo/bug3#it>, a non-information resource or real world thing).
+This distinction is because of the ldp:insertedContentRelation definition.
+ How this works will be explained in the next example on creating a new resource.
+ </p>
</section>
<!-- end navandretext -->
@@ -846,21 +945,27 @@
<section id="creationext">
<h3 id="IndirectCreate">Creation (POST a resource to an LDP-IC) </h3>
- <p>Continuing from the previous example, we can report a Bug Report against 'LDP demo' product by creating a Bug Report LDPR under the 'LDP Demo' product description LDPC.</p>
+ <p>Continuing from the previous example, we can report a Bug Report against 'LDP demo' product by creating a Bug Report LDPR under the 'LDP Demo' product description LDPC.
+</p>
- <p>The client POSTs a representation of a Bug to the Bug Tracker LDPC.</p>
+ <p>The client POSTs a representation of a Bug to the Bug Tracker LDPC.
+</p>
<pre title="A request for creating a bug" class='example' data-include='ic_bug_create_req.txt' data-oninclude='fixCode'></pre>
- <p> One thing to note is that the representation of the resource to be created contain a triple (< >, foaf:primaryTopic , <#it>). If the create is successful, the server responds with location of the newly created resource.</p>
+ <p> One thing to note is that the representation of the resource to be created contain a triple (< >, foaf:primaryTopic , <#it>).
+ If the create is successful, the server responds with location of the newly created resource.</p>
<pre title="A response of creating new a bug" class='example' data-oninclude='fixCode'>
HTTP/1.1 201 Created
Location: /tracker/ldp-demo/67
Content-Length: 0
</pre>
- <p>If the creation fails, the server will respond with an appropriate status code depending on the error. After the resource is creation, the Product A LDPC will have the following representation.</p>
+ <p>If the creation fails, the server will respond with an appropriate status code depending on the error.
+ After the resource is creation, the Product A LDPC will have the following representation.
+</p>
<pre title="The state of the product LDPC after the bug creation" class='example' data-include='ic_bug_create_s1.txt' data-oninclude='fixCode'></pre>
- <p> As you can see two new triples are added to the container. That is (</app/product1>, <ldp:contains>, </tracker/ldp-demo/bug67>) and
- (</tracker/ldp-demo/#it>, <bt:hasbug>, </tracker/ldp-demo/bug67#it>). </p>
+ <p> As you can see two new triples are added to the container.
+ That is (</app/product1>, <ldp:contains>, </tracker/ldp-demo/bug67>) and (</tracker/ldp-demo/#it>, <bt:hasbug>, </tracker/ldp-demo/bug67#it>).
+ </p>
</section>
<!-- end creationext -->
@@ -888,12 +993,18 @@
<section>
<h1>Security</h1>
- <p>It is not the focus of the Linked Data Platform WG to provide security mechanisms for read/write Linked Data applications. Though most of the security mechanisms that are applicable to general web applications are equally applicable to Linked Data applications, there is still some space to build security mechanisms specific to Linked Data applications by leverage the Linked Data technologies and providing concrete security requirements of Linked Data applications. In this context, LDP WG has started to create a WG note on Access Control which aims to produce use cases for security scenarios of LDP applications that can be used as the input to later initiative that will be focused on developing standard security mechanisms for LDP applications.</p>
+ <p>It is not the focus of the Linked Data Platform WG to provide security mechanisms for read/write Linked Data applications.
+ Though most of the security mechanisms that are applicable to general web applications are equally applicable to Linked Data applications, there is still some space to build security mechanisms specific to Linked Data applications by leverage the Linked Data technologies and providing concrete security requirements of Linked Data applications.
+
+ In this context, LDP WG has started to create a WG note on Access Control which aims to produce use cases for security scenarios of LDP applications that can be used as the input to later initiative that will be focused on developing standard security mechanisms for LDP applications.
+
+</p>
</section>
<section>
<h1 id="ldpc">LDP Implementations</h1>
- A list of implementations that plan to be LDP compliant is available in the LDP Implementations wiki page. LDP Implementation report provides the coverage of the specification by each LDP implementation.
+ A list of implementations that plan to be LDP compliant is available in the LDP Implementations wiki page.
+ LDP Implementation report provides the coverage of the specification by each LDP implementation.
</section>
<section>
@@ -913,6 +1024,7 @@
<section class='appendix informative' id="history">
<h1>Change History</h1>
<p>The change history is up to the editors to insert a brief summary of changes, ordered by most recent changes first and with heading from which public draft it has been changed from.
+
</p>
<ul>
<li>2013-08-05 - Providing JSON-LD representations of the examples.</li>