--- a/ldp-paging.html Tue Jul 08 10:48:28 2014 -0400
+++ b/ldp-paging.html Tue Jul 08 13:02:37 2014 -0400
@@ -4,7 +4,7 @@
DONE: http://www.w3.org/2013/meeting/ldp/2014-04-15#resolution_7 : At a minimum, on paging, we'll provide a way for clients to detect that a triple fell through the cracks during paging.
DONE: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 3: spec sandro's paging proposal
DONE: http://www.w3.org/2012/ldp/track/issues/94 -> http://www.w3.org/2013/meeting/ldp/2014-05-12#resolution_3 2014-04-17 resolution 3: spec sandro's paging proposal
- STARTED: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 4: page size hint
+ TODO: STARTED: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 4: page size hint
DONE: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 5: contains+member triple always on same page
DONE: http://www.w3.org/2013/meeting/ldp/2014-05-12 resolution 4: ordering undefined when paging non-LDPC LDPRs
@@ -267,7 +267,7 @@
<!-- TODO: Move bulk of paging intro here - it's not rocket science -->
<h1>Introduction</h1>
<p>This specification provides a widely re-usable pattern to deal with large resources.
- Depending on the server’s capabilities, a GET request on a <a title="Paged resource">resource</a> can
+ Depending on the client's and server’s capabilities, a GET request on a <a title="Paged resource">resource</a> can
be redirected to a <a title="In-Sequence Page resource">subset of the resource (one page)</a>, that provides access to subsequent pages
(see <a href="#ldpr-Paging" class="sectionRef"></a>).
</p>
@@ -279,7 +279,7 @@
<h1>Terminology</h1>
<section id="terms-from-ldp">
-<h2>Terms re-used from the Linked Data Platform.</h2>
+<h2>Terms re-used from the Linked Data Platform</h2>
<p>This section is non-normative. It summarizes a subset of terms formally defined in [[LDP]] for the reader's convenience.
</p>
@@ -353,12 +353,11 @@
<dd>One of a sequence of related <a title="Linked Data Platform Resource">LDPRs</a>
<var>P<sub>1</sub>, P<sub>2</sub>, ...,P<sub>n</sub></var>,
each of which contains a subset of the state
- of another resource <var>P</var>. <var>P</var> is called the paged resource.
+ of another resource <var>P</var>, called the <a>paged resource</a>.
For readers
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,14 +442,20 @@
<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: <b>normative</b></li>
+ <li>2. Terminology</li>
+ <ul>
+ <li>2.1 Terms re-used from the Linked Data Platform: <b>non-normative</b></li>
+ <li>2.2 Terms normatively defined by this specification: <b>normative</b></li>
+ <li>2.3 Conventions Used in This Document: <b>normative</b></li>
+ </ul>
<li>3. Conformance: <b>normative</b></li>
- <li>4. Linked Data Platform Resources: <b>normative</b></li>
- <li>5. Linked Data Platform Containers: <b>normative</b></li>
- <li>6. HTTP Header Definitions: <b>normative</b></li>
+ <li>4. Linked Data Platform Paging Clients: <b>normative</b></li>
+ <li>5. Linked Data Platform Resources: <b>normative</b></li>
+ <li>6. Linked Data Platform Containers: <b>normative</b></li>
+ <li>7. Notable information from normative references: <b>non-normative</b></li>
<li>A. Acknowledgements: <b>non-normative</b></li>
<li>B.1 Normative references: <b>normative</b></li>
<li>B.2 Non-normative references: <b>non-normative</b></li>
@@ -469,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>
@@ -501,6 +505,96 @@
</section>
</section>
+
+<section id="ldpp-hints">
+<h2>Client hints</h2>
+ <p>
+ Clients can provide paging-related hints to influence the server's choices.
+ </p>
+
+<section id="ldpp-hints-summary">
+<h3>Summary</h3>
+
+ <p>This specification introduces new ...
+ <!-- TODO: fill in summary -->
+ <!--
+ parameters on the HTTP <code>Prefer</code> request header's
+ <code>return=representation</code> preference [[!RFC7240]], used optionally by clients to
+ supply a hint to help the server form a response that is most appropriate to
+ the client's needs. The LDP-defined parameters suggest the portion(s) of a resource's state that the
+ client application is interested in and, if received, is likely to be
+ processed. LDP Containers with large numbers of associated documents
+ and/or members will have large representations, and many client
+ applications may be interested in processing only a subset of the LDPC's
+ information (for example, only membership triples or only containment triples),
+ resulting in a potentially large savings in server, client,
+ and network processing.
+ </p>
+
+ <p>
+ Non-normative note: LDP server implementers should carefully consider the effects of these
+ preferences on caching, as described in section 2 of [[!RFC7240]].
+ </p>
+
+ <p>
+ Non-normative note: [[!RFC7240]] recommends that server implementers include a
+ <code>Preference-Applied</code> response header when the client cannot otherwise determine the server's
+ behavior with respect to honoring hints from the response content.
+ <a href="#prefer-examples">Examples</a> illustrates some cases where the header is unnecessary.
+ </p>
+ -->
+
+</section> <!-- Prefer summary -->
+
+<section id="prefer-rules">
+<h3>Specification</h3>
+
+ <section id="ldpp-hints-page-size"><h2 class="normal">
+ The <code>page-size</code> hint defines the client's maximum desired size for a response representation.
+ A client communicates its hint to the server by adding a
+ HTTP preference request header with
+ <code>return=representation</code> that includes a
+ <code>page-size</code> parameter whose value adheres to the following syntax:
+ </h2>
+ <pre><code>
+ page-size-parameter = "page-size" *WSP "=" *WSP DQUOTE *WSP 1*DIGIT 1*WSP 1*units *WSP DQUOTE
+ units = rdf-triples / extension-units
+ rdf-triples = "rdf-triples" ; units = RDF triples
+ extension-units = token ; other units allowed for future extensibility
+ </code></pre>
+ <blockquote>
+ <p>
+ Where <code>WSP</code> is whitespace [[!RFC5234]],
+ <code>DIGIT</code> is an integer between zero and nine [[!RFC5234]],
+ <code>DQUOTE</code> is a double quote [[!RFC5234]],
+ and
+ <code>token</code> is as defined in [[!RFC7230]].
+ The generic preference BNF [[!RFC7240]] allows either a quoted string or a token as the value of a
+ preference parameter; LDP Paging assigns a meaning to the value only when it is a quoted string.
+ <a title="LDP Paging server">LDP Paging servers</a> MAY
+ ignore a page size of zero, or unrecognized <code>units</code>,
+ and process the request as if the hint was absent.
+ </p>
+ </blockquote>
+ </section>
+
+</section> <!-- Prefer specification -->
+
+<section id="prefer-examples" class="informative">
+<h3>Examples</h3>
+
+ <p id="prefer-examples-direct-minimal-container-only1">
+ Clients interested in receiving at most 500 RDF triples per <a title="in-sequence page resource">page</a>
+ would use add this HTTP header on a <code>GET</code> request:
+ <code>Prefer: return=representation; page-size="500 rdf-triples"</code>
+ </p>
+
+
+</section> <!-- Prefer examples -->
+
+
+</section> <!-- Paging hints -->
+
</section> <!-- Client constraints -->
<section id="ldpr">
@@ -579,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#>.
@@ -620,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
@@ -632,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.
#
@@ -725,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 -->
@@ -759,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
@@ -774,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>.
@@ -797,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>
@@ -965,95 +1060,6 @@
</section> <!-- h2 -->
-<section id="ldpp-hints">
-<h2>Paging-related client hints</h2>
- <p>
- Clients can provide paging-related hints to influence the server's choices.
- </p>
-
-<section id="ldpp-hints-summary">
-<h3>Summary</h3>
-
- <p>This specification introduces new ...
- <!-- TODO: fill in summary -->
- <!--
- parameters on the HTTP <code>Prefer</code> request header's
- <code>return=representation</code> preference [[!RFC7240]], used optionally by clients to
- supply a hint to help the server form a response that is most appropriate to
- the client's needs. The LDP-defined parameters suggest the portion(s) of a resource's state that the
- client application is interested in and, if received, is likely to be
- processed. LDP Containers with large numbers of associated documents
- and/or members will have large representations, and many client
- applications may be interested in processing only a subset of the LDPC's
- information (for example, only membership triples or only containment triples),
- resulting in a potentially large savings in server, client,
- and network processing.
- </p>
-
- <p>
- Non-normative note: LDP server implementers should carefully consider the effects of these
- preferences on caching, as described in section 2 of [[!RFC7240]].
- </p>
-
- <p>
- Non-normative note: [[!RFC7240]] recommends that server implementers include a
- <code>Preference-Applied</code> response header when the client cannot otherwise determine the server's
- behavior with respect to honoring hints from the response content.
- <a href="#prefer-examples">Examples</a> illustrates some cases where the header is unnecessary.
- </p>
- -->
-
-</section> <!-- Prefer summary -->
-
-<section id="prefer-rules">
-<h3>Specification</h3>
-
- <section id="ldpp-hints-page-size"><h2 class="normal">
- The <code>page-size</code> hint defines the client's maximum desired size for a response representation.
- A client communicates its hint to the server by adding a
- HTTP preference request header with
- <code>return=representation</code> that includes a
- <code>page-size</code> parameter whose value adheres to the following syntax:
- </h2>
- <pre><code>
- page-size-parameter = "page-size" *WSP "=" *WSP DQUOTE *WSP 1*DIGIT 1*WSP 1*units *WSP DQUOTE
- units = rdf-triples / extension-units
- rdf-triples = "rdf-triples" ; units = RDF triples
- extension-units = token ; other units allowed for future extensibility
- </code></pre>
- <blockquote>
- <p>
- Where <code>WSP</code> is whitespace [[!RFC5234]],
- <code>DIGIT</code> is an integer between zero and nine [[!RFC5234]],
- <code>DQUOTE</code> is a double quote [[!RFC5234]],
- and
- <code>token</code> is as defined in [[!RFC7230]].
- The generic preference BNF [[!RFC7240]] allows either a quoted string or a token as the value of a
- preference parameter; LDP Paging assigns a meaning to the value only when it is a quoted string.
- <a title="LDP Paging server">LDP Paging servers</a> MAY
- ignore a page size of zero, or unrecognized <code>units</code>,
- and process the request as if the hint was absent.
- </p>
- </blockquote>
- </section>
-
-</section> <!-- Prefer specification -->
-
-<section id="prefer-examples" class="informative">
-<h3>Examples</h3>
-
- <p id="prefer-examples-direct-minimal-container-only1">
- Clients interested in receiving at most 500 RDF triples per <a title="in-sequence page resource">page</a>
- would use add this HTTP header on a <code>GET</code> request:
- <code>Prefer: return=representation; page-size="500 rdf-triples"</code>
- </p>
-
-
-</section> <!-- Prefer examples -->
-
-
-</section> <!-- Paging hints -->
-
</section> <!-- h1 -->
@@ -1088,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.
@@ -1111,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/
@@ -1174,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">
@@ -1194,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
@@ -1297,11 +1304,6 @@
</section> <!-- Base specs -->
<section>
-<h1>HTTP Header Definitions</h1>
-
-<p><em>TBD</em></p>
-
-</section> <!-- Header defns -->
<!-- Removed for action-113
<section>
@@ -1413,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>