--- a/ldp-primer/ldp-primer.html Mon Jul 15 14:50:51 2013 +0200
+++ b/ldp-primer/ldp-primer.html Mon Jul 22 18:02:54 2013 +0200
@@ -1,1 +1,1 @@
-<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.1//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-2.dtd">
<html
xmlns="http://www.w3.org/1999/xhtml"
prefix="td: http://www.w3.org/2006/03/test-description# tn: http://ldp.example.org/NewTestDefinitions# ht: http://www.w3.org/2011/http#">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<!-- rgarcia: Had to uncomment it so it can read the local image
<base href="http://www.w3.org/TR/ldp/TestCases">-->
<title>Linked Data Platform 1.0 Primer</title>
<script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove' async></script>
<script class='remove'>
var respecConfig = {
// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
specStatus: "ED",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "ldp-primer",
// TODO: Confirm short name
// if your specification has a subtitle that goes below the main
// formal title, define it here
// subtitle : "an excellent document",
// if you wish the publication date to be other than today, set this
// publishDate: "2009-08-06",
// if the specification's copyright date is a range of years, specify
// the start date here:
// copyrightStart: "2005"
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
// and its maturity status
//previousPublishDate: "2013-03-07",
//previousMaturity: "FPWD",
//previousURI: "http://www.w3.org/TR/2013/WD-ldp-20130307/",
// if there a publicly available Editor's Draft, this is the link
//edDraftURI: "http://www.w3.org/2012/ldp/hg/ldp.html",
// if this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2009-08-05",
// if you want to have extra CSS, append them to this list
// it is recommended that the respec.css stylesheet be kept
//extraCSS: ["https://dvcs.w3.org/hg/ldpwg/css/respec.css"],
// editors, add as many as you like
// only "name" is required
editors: [
{ name: "Nandana Mihindukulasooriya",
url: "http://mayor2.dia.fi.upm.es/oeg-upm/index.php/en/universitystaff/290-nandana",
company: "Ontology Engineering Group, Universidad Politécnica de Madrid",
companyURL: "http://www.oeg-upm.net/"},
{ name: "Roger Menday",
url: "#",
company: "Fujitsu Limited",
companyURL: "#" },
],
// authors, add as many as you like.
// This is optional, uncomment if you have authors as well as editors.
// only "name" is required. Same format as editors.
//authors: [
// { name: "Your Name", url: "http://example.org/",
// company: "Your Company", companyURL: "http://example.com/" },
//],
// name of the WG
wg: "Linked Data Platform Working Group",
// URI of the public WG page
wgURI: "http://www.w3.org/2012/ldp",
// name (without the @w3c.org) of the public mailing to which comments are due
wgPublicList: "public-ldp-wg",
// URI of the patent status for this WG, for Rec-track documents
// !!!! IMPORTANT !!!!
// This is important for Rec-track documents, do not copy a patent URI from a random
// document unless you know what you're doing. If in doubt ask your friendly neighbourhood
// Team Contact.
wgPatentURI: "http://www.w3.org/2004/01/pp-impl/55082/status",
doRDFa: "1.1",
};
// Replaces HTML characters (brackets and quotes) with legal HTML representations
// The following example would include a code example from another file and then
// call this function to make the included code renderable in a browser.
//
// <pre class='example' data-include='include-rdf-type.ttl' data-oninclude='fixCode'></pre>
function fixCode(r, content) {
var result = content;
result = result.replace(/</g, "<").replace(/>/g, ">");
result = result.replace(/'/g, "'").replace(/"/g, """);
return result;
}
function highlight(r, content) {
return '<span style="background-color:#ccffcc">' + content + '</span>';
}
</script>
</head>
<body>
<section id='abstract'>
This primer provides an introduction to Linked Data Platform (LDP), including the basic concepts
of LDP including Linked Data Platform Resource (LDPR) and Linked Data Platform Container (LDPC)
and their affordances, and a running example showing how an LDP client can interact with a LDP server
in the context of read-write Linked Data application i.e. how to HTTP for accessing, updating,
creating and deleting resources from servers that expose their resources as Linked Data.
</section>
<section id="intro-section">
<h1><a id="Introduction">Introduction</a></h1>
<p>A bit about Linked Data, current state, and the need for a Linked Data Platform (Read/Write LD) etc.
A bit about generic LDP servers and LDP servers that represent business applications. That is bit confusing for most of the people.
from test cases, Generic vs domain-specific servers
There will be two types of systems implementing the LDP specification:
Generic RDF storage systems that allow interacting with their resources by means of the LDP specification.
These servers do not impose any restriction on LDPRs. Systems exposing their data using the LDP specification. These systems impose restrictions on LDPRs since they have an underlying business logic and data model. In order to cover both types of systems, we do not provide concrete input data in the test suite. It is up to the evaluator to define concrete input data for a certain system. Evaluators must include these input data along with the results when reporting the results of a certain system.</p>
</section>
<section id="org-section">
<h1 id="orgnization">Organization of this Document</h1>
<p>This document is organized as follows:</p>
<ul>
</ul>
<h2 id="conventions">Conventions Used in This Document</h2>
<p>Sample resource representations are provided in <code>text/turtle</code>
format [[TURTLE]].</p>
<p>Commonly used namespace prefixes:</p>
<pre style="word-wrap: break-word; white-space: pre-wrap;"> @prefix dcterms: <http://purl.org/dc/terms/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.</pre>
</section>
<section id="examples">
<h1>Examples</h1>
<p>
This section provides a set of examples to show the Linked Data Platform interactions. Note that we do not intend these examples to be representative of the manner LDP should be used, or as a canonical example of good modeling with LDP. Instead, we intend it to be a rather simple exhibition of various features of Linked Data Platform. <br/><br/>
The examples in this section will revolve around a very simple Bug Tracker application. Bug Tracker application records the bugs of several products. The Bug Tracker allows reporting, updating and deleting bugs and products.
We can make the Bug Tracker application a LDP application by mapping the Bug Tracker data model to LDP data model and mapping the Bug Tracker interactions to LDP interactions. We can map Bug Tracker to a LDPC that contains a set of products, Product to a LDPC that contains a set of bugs, and a Bug to a LDPR.
</p>
<table class="simple">
<thead>
<th>Path</th>
<th>Method</th>
<th>Description</th>
</thead>
<tbody>
<tr>
<td>/app/{product-id}</td>
<td>GET</td>
<td>Lists the bugs of a product.</td>
</tr>
<tr>
<td>/app/{product-id}/{bug-id}</td>
<td>GET</td>
<td>Provides the information about the bug.</td>
</tr>
<tr>
<td>/app/{product-id}</td>
<td>POST</td>
<td>TODO</td>
</tr>
<tr>
<td>/app/{product-id}</td>
<td>PUT</td>
<td>TODO</td>
</tr>
<tr>
<td>/app/{product-id}</td>
<td>DELETE</td>
<td>TODO</td>
</tr>
</tbody>
</table>
<section id="simple-ex">
<h2 >Simple scenarios</h2>
<h3 id="ProductLookup">Lookup a Product</h3>
<p>One of the main use cases of the bug tracker is to list of the bugs of a given product. If one has the url of the product, they can look it up to get more information about the product including the bugs it contain.</p>
<table>
<tr>
<td><img src="product_lookup.png" /></td>
<td>
<p>The client request a GET with the URI of a known Product resource.</p>
<pre class="example">GET /app/product1 HTTP/1.1
Host: example.org
Accept: text/turtle
</pre>
<p>If the resource is available, the server responds with the representation of the resource.</p>
<pre title="HTTP response for product lookup"
class='example' data-include='product_lookup_resp.ttl'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
<h3 id="BugLookup">Lookup a Bug</h3>
<p>Looking up a bug is similar to looking up a product. </p>
<table>
<tr>
<td><img src="bug_lookup.png" /></td>
<td>
<p>Based on links in the representation of the Product, the client uses GET to navigate to a known Bug resource.</p>
<pre class="example">GET /app/product1/bug3 HTTP/1.1
Host: example.org
Accept: text/turtle
</pre>
<p>The server responds with the representation of the bug.</p>
<pre title="The response of bug lookup"
class='example' data-include='bug_look_up_resp.ttl'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
<h3 id="BugUpdate">Update a Bug</h3>
<p> TODO - Description </p>
<table>
<tr>
<td><img src="bug_update.png" /></td>
<td>
<p>TODO - Description</p>
<pre title="A resquest for updating a bug"
class='example' data-include='bug_update_req.ttl'
data-oninclude='fixCode'></pre>
<p>If the update is successful, the server will respond with a success status and a new etag.</p>
<pre class="example">
HTTP/1.1 204 No Content
ETag: W/"123456790"
</pre>
</td>
</tr>
</table>
</section>
<section id="basic-ex">
<h2>Basic scenarios</h2>
</section>
<section id="advanced-ex">
<h2>Advanced scenarios</h2>
</section>
</section>
<section>
<h2 id="ldpc">LDP Implementations</h2>
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>
</body>
</html>
\ No newline at end of file
+<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML+RDFa 1.1//EN" "http://www.w3.org/MarkUp/DTD/xhtml-rdfa-2.dtd">
<html
xmlns="http://www.w3.org/1999/xhtml"
prefix="td: http://www.w3.org/2006/03/test-description# tn: http://ldp.example.org/NewTestDefinitions# ht: http://www.w3.org/2011/http#">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<!-- rgarcia: Had to uncomment it so it can read the local image
<base href="http://www.w3.org/TR/ldp/TestCases">-->
<title>Linked Data Platform 1.0 Primer</title>
<script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove' async></script>
<script class='remove'>
var respecConfig = {
// specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
specStatus: "ED",
// the specification's short name, as in http://www.w3.org/TR/short-name/
shortName: "ldp-primer",
// TODO: Confirm short name
// if your specification has a subtitle that goes below the main
// formal title, define it here
// subtitle : "an excellent document",
// if you wish the publication date to be other than today, set this
// publishDate: "2009-08-06",
// if the specification's copyright date is a range of years, specify
// the start date here:
// copyrightStart: "2005"
// if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
// and its maturity status
//previousPublishDate: "2013-03-07",
//previousMaturity: "FPWD",
//previousURI: "http://www.w3.org/TR/2013/WD-ldp-20130307/",
// if there a publicly available Editor's Draft, this is the link
//edDraftURI: "http://www.w3.org/2012/ldp/hg/ldp.html",
// if this is a LCWD, uncomment and set the end of its review period
// lcEnd: "2009-08-05",
// if you want to have extra CSS, append them to this list
// it is recommended that the respec.css stylesheet be kept
//extraCSS: ["https://dvcs.w3.org/hg/ldpwg/css/respec.css"],
// editors, add as many as you like
// only "name" is required
editors: [
{ name: "Nandana Mihindukulasooriya",
url: "http://mayor2.dia.fi.upm.es/oeg-upm/index.php/en/universitystaff/290-nandana",
company: "Ontology Engineering Group, Universidad Politécnica de Madrid",
companyURL: "http://www.oeg-upm.net/"},
{ name: "Roger Menday",
url: "#",
company: "Fujitsu Limited",
companyURL: "#" },
],
// authors, add as many as you like.
// This is optional, uncomment if you have authors as well as editors.
// only "name" is required. Same format as editors.
//authors: [
// { name: "Your Name", url: "http://example.org/",
// company: "Your Company", companyURL: "http://example.com/" },
//],
// name of the WG
wg: "Linked Data Platform Working Group",
// URI of the public WG page
wgURI: "http://www.w3.org/2012/ldp",
// name (without the @w3c.org) of the public mailing to which comments are due
wgPublicList: "public-ldp-wg",
// URI of the patent status for this WG, for Rec-track documents
// !!!! IMPORTANT !!!!
// This is important for Rec-track documents, do not copy a patent URI from a random
// document unless you know what you're doing. If in doubt ask your friendly neighbourhood
// Team Contact.
wgPatentURI: "http://www.w3.org/2004/01/pp-impl/55082/status",
doRDFa: "1.1",
};
// Replaces HTML characters (brackets and quotes) with legal HTML representations
// The following example would include a code example from another file and then
// call this function to make the included code renderable in a browser.
//
// <pre class='example' data-include='include-rdf-type.ttl' data-oninclude='fixCode'></pre>
function fixCode(r, content) {
var result = content;
result = result.replace(/</g, "<").replace(/>/g, ">");
result = result.replace(/'/g, "'").replace(/"/g, """);
return result;
}
function highlight(r, content) {
return '<span style="background-color:#ccffcc">' + content + '</span>';
}
</script>
</head>
<body>
<section id='abstract'>
This primer provides an introduction to Linked Data Platform (LDP), including the basic concepts
of LDP including Linked Data Platform Resource (LDPR) and Linked Data Platform Container (LDPC)
and their affordances, and a running example showing how an LDP client can interact with a LDP server
in the context of read-write Linked Data application i.e. how to HTTP for accessing, updating,
creating and deleting resources from servers that expose their resources as Linked Data.
</section>
<section id="intro-section">
<h1><a id="Introduction">Introduction</a></h1>
<p>Linked Data is a universal approach for handling data which fundamentally includes the notion linking between data items.
Much like the Web is giant network of interlinked documents for a human reader, the graph of Linked Data in the Web is a
data layer on top of which applications are delivered, information is modified, processed, visualised and shared.
</p>
<p>There will be several categories of systems implementing the LDP specification. Two main categories of the LDP servers include:</p>
<dl class="glossary">
<dt>Generic / vanilla LDP servers</dt>
<dd>RDF storage systems that allow interacting with their resources by means of the LDP specification. These servers do not impose any restriction on LDPRs.</dd>
<dt>Application specific LDP severs </dt>
<dd>Systems exposing their data using the LDP specification. These systems impose restrictions on LDPRs since they have an underlying business logic and data model.</dd>
</dl>
</section>
<section id="org-section">
<h1 id="orgnization">Organization of this Document</h1>
<p>This document is organized as follows:</p>
<ul>
</ul>
<h2 id="conventions">Conventions Used in This Document</h2>
<p>Sample resource representations are provided in <code>text/turtle</code>
format [[TURTLE]].</p>
<p>Commonly used namespace prefixes:</p>
<pre style="word-wrap: break-word; white-space: pre-wrap;"> @prefix dcterms: <http://purl.org/dc/terms/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix xsd: <http://www.w3.org/2001/XMLSchema#>.</pre>
</section>
<section id="examples">
<h1>Examples</h1>
<p>
This section provides a set of examples to show the Linked Data Platform interactions. Note that we do not intend these examples to be representative of the manner LDP should be used, or as a canonical example of good modeling with LDP. Instead, we intend it to be a rather simple exhibition of various features of Linked Data Platform. <br/><br/>
The examples in this section will revolve around a very simple Bug Tracker application. Bug Tracker application records the bugs of several products. The Bug Tracker allows reporting, updating and deleting bugs and products.
We can make the Bug Tracker application a LDP application by mapping the Bug Tracker data model to LDP data model and mapping the Bug Tracker interactions to LDP interactions. We can map Bug Tracker to a LDPC that contains a set of products, Product to a LDPC that contains a set of bugs, and a Bug to a LDPR.
</p>
<p>RESTful API of the example Bug Tracker system.</p>
<table class="simple">
<thead>
<th>Path</th>
<th>Method</th>
<th>Description</th>
</thead>
<tbody>
<tr>
<td rowspan="4">/app/</td>
<td>GET</td>
<td>Lists all the product descriptions.</td>
</tr>
<tr>
<td>POST</td>
<td>Create a new product description.</td>
</tr>
<tr>
<td>PUT</td>
<td>Update the list of product descriptions and/or app description</td>
</tr>
<tr>
<td>DELETE</td>
<td>Not supported.</td>
</tr>
<tr>
<td rowspan="4">/app/{product-id}/</td>
<td>GET</td>
<td>Lists the bug reports associated with a product.</td>
</tr>
<tr>
<td>POST</td>
<td>Create a new bug report associated with a product.</td>
</tr>
<tr>
<td>PUT</td>
<td>Update the project description.</td>
</tr>
<tr>
<td>DELETE</td>
<td>Delete the project description and associated bug reports.</td>
</tr>
<tr>
<td rowspan="4">/app/{product-id}/{bug-id}</td>
<td>GET</td>
<td>Gets the bug report.</td>
</tr>
<tr>
<td>POST</td>
<td>Not supported.</td>
</tr>
<tr>
<td>PUT</td>
<td>Update the bug report.</td>
</tr>
<tr>
<td>DELETE</td>
<td>Delete the bug report.</td>
</tr>
</tbody>
</table>
<section id="simple-ex">
<h2 >Simple scenarios</h2>
<h3 id="ProductLookup">Lookup a Product</h3>
<p>One of the main use cases of the bug tracker is to list of the bugs of a given product. If one has the url
of the product, they can look it up to get more information about the product including the bugs it contain.</p>
<table>
<tr>
<td><img src="product_lookup.png" /></td>
<td>
<p>The client request a GET with the URI of a known Product resource.</p>
<pre class="example">GET /app/product1 HTTP/1.1
Host: example.org
Accept: text/turtle
</pre>
<p>If the resource is available, the server responds with the representation of the resource.</p>
<pre title="HTTP response for product lookup"
class='example' data-include='product_lookup_resp.ttl'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
<h3 id="BugLookup">Lookup a Bug</h3>
<p>Looking up a bug is similar to looking up a product. </p>
<table>
<tr>
<td><img src="bug_lookup.png" /></td>
<td>
<p>Based on links in the representation of the Product, the client uses GET to navigate to a known Bug resource.</p>
<pre class="example">GET /app/product1/bug3 HTTP/1.1
Host: example.org
Accept: text/turtle
</pre>
<p>The server responds with the representation of the bug.</p>
<pre title="The response of bug lookup"
class='example' data-include='bug_look_up_resp.ttl'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
<h3 id="BugUpdate">Update a Bug</h3>
<p> TODO - Description </p>
<table>
<tr>
<td><img src="bug_update.png" /></td>
<td>
<p>TODO - Description</p>
<pre title="A resquest for updating a bug"
class='example' data-include='bug_update_req.ttl'
data-oninclude='fixCode'></pre>
<p>If the update is successful, the server will respond with a success status and a new etag.</p>
<pre class="example">
HTTP/1.1 204 No Content
ETag: W/"123456790"
</pre>
</td>
</tr>
</table>
<h3 id="BugCreate">Create a new Bug</h3>
<p>Continuing from the previous example, we can report a Bug against 'product1' by creating a Bug LDPR under the 'Product' LDPC.
The client POSTs a representation of a Bug to the Bug Tracker LDPC. </p>
<table>
<tr>
<td><img src="bug_create.png" /></td>
<td>
<p>The client POSTs a representation of a Bug to the Bug Tracker LDPC.</p>
<pre title="A resquest for creating a bug"
class='example' data-include='bug_create_req.ttl'
data-oninclude='fixCode'></pre>
<p>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-include='bug_create_res.ttl'
data-oninclude='fixCode'></pre>
</td>
</tr>
<tr>
<td colspan="2">
<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='bug_create_s1.ttl'
data-oninclude='fixCode'></pre>
<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.ttl'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
</section>
<section id="basic-ex">
<h2>Basic scenarios</h2>
<h3 id="ProductCreate">Creat a Product</h3>
<p>If the bug tracker allows creating new Products in the tracker, that can done by posting a representation of a new Product to the
Bug Tracker container.</p>
<table>
<tr>
<td colspan="2">
<p>The status of the bug tracker before creating the new product.</p>
<pre title="The state of the Bug Tracker LDPC"
class='example' data-include='product_create_s1.ttl'
data-oninclude='fixCode'></pre>
</td>
</tr>
<tr>
<td><img src="product_create.png" /></td>
<td>
<p>The client POSTs a representation of a Product to the Bug Tracker LDPC.</p>
<pre title="A resquest for creating a product"
class='example' data-include='product_create_req.ttl'
data-oninclude='fixCode'></pre>
<p>If the create is successful, the server responds with location of the newly created resource.</p>
<pre title="A response after creating new a b"
class='example' data-include='product_create_res.ttl'
data-oninclude='fixCode'></pre>
</td>
</tr>
<tr>
<td colspan="2">
<p>After creation of this new container, 'Product A', the representation of the 'Tracker' container will be</p>
<pre title="The state of the Bug Tracker after the product creation"
class='example' data-include='product_create_s2.ttl'
data-oninclude='fixCode'></pre>
<p>and the 'Product A' will have the following representation.</p>
<pre title="The state of the new Product"
class='example' data-include='product_create_s3.ttl'
data-oninclude='fixCode'></pre>
</td>
</tr>
</table>
</section>
<section id="advanced-ex">
<h2>Advanced scenarios</h2>
<section id="paging">
<h3>Pagination</h3>
</section>
<section id="odering">
<h3>Ordering</h3>
</section>
<section id="binary-res">
<h3>Handling binary resources</h3>
</section>
</section>
<section>
<h2 id="ldpc">LDP Implementations</h2>
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>
</body>
</html>
\ No newline at end of file