--- a/ldp-paging.html Tue Jul 08 11:36:15 2014 -0400
+++ b/ldp-paging.html Tue Jul 08 12:59:46 2014 -0400
@@ -358,7 +358,6 @@
familiar with paged feeds [[RFC5005]], an in-sequence page resource is similar to a feed document and the same
coherency/completeness considerations apply.
<a href="#ldpr-pagingGET-sequences-change">LDP provides no guarantees that the sequence of page resources is stable</a>.
- <!-- TODO: check link target ^ -->
<p>
Note: the choice of terms was designed to help authors and readers clearly differentiate between
the <a title="Paged resource"><em>resource being paged</em></a>, and the
@@ -443,7 +442,7 @@
<section id='conformance'>
<p>The status of the sections of Linked Data Platform Paging 1.0 (this document) is as follows:</p>
-<p><em>TODO</em>: Update this section list</p>
+
<ul>
<li>1. Introduction: <b>non-normative</b></li>
<li>2. Terminology</li>
@@ -475,8 +474,7 @@
<section><h2>General</h2>
<section id="ldpp-client-traversal"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST
- be capable of <a>forward traversal</a> and/or <a>backward traversal</a>.
- <!-- TODO: and/or is meaningless, must be at least one -->
+ be capable of at least one of <a>forward traversal</a> and/or <a>backward traversal</a>.
</h2>
</section>
@@ -675,18 +673,19 @@
we’ll split the response across two pages.
The client
retrieves <code>http://example.org/customer-relations</code>, and
- the server responds with <a href="#atrisk-2NN">status code <code>2NN Returning Related</code></a>,
+ the server responds with <a href="#atrisk-2NN">status code <code>2NN Contents of Related</code></a>,
a <code>Location: http://example.org/customer-relations?page1</code> HTTP response header
identifying the first page as the resource whose representation is enclosed in the response,
and the following representation:
</p>
-<!-- TODO: add container link header with its etag -->
+<!-- TODO: HTTP envelope to all requests/responses, and show requests where they're omitted today -->
<pre class="example" id="ldpc-ex-page1"># The following is the representation of
# http://example.org/customer-relations?page1
# Requests on the URI will result in responses that include the following HTTP headers
# Link: <http://www.w3.org/ns/ldp#Page>; rel='type'
# Link: <http://example.org/customer-relations?p=2>; rel='next'
+# Link: <http://example.org/customer-relations>; rel='canonical'; etag="customer-relations-v1"
# This Link header is how clients discover the URI of the next page in sequence,
# and that the resource supports paging.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@@ -716,7 +715,7 @@
<p>
Because the server includes a <code>Link: <http://example.org/customer-relations?p=2>; rel='next'</code>
- response header, and the status code is 2xx (<code>2NN Returning Related</code> in this case),
+ response header, and the status code is 2xx (<code>2NN Contents of Related</code> in this case),
the client knows that more data exists and where to find it.
The server determines the size of the pages using application specific methods not defined
within this specificiation. The next page link's target URI is also
@@ -728,12 +727,12 @@
the server responds with status code <code>200 OK</code> and the following representation:
</p>
-<!-- TODO: add container link header with its etag -->
<pre class="example" id="ldpc-ex-page2"># The following is the representation of
# http://example.org/customer-relations?p=2
#
# Requests on the URI will result in responses that include the following HTTP headers
# Link: <http://www.w3.org/ns/ldp#Page>; rel='type'
+# Link: <http://example.org/customer-relations>; rel='canonical'; etag="customer-relations-v1"
#
# There is no "next" Link in the server's response, so this is the final page.
#
@@ -821,15 +820,14 @@
<section id="ldpr-PagingGET">
<h3>HTTP GET</h3>
- <p>In addition to the requirements set forth in <a href="#ldpr-HTTP_GET" class="sectionRef"></a> on HTTP <code>GET</code>,
+ <p>In addition to the requirements on HTTP <code>GET</code> for LDPRs [[!LDP]],
<a title="LDP Paging server">LDP Paging servers</a> must
also follow the requirements in this section for all <a title="Paged resource">paged resources</a>
and their associated <a title="in-sequence page resource">in-sequence page resources</a>.
- <!-- TODO: remove this clause? circular ref -->
</p>
<section id="ldpr-page-large"><h2 class="normal">
- <!-- TODO: remove this clause? see what's still in LDP; as a SHOULD here it seems weird -->
+ <!-- Remove this clause? No, it was MOVED here from LDP, and as a Must we'd need to define 'large' to test compliance. -->
<a title="LDP Paging server">LDP Paging servers</a> SHOULD allow clients to retrieve large LDP-RSs in
pages.
</h2></section><!-- Was 4.2.14 / #ldpr-4_2_14 -->
@@ -855,13 +853,12 @@
the client is interested in processing,
to influence the amount of data returned in representations.
</h2></section>
- <!-- TODO: Need to rework this^ and possibly relocate it ... does not apply only to LDPCs -->
<div class="atrisk" id="atrisk-2NN"><p class="atrisktext">Feature At Risk</p>
<p>The LDP Working Group proposes incorporation of the features described in the next compliance clause.</p>
<ul>
<li><p>
- A <a href="http://lists.w3.org/Archives/Public/www-tag/2013Dec/0041.html">TAG discussion</a> has started,
+ A <a href="http://lists.w3.org/Archives/Public/www-tag/2013Dec/0041.html">December 2013 TAG discussion</a> started,
whose goal is to reduce the need for two request-response round trips down to one when retrieving what
turns out to be the first page of a paged resource, by defining a new
HTTP response code in the <code>2xx</code> or <code>3xx</code> class that would allow a server to
@@ -870,9 +867,11 @@
</p></li>
<li><p>
For the purposes of drafting this section, we assume that the
- new code's value is <code>2NN Returning Related</code>,
+ new code's value is <code>2NN Contents of Related</code>,
+ and its definition is given by the
+ <a href="http://www.w3.org/2014/02/2xx/draft-prudhommeaux-http-status-2NN.xml">draft-prudhommeaux-http-status-2nn</a>
+ IETF draft, whose content evolved from
<a href="http://lists.w3.org/Archives/Public/www-tag/2014Jan/0023.html">an LDP extrapolation from TAG discussions</a>,
- and its definition is given by
<a href="http://lists.w3.org/Archives/Public/www-tag/2014Jan/0015.html">Henry Thompson's strawman</a>,
with the substitution of 2NN for 2xx as suggested in
<a href="https://github.com/w3ctag/spec-reviews/blob/master/2014/04/http-209.md">the TAG's draft comments, item 2</a>.
@@ -893,7 +892,7 @@
<section id="ldpr-status-code"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> SHOULD respond
- with HTTP status code <code>2NN Returning Related</code>
+ with HTTP status code <code>2NN Contents of Related</code>
to successful <code>GET</code> requests with any <a title="Paged resource">paged resource</a>
as the <code>Request-URI</code>, although any appropriate code such as <code>303 See Other</code> MAY be used.
</h2></section>
@@ -1095,11 +1094,9 @@
</p>
<p>
Order becomes more important when containers are
- paginated. If the server does not respect ordering when constructing
- pages, the client would be forced to retrieve all pages before
- sorting the members, which would defeat the purpose of pagination.
- <!-- TODO: Not if the purpose of pagination is rate-limiting, as we've said it is.
- This is about reducing dup work for client, i.e. optimization. -->
+ paginated. If the server respects ordering when constructing
+ pages, clients needing a globally sorted set of members
+ can reduce the effort required to merge pages.
In cases where ordering is important, an <a>LDP Paging server</a> exposes all the
members on a page with the proper sort order with relation to all
members on the next and previous pages.
@@ -1118,9 +1115,9 @@
<code>ldp:containerSortPredicate</code>, and
optionally a <code>ldp:containerSortCollation</code>.
</p>
- <p>Here is an example container described
- previously, with representation for ordering of the assets:</p>
-<!-- TODO: fix ^ previously -->
+ <p>Here is an example asset container described in [[LDP]] section 5.1,
+ with the ordering of the assets asserted:</p>
+
<pre class="example" id="ldpc-ex-ordering">
# The following is the ordered representation of
# http://example.org/netWorth/nw1/assetContainer/
@@ -1181,9 +1178,12 @@
<p>The Linked Data Platform does not define how clients
discover <dfn><abbr title="Linked Data Platform Containers">LDPCs</abbr></dfn>.</p>
+ <div class="ldp-issue-pending" id="what-the-new-container"><p class="ldp-issue-title">For Discussion</p>
+ <p>Are we attempting to define a new type of container here? If not, should delete the clause.</p>
+ </div>
+
<section id="ldpc-isldpr"><h2 class="normal">Each Linked Data Platform Paging Container MUST also be
a conforming Linked Data Platform Container.
- <!-- TODO: this^ seems like an odd stmt ... if we are only defining page order for LDPCs, why is this relevant? -->
</h2></section>
<section id="ldpc-onsamepage"><h2 class="normal">
@@ -1201,10 +1201,10 @@
<section id="ldpc-sortcriteriaobj"><h2 class="normal">
<a title="LDP Paging server">LDP Paging servers</a> MAY
- represent the members of a paged LDPC in a sequential
- <!-- TODO: order is ALWAYS sequential; this is really about is that sequence a sort output, and if so on what key(s), assuming that the server wants to communicate that to clients -->
- order; LDP Paging does not specify ordering for LDPRs that are not also LDPCs.
- If the server does so, it MUST specify the order using a triple
+ communicate the order it uses to allocate LDPC members to <a>in-sequence page resource</a>s
+ as part of the pages' representations;
+ LDP Paging does not specify ordering for pages of LDPRs in other cases.
+ If the server communicates this, it MUST specify the order using a triple
whose subject is the page URI,
whose predicate is <code>ldp:containerSortCriteria</code>,
and whose object is a <code>rdf:List</code> of
@@ -1415,6 +1415,7 @@
<!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-paging-20140930/">Candidate Recommendation Draft</a></em></blockquote> wah -->
<!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-paging-20140730/">Last Call Draft</a></em></blockquote> -->
<ul>
+ <li>2014-07-08 - Resolve a set of editorial to-dos (JA) </li>
<li>2014-07-07 - Clients must consent to/invite paging per 20140630 resolution 2 (JA) </li>
<li>2014-07-07 - Rename single-page resource to in-sequence page resource per 20140630 resolution 3 (JA) </li>
<li>2014-06-10 - Use http-bis and Prefer RFC numbers, adjust BNF to match bis changes (JA) </li>