--- a/ldp.html Mon Jun 24 16:56:30 2013 +0100
+++ b/ldp.html Mon Jul 01 07:48:38 2013 -0400
@@ -303,6 +303,7 @@
such as type changes?</li>
<li>What can servers do to ease the burden of constraints for resource
creation?</li>
+ <li>How do I GET the entries of a large resources broken up into pages?</li>
</ul>
<p>Additional informative guidance is available on the <a
href="http://www.w3.org/2012/ldp/wiki/Deployment_Guide"
@@ -315,7 +316,9 @@
<li>Are there some typical vocabularies that should be reused?</li>
</ul>
<p>The following sections define the rules and
- guidelines for use of LDPRs.</p>
+ guidelines for use of LDPRs. This document also explains how to include
+ information about each member in the resource’s own representation
+ and how to paginate the resource representation if it gets too big.</p>
<section>
<h2 id="ldpr-general">General</h2>
@@ -390,10 +393,6 @@
<div class="ldp-issue-title"><a href="http://www.w3.org/2012/ldp/track/issues/32">ISSUE-32</a></div>
How can clients discover that a resource is an LDPR or LDPC, and what features are supported?
</div>
- <div class="ldp-issue-closed">
- <div class="ldp-issue-title"><a href="http://www.w3.org/2012/ldp/track/issues/33">ISSUE-33</a></div>
- Pagination for non-container resources
- </div>
<div id="ldpr-4_1_11" class="rule">4.1.11 LDPR
servers SHOULD enable simple creation and modification of LDPRs.
@@ -546,6 +545,177 @@
</div>
</section>
+<section>
+<h2 id="ldpr-Paging">Paging</h2>
+<em>Suggest creating a separate "last" section for LDPRs to not clutter everything else</em>
+
+<section>
+<h3 id="ldpr-PagingIntro">Introduction</h3>
+ <em>This section is non-normative</em>
+ <p>It sometimes happens that a
+ resource is too large to reasonably transmit its representation in a
+ single HTTP response. This will be especially true if the resource
+ representation includes many triples both from its own representation and
+ from the representations of any of its members. A client could anticipate that a resource will be too large -
+ for example, a client tool that accesses defects may assume that an
+ individual defect will usually be of sufficiently constrained size
+ that it makes sense to request all of it at once, but that the
+ container of all the defects ever created will typically be too big.
+ Alternatively, a server could recognize that a resource that has been
+ requested is too big to return in a single message.</p>
+ <p>
+ To address this problem, LDPRs should support a technique called Paging. Paging can be achieved with a
+ simple RDF pattern. For each resource, <code><resourceURL></code>, we define a new
+ 'first page' resource. In this example, its URL will be <code><containerURL>?firstPage</code>,
+ but servers are free to construct the URL as they see fit.
+ The triples in the representation of the each page
+ are a subset of the triples in the resource
+ - same subject, predicate and object.
+ </p>
+ <p>LDPR servers may respond to requests for a
+ resource by redirecting the client to the first page resource –
+ using a 303 “See Other” redirect to the actual URL for the page
+ resource.</p>
+ <p>
+ Looking at an example resource representing JohnZSmith's net
+ worth, we’ll split the response across two pages.
+ To find the URL of the first page, the client makes a <code>OPTIONS</code> request
+ to the resource's URL, and in the response looks for a HTTP <code>Link</code>
+ header with <code>rel="first"</code>; the target URI in the header is the URL
+ of the first page resource.
+ The client then
+ requests the first page as <code>http://example.org/netWorth/nw1/assetContainer/?firstPage</code>:
+ </p>
+<pre class="example"># The following is the representation of
+# http://example.org/netWorth/nw1/assetContainer/?firstPage
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
+@prefix dcterms: <http://purl.org/dc/terms/>.
+@prefix ldp: <http://www.w3.org/ns/ldp#>.
+@prefix o: <http://example.org/ontology/>.
+
+<http://example.org/netWorth/nw1/assetContainer/>
+ a ldp:Container;
+ dcterms:title "The assets of JohnZSmith";
+ ldp:membershipSubject <http://example.org/netWorth/nw1>;
+ ldp:membershipPredicate o:asset.
+
+<http://example.org/netWorth/nw1/assetContainer/?firstPage>
+ a ldp:Page;
+ ldp:pageOf <http://example.org/netWorth/nw1/assetContainer/>;
+ ldp:nextPage <http://example.org/netWorth/nw1/assetContainer/?p=2>.
+
+<http://example.org/netWorth/nw1>
+ a o:NetWorth;
+ o:asset
+ <http://example.org/netWorth/nw1/assetContainer/a1>,
+ <http://example.org/netWorth/nw1/assetContainer/a4>,
+ <http://example.org/netWorth/nw1/assetContainer/a3>,
+ <http://example.org/netWorth/nw1/assetContainer/a2>.
+
+<http://example.org/netWorth/nw1/assetContainer/a1>
+ a o:Stock;
+ o:value 100.00.
+<http://example.org/netWorth/nw1/assetContainer/a2>
+ a o:Cash;
+ o:value 50.00.
+# server initially supplied no data for a3 and a4 in this response</pre>
+
+ <p>
+ The following example is the result of retrieving the representation
+ for the next page:
+ </p>
+
+<pre class="example"># The following is the representation of
+# http://example.org/netWorth/nw1/assetContainer/?p=2
+@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
+@prefix dcterms: <http://purl.org/dc/terms/>.
+@prefix ldp: <http://www.w3.org/ns/ldp#>.
+@prefix o: <http://example.org/ontology/>.
+
+<http://example.org/netWorth/nw1/assetContainer/>
+ a ldp:Container;
+ dcterms:title "The assets of JohnZSmith";
+ ldp:membershipSubject <http://example.org/netWorth/nw1>;
+ ldp:membershipPredicate o:asset.
+
+<http://example.org/netWorth/nw1/assetContainer/?p=2>
+ a ldp:Page;
+ ldp:pageOf <http://example.org/netWorth/nw1/assetContainer/>;
+ ldp:nextPage rdf:nil.
+
+<http://example.org/netWorth/nw1>
+ a o:NetWorth;
+ o:asset
+ <http://example.org/netWorth/nw1/assetContainer/a5>.
+
+<http://example.org/netWorth/nw1/assetContainer/a5>
+ a o:Stock;
+ dcterms:title "Big Co.";
+ o:value 200.02.</pre>
+
+ <p>
+ In this example, there is only one member in the container in the
+ final page. To indicate this is the last page, a value of <code>rdf:nil</code> is used for the <code>ldp:nextPage</code>
+ predicate of the page resource.
+ </p>
+ <p>LDPC guarantees that any and all the triples
+ about the members will be on the same page as the membership triple
+ for the member.</p>
+</section>
+
+<section>
+<h3 id="ldpr-PagingGET">HTTP GET</h3>
+<p>In addition to the requirements set forth in section (HTTP GET), LDPR Servers that support paging must also follow the requirements in this section</p>
+
+ <div id="ldpr-5_3_4" class="rule">5.3.4 LDPR servers SHOULD allow clients to retrieve large LDPRs in
+ pages. In responses to <code>GET</code> requests with an LDPR as the Request-URI,
+ LDPR servers that support paging SHOULD provide an HTTP <code>Link</code>
+ header whose target URI is the first page resource, and whose link relation type is <code>first</code> [[!RFC5988]].
+ This is the mechanism by which clients discover the URL of the first page. If no such <code>Link</code>
+ header is present, then conservative clients will assume that the LDPR does not support paging.
+ For example, if there is a LDPR with URL <code><resourceURL></code> that supports paging and whose
+ first page URL is <code><resourceURL>?theFirstPage</code>, then the corresponding link header
+ would be <code>Link: <?theFirstPage>;rel="first"</code>.
+ The representation for any page, including the first, will include
+ the URL for the next page. See section <a href="#ldpr-paging">4.7 Paging</a> for additional details.
+ </div>
+ <div id="ldpc-5_3_5" class="rule">5.3.5 LDPR servers MAY split the response representation of any LDPR.
+ This is known as
+ server-initiated paging. See section <a href="#ldpr-paging">4.7 Paging</a> for
+ additional details.
+ </div>
+ <div id="ldpc-5_3_5_1" class="rule">5.3.5.1 LDPR servers that initiate paging SHOULD respond to requests for a LDPR
+ by redirecting the client to the first page resource using a <code>303 See
+ Other</code> response with an HTTP <code>Location</code> header providing the first page resource URL.
+ </div>
+ <div id="ldpc-5_3_6" class="rule">5.3.6 LDPR servers that support paging MUST include in the page
+ representation a representation for the LDPR, such that:
+ </div>
+ <div id="ldpc-5_3_6_1" class="rule">5.3.6.1 The page resource representation SHOULD have one triple to indicate its
+ type, whose subject is the URL of the page, whose predicate is <code>rdf:type</code> and object is <code>ldp:Page</code>.
+ It also SHOULD have 1 triple to indicate the resource it is paging,
+ whose subject is the URL of the page, predicate is <code>ldp:pageOf</code>,
+ and object is the URL of the LDPC.
+ </div>
+ <div id="ldpc-5_3_6_2" class="rule">5.3.6.2 The page resource representation MUST have one triple with the subject
+ of the page, predicate of <code>ldp:nextPage</code> and
+ object being the URL for the subsequent page.
+ </div>
+ <div id="ldpc-5_3_6_3" class="rule">5.3.6.3 The last page resource representation MUST have one triple with the subject of the
+ last page, predicate of <code>ldp:nextPage</code> and object being <code>rdf:nil</code>.
+ </div>
+</section>
+
+<section>
+<h3 id="ldpr-paging-HTTP_OPTIONS">HTTP OPTIONS</h3>
+<div id="ldpr-4_8_2_1" class="rule">4.8.2.1 LDPR servers MUST indicate their support for client-initiated paging by
+ responding to a HTTP OPTIONS request on the LDPR’s URL with the HTTP
+ response header for link relations using the header name of <code>Link</code> and link relation type is <code>first</code> [[!RFC5988]].
+</div>
+</section>
+
+</section>
+
</section>
<section>
@@ -566,7 +736,6 @@
<li>Where can I GET a list of existing resources?</li>
<li>How is the order of the container entries expressed?</li>
<li>How do I get information about the members along with the container?</li>
- <li>How do I GET the entries of a large container broken up into pages?</li>
<li>How can I ensure the resource data is easy to query?</li>
</ol>
<p>
@@ -586,9 +755,6 @@
using POST to create new resources and add them to the list of
members of a container. It goes on to explain how to learn about a set of related
resources, they may have been created using POST or through other means.
- This document also explains how to include
- information about each member in the container’s own representation
- and how to paginate the container representation if it gets too big.
It also defines behavior when POST created resources are deleted, to clean up
container membership, and deleting containers removes membership information and
possibly perform some cleanup tasks on unreferenced member resoruces.</p>
@@ -805,119 +971,8 @@
<p>While the same non-member resource could be used to update the non-member properties via PUT,
LDP recommends using PATCH for this purpose.</p>
-
- <div id="ldpc-paging" class="rule">5.1.3 Paging</div>
- <em>This section is non-normative</em>
- <p>It sometimes happens that a
- container is too large to reasonably transmit its representation in a
- single HTTP response. This will be especially true if the container
- representation includes many triples from the representations of its
- members. A client could anticipate that a container will be too large -
- for example, a client tool that accesses defects may assume that an
- individual defect will usually be of sufficiently constrained size
- that it makes sense to request all of it at once, but that the
- container of all the defects ever created will typically be too big.
- Alternatively, a server could recognize that a container that has been
- requested is too big to return in a single message.</p>
- <p>
- To address this problem, LDPCs should support a technique called Paging. Paging can be achieved with a
- simple RDF pattern. For each container resource, <code><containerURL></code>, we define a new
- 'first page' resource. In this example, its URL will be <code><containerURL>?firstPage</code>,
- but servers are free to construct the URL as they see fit.
- The triples in the representation of the each page
- are a subset of the triples in the container
- - same subject, predicate and object.
- </p>
- <p>LDPC servers may respond to requests for a
- container by redirecting the client to the first page resource –
- using a 303 “See Other” redirect to the actual URL for the page
- resource.</p>
- <p>
- Continuing on from the member information from the JohnZSmith net
- worth example, we’ll split the response across two pages.
- To find the URL of the first page, the client makes a <code>HEAD</code> request
- to the container's URL, and in the response looks for a HTTP <code>Link</code>
- header with <code>rel="first"</code>; the target URI in the header is the URL
- of the first page resource.
- The client then
- requests the first page as <code>http://example.org/netWorth/nw1/assetContainer/?firstPage</code>:
- </p>
-<pre class="example"># The following is the representation of
-# http://example.org/netWorth/nw1/assetContainer/?firstPage
-@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
-@prefix dcterms: <http://purl.org/dc/terms/>.
-@prefix ldp: <http://www.w3.org/ns/ldp#>.
-@prefix o: <http://example.org/ontology/>.
-
-<http://example.org/netWorth/nw1/assetContainer/>
- a ldp:Container;
- dcterms:title "The assets of JohnZSmith";
- ldp:membershipSubject <http://example.org/netWorth/nw1>;
- ldp:membershipPredicate o:asset.
+ <div id="ldpc-5.1.3" class="rule">5.1.3 <strike>Paging</strike> <em>Was paging, moved to section 4</em></div>
-<http://example.org/netWorth/nw1/assetContainer/?firstPage>
- a ldp:Page;
- ldp:pageOf <http://example.org/netWorth/nw1/assetContainer/>;
- ldp:nextPage <http://example.org/netWorth/nw1/assetContainer/?p=2>.
-
-<http://example.org/netWorth/nw1>
- a o:NetWorth;
- o:asset
- <http://example.org/netWorth/nw1/assetContainer/a1>,
- <http://example.org/netWorth/nw1/assetContainer/a4>,
- <http://example.org/netWorth/nw1/assetContainer/a3>,
- <http://example.org/netWorth/nw1/assetContainer/a2>.
-
-<http://example.org/netWorth/nw1/assetContainer/a1>
- a o:Stock;
- o:value 100.00.
-<http://example.org/netWorth/nw1/assetContainer/a2>
- a o:Cash;
- o:value 50.00.
-# server initially supplied no data for a3 and a4 in this response</pre>
-
- <p>
- The following example is the result of retrieving the representation
- for the next page:
- </p>
-
-<pre class="example"># The following is the representation of
-# http://example.org/netWorth/nw1/assetContainer/?p=2
-@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
-@prefix dcterms: <http://purl.org/dc/terms/>.
-@prefix ldp: <http://www.w3.org/ns/ldp#>.
-@prefix o: <http://example.org/ontology/>.
-
-<http://example.org/netWorth/nw1/assetContainer/>
- a ldp:Container;
- dcterms:title "The assets of JohnZSmith";
- ldp:membershipSubject <http://example.org/netWorth/nw1>;
- ldp:membershipPredicate o:asset.
-
-<http://example.org/netWorth/nw1/assetContainer/?p=2>
- a ldp:Page;
- ldp:pageOf <http://example.org/netWorth/nw1/assetContainer/>;
- ldp:nextPage rdf:nil.
-
-<http://example.org/netWorth/nw1>
- a o:NetWorth;
- o:asset
- <http://example.org/netWorth/nw1/assetContainer/a5>.
-
-<http://example.org/netWorth/nw1/assetContainer/a5>
- a o:Stock;
- dcterms:title "Big Co.";
- o:value 200.02.</pre>
-
- <p>
- In this example, there is only one member in the container in the
- final page. To indicate this is the last page, a value of <code>rdf:nil</code> is used for the <code>ldp:nextPage</code>
- predicate of the page resource.
- </p>
- <p>LDPC guarantees that any and all the triples
- about the members will be on the same page as the membership triple
- for the member.</p>
-
<div id="ldpc-ordering" class="rule">5.1.4 Ordering</div>
<em>This section is non-normative</em>
<p>
@@ -1118,43 +1173,11 @@
</strike></blockquote>
</div>
- <div id="ldpc-5_3_4" class="rule">5.3.4 LDPC servers SHOULD allow clients to retrieve large LDPCs in
- pages. In responses to <code>GET</code> requests with an LDPC as the Request-URI,
- LDPC servers that support paging SHOULD provide an HTTP <code>Link</code>
- header whose target URI is the first page resource, and whose link relation type is <code>first</code> [[!RFC5988]].
- This is the mechanism by which clients discover the URL of the first page. If no such <code>Link</code>
- header is present, then conservative clients will assume that the LDPC does not support paging.
- For example, if there is a LDPC with URL <code><containerURL></code> that supports paging and whose
- first page URL is <code><containerURL>?theFirstPage</code>, then the corresponding link header
- would be <code>Link: <?theFirstPage>;rel="first"</code>.
- The representation for any page, including the first, will include
- the URL for the next page. See section <a href="#ldpc-paging">5.1.3 Paging</a> for additional details.
- </div>
- <div id="ldpc-5_3_5" class="rule">5.3.5 LDPC servers MAY split the response representation of any LDPC.
- This is known as
- server-initiated paging. See section <a href="#ldpc-paging">5.1.3 Paging</a> for
- additional details.
- </div>
- <div id="ldpc-5_3_5_1" class="rule">5.3.5.1 LDPC servers that initiate paging SHOULD respond to requests for a LDPC
- by redirecting the client to the first page resource using a <code>303 See
- Other</code> response with an HTTP <code>Location</code> header providing the first page resource URL.
- </div>
- <div id="ldpc-5_3_6" class="rule">5.3.6 LDPC servers that support paging MUST include in the page
- representation a representation for the LDPC, such that:
- </div>
- <div id="ldpc-5_3_6_1" class="rule">5.3.6.1 The page resource representation SHOULD have one triple to indicate its
- type, whose subject is the URL of the page, whose predicate is <code>rdf:type</code> and object is <code>ldp:Page</code>.
- It also SHOULD have 1 triple to indicate the container it is paging,
- whose subject is the URL of the page, predicate is <code>ldp:pageOf</code>,
- and object is the URL of the LDPC.
- </div>
- <div id="ldpc-5_3_6_2" class="rule">5.3.6.2 The page resource representation MUST have one triple with the subject
- of the page, predicate of <code>ldp:nextPage</code> and
- object being the URL for the subsequent page.
- </div>
- <div id="ldpc-5_3_6_3" class="rule">5.3.6.3 The last page resource representation MUST have one triple with the subject of the
- last page, predicate of <code>ldp:nextPage</code> and object being <code>rdf:nil</code>.
- </div>
+ <div id="ldpc-5_3_4" class="rule">5.3.4 <strike>LDPC servers SHOULD allow clients to retrieve large LDPCs in
+ pages.</strike> Moved to section 4</div>
+ <div id="ldpc-5_3_5" class="rule">5.3.5 <strike>LDPC servers MAY split the response representation of any LDPC</strike> moved to section 4</div>
+ <div id="ldpc-5_3_6" class="rule">5.3.6 <strike>LDPC servers that support paging MUST include in the page</strike> moved to section 4</div>
+
<div class="ldp-issue-closed">
<div class="ldp-issue-title"><a href="http://www.w3.org/2012/ldp/track/issues/18">ISSUE-18</a></div>
@@ -1325,7 +1348,15 @@
SHOULD NOT re-use URIs, per the<a href="#ldpc-5_2_9">
general requirements on LDPCs</a>.
</div>
-
+ <div id="ldpc-5_4_12" class="rule">ISSUE-15 5.4.12 LDPC servers that allow non-LDPR member creation via POST
+ MAY create a companion LDPR, things to work out:
+ <ul>
+ <li>Should this really be in LDPC section since it has to do with LDPR to non-LDPR relationship? confusion might be with create/POST</li>
+ <li>Need to update HEAD for non-LDPRs</li>
+ <li>DELETE for LDPRs (client may not have control of this) and non-LDPRs (should remove it + any LDPR)</li>
+ <li>Do we need to say anyting about update</li>
+ </ul>
+ </div>
</section>
<section>
@@ -1451,6 +1482,7 @@
<blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130701/">Third Public Working Draft</a></em></blockquote>
-->
<ul>
+ <li>2013-07-01 - ISSUE-33 Moved 5.1.3 Paging (LDPC) to 4.8 (LDPR) (SS)</li>
<li>2013-06-18 - ISSUE-75 5.2.5 membershipxxx predicates required, per 2013-06-18 F2F resolution (JA)</li>
<li>2013-06-18 - ISSUE-63 End of 5.3 + example rewritten for 2013-06-18 F2F resolution (JA)</li>
<li>2013-06-15 - ISSUE-14 End of 5.3 + example rewritten for ascending/descending sorts with optional collation (JA)</li>