--- a/ldp-paging.html Mon May 19 09:28:00 2014 -0400
+++ b/ldp-paging.html Tue May 20 17:41:18 2014 -0400
@@ -1,13 +1,14 @@
<!DOCTYPE html>
<!--
- TODO: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 3: spec sandro's paging proposal
- TODO: 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
+ 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
TODO: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 4: page size hint
TODO: http://www.w3.org/2013/meeting/ldp/2014-04-17 resolution 5: contains+member triple always on same page
- TODO: http://www.w3.org/2013/meeting/ldp/2014-05-12 resolution 4: ordering undefined when paging non-LDPC LDPRs
+ DONE: http://www.w3.org/2013/meeting/ldp/2014-05-12 resolution 4: ordering undefined when paging non-LDPC LDPRs
- TODO: Missing link header for equivalent of ldp:pageOf? Need to verify. Also we have ldp-paging:pageOf in samples
+ DONE: Missing link header for equivalent of ldp:pageOf? Need to verify. Also we have ldp-paging:pageOf in samples
but it doesn't exist in rules or vocabulary doc, oversight?
TODO: Example 11 is missing ldp:contains, true? Omit due to GET on page resource, should make it more clear.
TODO: Paging intro: add 3rd example showing header link age amongst pages and (HEAD on) the base resource.
@@ -99,25 +100,23 @@
wgPatentURI: "http://www.w3.org/2004/01/pp-impl/55082/status",
doRDFa: "1.1",
localBiblio: {
- "HTTPBIS-SEMANTICS": {
- title: "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content"
- , href: "http://tools.ietf.org/html/draft-ietf-httpbis-p2-semantics/"
+ "READ-COMMITTED": {
+ title: "Wikipedia: Isolation (database systems)"
+ , href: "http://en.wikipedia.org/wiki/Isolation_%28database_systems%29#Read_committed"
, authors: [
- "R. Fielding"
- , "J. Reschke"
+ "Various"
]
- , status: "In Last Call"
- , publisher: "IETF"
+ , status: "N/A"
+ , publisher: "Wikipedia"
},
- "RFC2817": {
- title: "Upgrading to TLS Within HTTP/1.1"
- , href: "http://tools.ietf.org/html/rfc2817"
+ "NON-REPEATABLE-READS": {
+ title: "Wikipedia: Isolation (database systems)"
+ , href: "http://en.wikipedia.org/wiki/Isolation_(database_systems)#Non-repeatable_reads"
, authors: [
- "R. Khare"
- , "S. Lawrence"
+ "Various"
]
- , status: "Proposed Standard"
- , publisher: "IETF"
+ , status: "N/A"
+ , publisher: "Wikipedia"
},
"RFC5005": {
title: "Feed Paging and Archiving"
@@ -213,10 +212,11 @@
<body>
<section id='abstract'>
This document describes a model for clients and servers to be able to efficiently retrieve large Linked Data Platform
-Resources representations by splitting up the responses into separate URL-addressable page resources.
+Resource representations by splitting up the responses into separate URL-addressable page resources.
</section>
<section class="informative" id="intro">
+<!-- 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
@@ -231,32 +231,37 @@
<h1>Terminology</h1>
<section id="terms-from-ldp">
-<h2>Terms re-used from [[!LDP]].</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>This section is non-normative. It summarizes a subset of terms formally defined in [[LDP]] for the reader's convenience.
</p>
<dl class="glossary">
<dt><dfn>LDP server</dfn></dt>
- <dd>A conforming HTTP server [[!HTTP11]] that follows the rules defined by [[!LDP]]
+ <dd>A conforming HTTP server [[HTTP11]] that follows the rules defined by [[LDP]]
when it is serving LDPRs and LDPCs.
<p></p></dd>
<dt><dfn>LDP client</dfn></dt>
- <dd>A conforming HTTP client [[!HTTP11]] that follows the rules defined by [[!LDP]] when
- interacting with a <a title="">LDP server</a>.
+ <dd>A conforming HTTP client [[HTTP11]] that follows the rules defined by [[LDP]] when
+ interacting with a <a>LDP server</a>.
<p></p></dd>
<dt><dfn>Linked Data Platform Resource</dfn> (<abbr title="Linked Data Platform Resource">LDPR</abbr>)</dt>
<dd>A HTTP resource whose state is represented in any way that conforms to the
- patterns and conventions in [[!LDP]].<p></p></dd>
+ patterns and conventions in [[LDP]].<p></p></dd>
<dt><dfn>Linked Data Platform RDF Source</dfn> (<abbr title="Linked Data Platform RDF Source">LDP-RS</abbr>)</dt>
<dd>An <a title="Linked Data Platform Resource">LDPR</a> whose state is fully represented in RDF.
<p></p></dd>
+ <dt><dfn>Linked Data Platform Container</dfn> (<abbr title="Linked Data Platform Container">LDPC</abbr>)</dt>
+ <dd>A LDP-RS representing a collection of <a title="Linked Data Platform Resource">LDPRs</a> linked by
+ <a>membership triples</a> and <a>containment triples</a>.
+ <p></p></dd>
+
<dt><dfn>Membership triples</dfn></dt>
- <dd>A set of triples that lists an <a title="Linked Data Platform RDF Source">LDP-RS's</a> members.
+ <dd>A set of triples that lists an <a title="Linked Data Platform Container">LDPC's</a> members.
<p></p></dd>
<dt><dfn>Containment triples</dfn></dt>
@@ -271,12 +276,14 @@
<section id="terms-from-paging">
<h2>Terms normatively defined by this specification</h2>
-<p>Terminology is based on W3C's Architecture of the World Wide Web [[WEBARCH]], Hyper-text Transfer Protocol [[HTTP11]] and Linked Data Platform [[LDP]].
+<p>The following terminology is based on W3C's Architecture of the World Wide Web [[WEBARCH]],
+ Hyper-text Transfer Protocol [[HTTP11]] and Linked Data Platform [[LDP]].
</p>
<dl class="glossary">
<dt><dfn>Paged resource</dfn></dt>
- <dd>A LDP-RS whose representation may be too large to fit in a single HTTP response, for which an
- LDP server offers a sequence of single-page <a title="Linked Data Platform RDF Source">LDP-RSs</a>.
+ <dd>A LDPR whose representation may be too large to fit in a single HTTP response, for which an
+ <a>LDP Paging server</a> offers a sequence of single-page <a title="Linked Data Platform Resource">LDPRs</a>.
+ <p>
When the representations of the sequence's resources
are combined by a client, the client has a (potentially incomplete or incoherent) copy of the paged resource's
state. If a paged resource <var>P</var> is a LDP-RS and is broken into a sequence of pages
@@ -285,21 +292,24 @@
a subset of the triples in <var>P</var>.
LDP allows paging of resources other than <a title="Linked Data Platform RDF Source">LDP-RSs</a>,
but does not specify how clients combine
- their representations. See <a href="#ldpr-Paging" class="sectionRef"></a> for additional details. For readers
+ their representations. See <a href="#ldpr-Paging" class="sectionRef"></a> for additional details.
+ </p>
+ For readers
familiar with paged feeds [[RFC5005]], a paged resource is similar to a logical feed.
Any resource could be considered to be a paged resource consisting of exactly one page,
although there is no known advantage in doing so.
<p></p></dd>
<dt><dfn>Single-page resource</dfn></dt>
- <dd>One of a sequence of related <a title="Linked Data Platform RDF Source">LDP-RSs</a>
+ <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.
For readers
familiar with paged feeds [[RFC5005]], a single-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 is stable</a>.
+ <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
@@ -336,6 +346,33 @@
header [[!RFC5988]][[!HTML5]] where the target URI is <var>P<sub>i=1...n-1</sub></var>.
<p></p></dd>
+ <dt><dfn>paging link</dfn></dt>
+ <dd>Any of the links defined by LDP Paging:
+ <a title="first page link">first page links</a>,
+ <a title="next page link">next page links</a>,
+ <a title="last page link">last page links</a>,
+ <a title="previous page link">previous page links</a>.
+ <p></p></dd>
+
+ <dt><dfn>forward traversal</dfn></dt>
+ <dd>The process of following <a title="next page link">next page links</a> from
+ some starting point.
+ <p>
+ Note: "forward" should <i>not</i> be read to mean anything more than a name for one direction through the sequence.
+ For example, following forward links does not imply that resources later in the sequence are newer; the forward direction might
+ correspond to moving forward in time, but any such relationship is server-specific not implied by LDP Paging
+ absent additional concrete assertions like those defined later for LDPC representations.
+ </p>
+ <p></p></dd>
+
+ <dt><dfn>backward traversal</dfn></dt>
+ <dd>The process of following <a title="previous page link">previous page links</a> from
+ some starting point.
+ <p>
+ Note: "backward" should <i>not</i> be read to mean anything more than a name for one direction through the sequence.
+ </p>
+ <p></p></dd>
+
</dl>
</section>
@@ -345,8 +382,9 @@
<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 foaf: <http://xmlns.com/foaf/0.1/>.
+ <pre style="word-wrap: break-word; white-space: pre-wrap;">
+ @prefix dcterms: <http://purl.org/dc/terms/>.
+ @prefix foaf: <http://xmlns.com/foaf/0.1/>.
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
</pre>
@@ -387,6 +425,18 @@
<p><em>TODO</em>: Confirm this client MUST for server-initiated paging</p>
</section>
+ <section id="ldpp-server-initiated"><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>.
+ </h2>
+ </section>
+
+ <section id="ldpp-server-initiated"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST NOT
+ assume that any <a title="single-page resource">single-page resource's</a> <a title="paging link">paging links</a>
+ will remain unchanged when the <a>single-page resource</a> is retrieved more than once. Doing so would
+ conflict with a server's ability to <a href="#ldpr-pagingGET-sequences-change">add pages to a sequence</a>, for example.
+ </h2>
+ </section>
+
</section>
</section> <!-- Client constraints -->
@@ -395,19 +445,42 @@
<section class="informative" id="ldpr-informative">
<h2>Introduction</h2>
-<!-- TODO: Rewrite intro -->
- <p>Linked Data Platform Resources (<dfn><abbr title="Linked Data Platform Resources">LDPRs</abbr></dfn>) are HTTP resources
- that conform to the simple patterns and conventions in this section.
- HTTP requests to access, modify, create or delete LDPRs are accepted
- and processed by <a title="LDP server">LDP servers</a>. Most LDPRs are domain-specific resources
- that contain data for an entity in some domain, which could be
- commercial, governmental, scientific, religious, or other.</p>
- <p>Some of the rules defined in this document provide
- clarification and refinement of the base Linked Data rules [[LINKED-DATA]];
- others address additional needs.</p>
- <p>The following sections define the conformance rules for LDP Paging servers when serving LDP-RSs.
- This document also explains <a href="#ldpr-Paging">how a server paginates an LDP-RS's representation</a> if it gets too big.
- Companion non-normative documents describe additional guidelines for use when interacting with LDPRs.
+ <p>
+ Some LDPRs are too large to reasonably transmit a representation in a
+ single HTTP response.
+ To address this problem, <a title="LDP Paging server">LDP Paging servers</a> can support a technique called Paging.
+ When a client retrieves such a resource, the server redirects the client to a "first page" resource, and includes in its response
+ a link to the next part of the resource's state, all at URLs of the server's choosing.
+ The representation of <a title="Single-page resource">each page of an LDPR</a>
+ is typically a subset of the <a title="Paged resource">paged resource</a>.
+ Any LDPR can be paged, but certain aspects of paging like ordering are only well-defined for LDP-RS's or LDPCs.
+ </p>
+ <p>
+ Logically, paging breaks up the <a>paged resource</a>
+ into a list of <a title="Single-page resource">single-page resources</a> (chunks) whose representations the client can retrieve.
+ A server can offer links that support forward and/or backward traversal of
+ the pages, but it has to offer at least one.
+ Likewise, some clients will be interested in knowing whether or not competing requests altered the
+ <a>paged resource</a> while the client was retrieving pages, since LDP paging does not guarantee
+ that those alterations were reflected in any <a>single-page resource</a> received by the client.
+ Regardless of the server implementation, LDP only guarantees that while traversing a series of pages that
+ the client observes data that is equivalent to a database that uses
+ read committed isolation [[READ-COMMITTED]];
+ specifically, clients can observe
+ non-repeatable reads [[NON-REPEATABLE-READS]] while traversing pages served by
+ <a title="LDP Paging server">LDP Paging servers</a>.
+ LDP Paging does guarantee, however, that any information in the LDPR continuously present (neither added nor deleted) in the
+ <a title="Paged resource">paged resource</a> across the entire period of time when the client is retrieving pages will
+ be present in at least one <a>single-page resource</a>.
+ LDP Paging defines a mechanism for informing clients that the <a>paged resource</a> has been changed so that they can, for example,
+ abandon a page traversal as early as possible.
+ </p>
+ <p>
+ A list of <a title="Single-page resource">single-page resources</a> is inherently ordered by the links
+ that a <a>LDP Paging server</a> exposes on any <a>paged resource</a>. LDP Paging defines
+ a vocabulary for communicating the ordering algorithm used by the <a>LDP Paging server</a>
+ only in the case where the <a>paged resource</a> is an LDPC; other specifications or future
+ versions of LDP Paging might define ordering in other cases.
</p>
</section>
@@ -417,25 +490,26 @@
<section class="informative" id="ldpr-PagingIntro">
<h3>Introduction</h3>
- <p>It sometimes happens that a
- resource is too large to reasonably transmit its representation in a
- single HTTP response.
- To address this problem, servers should support a technique called Paging.
- When a client retrieves such a resource, the server redirects the client to a "first page" resource, and includes in its response
- a link to the next part of the resource's state, all at URLs of the server's choosing.
- The triples in the representation of the <a title="Single-page resource">each page of an LDPR</a>
- are typically a subset of the triples from the <a title="Paged resource">paged resource</a>.
+ <p>
+ <a title="LDP Paging server">LDP Paging servers</a> may respond to requests for a
+ resource by redirecting to the first page of the resource and, with that, returning
+ a <a>next page link</a> containing the URL for the next page.
+ Clients inspect each response for the link to see if additional pages
+ are available; paging does not affect the choice of HTTP status code.
+<!-- TODO: link to formal definition/clauses -->
+ Note that paging provides a weak guarantee of completeness: if and only if it is the case
+ that no changes to the <a>paged resource</a> are made while
+ a client retrieves every <a>single-page resource</a> logically comprising it,
+ then the client will expect to have a complete picture of the <a>paged resource</a>
+ at a point in time. Since LDP Paging ensures that clients have a way to find
+ out when the <a>paged resource</a> has changed, this is a stronger guarantee
+ than the one described for paged feeds [[RFC5005]], but it does require the client
+ to detect when the condition holds.
+ Paging <i>does not guarantee</i> that it will ever be possible to successfully
+ retrieve all the <a>single-page resource</a>s without the <a>paged resource</a>
+ being added to or changed, so clients requiring such a guarantee
+ may not find all <a>paged resource</a>s usable in practice.
</p>
- <p><a title="LDP server">LDP servers</a> may respond to requests for a
-<!-- TODO: LDP servers => LDP paging servers, throughout -->
- resource by redirecting to the first page of the resource and, with that, returning
- a <code>Link <next-page-URL>;type='next'</code> header containing the URL for the next page.
- Clients inspect each response for the link header to see if additional pages
- are available; paging does not affect the choice of HTTP status code.
-<!-- TODO: Search/remove lossy -->
- Note that paging is lossy, as described in [[RFC5005]], and so (as stated there)
- clients should not make any assumptions about a set of pages being a complete or
- coherent snapshot of a resource's state.</p>
<p>
Looking at an example resource representing Example Co.'s customer
relationship data, identified by the URI <code>http://example.org/customer-relations</code>,
@@ -443,13 +517,16 @@
The client
retrieves <code>http://example.org/customer-relations</code>, and
the server responds with <a href="#atrisk-333">status code <code>333 Returning Related</code></a>,
- a <code>Location: http://example.org/customer-relations?page1</code> HTTP response header,
+ 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 -->
<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 header
+# 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'
# This Link header is how clients discover the URI of the next page in sequence,
# and that the resource supports paging.
@@ -492,9 +569,13 @@
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'
+#
# There is no "next" Link in the server's response, so this is the final page.
#
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@@ -522,99 +603,85 @@
final page. To indicate this is the last page, the server omits the <code>Link: rel='next'</code>
header in its response.
</p>
+ <!-- TODO: show it both ways; if a competing change hit the container, or not -->
<p>
As mentioned above, retrieving all the pages offered by a server gives no guarantee to a client
- that it knows the entire state of the server. For example, after the server constructs the
+ that it knows the entire state of the <a>paged resource</a> on the server, unless the client also
+ verifies that the <a>paged resource</a> has not changed. For example, after the server constructs the
the first page representation, another
actor could delete <code>client#BettyASmith</code> from the server.
</p>
</section>
+<section class="informative" id="ldpr-impl">
+
+<h3>Paging without maintaining session state</h3>
+ <p>
+ Server implementers naturally have concerns when they are expected to maintain per-client state
+ because of the scalability limitations that per-client state implies.
+ LDP Paging carries no such requirement, although this may not be obvious at first glance.
+ Since URLs are opaque to clients [[WEBARCH]], a server
+ is free to encode the information required for it to know where to start the next page inside
+ its next page links, for example.
+ </p>
+ <p>
+ Observe that in the preceding example, it is likely that the <var>page n</var> URIs are all of the form
+ <code>http://example.org/customer-relations?p=<var>n</var></code>,
+ where <var>n</var> is <var>2..n</var>.
+ If the server allocates <code>o:client</code> representations to pages randomly, it's not obvious how to avoid
+ keeping per-client state of one kind or another on the server while still sending all the representations on
+ at least one page. In the common case where the list has an
+ ordering (either a natural one or one imposed by the implementation) however, it is easy to avoid
+ keeping per-client state on the server.
+ </p>
+ <p>
+ One trivial case is "fixed order"; if the server always sends
+ <code>o:client</code> representations in the order
+ <code>#JohnZSmith, #BettyASmith, #JoanRSmith, #GlenWSmith, #AlfredESmith</code> (or indeed,
+ in <i>any</i> predictable order), then it can put the "last seen" identifier in the <a>next page link</a>
+ of each <a>single-page resource</a> as it is retrieved <em>by each client</em>. The "session state"
+ is, in effect, kept by the client.
+ In this case, the <a>next page link</a> in the first page might be:
+ </p>
+ <pre class="example" id="paging-no-session-state1">
+ Link: <http://example.org/customer-relations?resumeafter=JoanRSmith>; rel='next'
+ </pre>
+ <p>
+ If the server also supports <a>backward traversal</a>, then the second page's
+ <a>previous page link</a> might be:
+ </p>
+ <pre class="example" id="paging-no-session-state2">
+ Link: <http://example.org/customer-relations?resumebefore=GlenWSmith>; rel='next'
+ </pre>
+ <p>
+ Keep in mind that this is an exemplary server implementation decision; it is not prescribed by
+ LDP Paging, and other choices are certainly possible. As long as the URIs used in links
+ are opaque to clients, any choice is permissible.
+ </p>
+</section>
<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>,
- <a title="LDP server">LDP servers</a> that support paging must
+ <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="Single-page resource">single-page resources</a>.
+ <!-- TODO: remove this clause? circular ref -->
</p>
- <section id="ldpr-page-large"><h2 class="normal"><a title="LDP server">LDP servers</a> SHOULD allow clients to retrieve large LDP-RSs in
+ <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 -->
+ <a title="LDP Paging server">LDP Paging servers</a> SHOULD allow clients to retrieve large LDP-RSs in
pages.
See <a href="#ldpr-Paging" class="sectionRef"></a> for additional requirements associated with <a title="Paged resource">paged resources</a>.
</h2></section><!-- Was 4.2.14 / #ldpr-4_2_14 -->
- <section id="ldpr-split-any"><h2 class="normal"><a title="LDP server">LDP servers</a> MAY
+ <section id="ldpr-split-any"><h2 class="normal">
+ <!-- TODO: I thought we only defined paging for LDP-RS's so is this right? -->
+ <a title="LDP Paging server">LDP Paging servers</a> MAY
treat any resource (LDP-RS or not) as a <a title="Paged resource">paged resource</a>.
See <a href="#ldpr-Paging" class="sectionRef"></a> for additional details.
</h2></section><!-- Was 4.2.15 / #ldpr-4_2_15 -->
- <section id="ldpr-pagingGET-sequences-change"><h2 class="normal"><a title="LDP server">LDP servers</a> MAY
- add <a title="Single-page resource">single-page resources</a> to a
- <a title="Paged resource">paged resource's</a> sequence over time,
- but SHOULD only add pages to the end of a sequence.
- </h2><!-- Was 4.10.2.1 / #ldpr-pagingGET-sequences-change -->
- <blockquote>Non-normative note:
- As a result, clients retrieving any <a title="Single-page resource">single-page resource</a> several times can observe its place in the sequence
- change as the state of the <a title="Paged resource">paged resource</a> changes.
- For example, a nominally last page's server might provide a
- <a>next page link</a> when the page is retrieved. Similar situations arise when the page sequence crosses server boundaries;
- server A might host the initial portion of a sequence that links to the last page server A is aware of,
- hosted on server B, and server B might extend the sequence of pages.
- </blockquote>
-
- <section id="ldpr-pagingGET-first-allowed-onpages"><h2 class="normal">
- <a title="LDP server">LDP servers</a> MAY provide
- a <a>first page link</a> when responding to
- requests with any <a title="Single-page resource">single-page resource</a> as the <code>Request-URI</code>.
- </h2></section><!-- Was 4.10.2.1.1 / #ldpr-pagingGET-sequences-change -->
-
- <section id="ldpr-pagingGET-last-allowed-onpages"><h2 class="normal"><a title="LDP server">LDP servers</a> MAY
- provide a <a>last page link</a>
- in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a> as the <code>Request-URI</code>.
- </h2></section><!-- Was 4.10.2.1.3 / #ldpr-pagingGET-last-allowed-onpages -->
- </section>
-
- <section id="ldpr-pagingGET-next-reqd"><h2 class="normal"><a title="LDP server">LDP servers</a> MUST
- provide a <a>next page link</a>
- in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a>
- <em>other than the final page</em>
- as the <code>Request-URI</code>.
- This is the mechanism by which clients can discover the URL of the next page.
- </h2><!-- Was 4.10.2.2 / #ldpr-pagingGET-next-reqd-change -->
-
- <section id="ldpr-pagingGET-lastnext-prohibited"><h2 class="normal"><a title="LDP server">LDP servers</a> MUST NOT
- provide a <a>next page link</a>
- in responses to <code>GET</code> requests with the final <a title="Single-page resource">single-page resource</a>
- as the <code>Request-URI</code>.
- This is the mechanism by which clients can discover the end of the page sequence
- as currently known by the server.
- </h2></section><!-- Was 4.10.2.2.1 / #ldpr-pagingGET-lastnext-prohibited -->
-
- <section id="ldpr-pagingGET-prev-allowed"><h2 class="normal"><a title="LDP server">LDP servers</a> MAY
- provide a <a>previous page link</a>
- in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a>
- <em>other than the first page</em>
- as the <code>Request-URI</code>.
- This is one mechanism by which clients can discover the URL of the previous page.
- </h2></section><!-- Was 4.10.2.2.2 / #ldpr-pagingGET-prev-allowed -->
-
- <section id="ldpr-pagingGET-firstprev-prohibited"><h2 class="normal"><a title="LDP server">LDP servers</a> MUST NOT
- provide a <a>previous page link</a>
- in responses to <code>GET</code> requests with the <em>first</em> <a title="Single-page resource">single-page resource</a>
- as the <code>Request-URI</code>.
- This is one mechanism by which clients can discover the beginning of the page sequence
- as currently known by the server.
- </h2></section><!-- Was 4.10.2.2.3 / #ldpr-pagingGET-firstprev-prohibited -->
- </section>
-
- <section id="ldpr-pagingGET-page-type-reqd"><h2 class="normal"><a title="LDP server">LDP servers</a> MUST
- provide an HTTP <code>Link</code>
- header whose target URI is <code>http://www.w3.org/ns/ldp#Page</code>, and whose link relation type is <code>type</code> [[!RFC5988]]
- in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a>
- as the <code>Request-URI</code>.
- This is one mechanism by which clients know that the resource is one of a sequence of pages.
- </h2></section><!-- Was 4.10.2.4 / #ldpr-pagingGET-page-type-reqd -->
-
<div class="atrisk" id="atrisk-333"><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>
@@ -639,18 +706,165 @@
<li><p>
Once LDP-Paging is a
Candidate Recommendation, the LDP WG will make an assessment based on the status at IETF,
- working with the W3C Director, to either use the newly defined response code
+ working with the W3C Director, to either use the newly defined response code 333
as documented in this section or to revert to a classic
<code>303</code> response pattern.
</p></li>
</ul>
</div>
- <section id="ldpr-status-code"><h2 class="normal"><a title="LDP server">LDP servers</a> SHOULD respond
+ <section id="ldpr-status-code"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> SHOULD respond
with HTTP status code <code>333 Returning 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 MAY be used.
</h2></section>
+
+ <section id="ldpr-guarantee-show-unchanged"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> MUST
+ ensure that all state present in the <a>paged resource</a> throughout a client's <em>entire</em> traversal operation
+ is represented in at least one <a>single-page resource</a>. In other words, whatever subset of the
+ <a>paged resource</a> that is <em>not added, updated, or removed during the client's traversal</em>
+ of its pages has to be present in one of the pages.
+ </h2>
+ <blockquote>Non-normative note:
+ As a consequence, if the <a>paged resource</a> does not change <em>at all</em> during the traversal,
+ then the client has a complete view of its state as given by the negotiated response media type
+ <em>at the point in time when the final page was retrieved</em>.
+ If the <a>paged resource</a> <em>does</em> change during the traversal, then only the portions that
+ were actually updated will differ; the client has no LDP Paging-provided means for knowing in what
+ way(s) its view differs from that of the server in this case.
+ </blockquote>
+ <blockquote>Non-normative note:
+ When the <a>paged resource</a> is an LDP-RS,
+ the expectation is that all triples untouched by changes to the <a>paged resource</a> have been
+ given to the client during the traversal; it is possible that some subset of the changed triples, including all or none of them,
+ have been provided to the client, but the client has no way to know which.
+ </blockquote>
+ </section>
+
+ <div class="ldp-issue-pending" id="question-link-relation"><p class="ldp-issue-title">Background and feedback requested on the link relation type used below</p>
+ <p>Likely suspects from the <a href="http://www.iana.org/assignments/link-relations/link-relations.xml">IANA link relation registry</a> that the editors examined:</p>
+ <ul>
+ <li><p>
+ <a href="http://tools.ietf.org/html/rfc6596">canonical</a> (see section 3, source has no TOC/anchors) may be
+ close enough; the content at the context URI can explicitly be a subset of that at the target (canoncial) URI.
+ Certain cited functions like link consolidation are completely appropriate; if we believe the authors about its
+ usage by crawlers/indexers however, we may be working at cross purposes.
+ </p></li>
+ <li><p>
+ <a href="http://tools.ietf.org/html/rfc6573">collection</a> has muddy semantics in the case where
+ the paged resource is an LDPC (i.e. the case we care most about, in terms of LDP's use cases). We could
+ probably get away with using collection, but its "inverse" item (defined in the same RFC) would definitely
+ have a <em>different</em> semantic than what we want for paging (the RFC thinks an item is a member of the
+ collection, but a page of an LDPC might have multiple LDP members on it, if we consider inlining in any form).
+ It would have the net effect of looking at the LDPC as a generic RDF source, and "forgetting" within the paging
+ spec that LDPCs have members - something that I'm sure we could all do, but pity the adopters using both
+ together and trying to keep the different collection/item "models" untangled.
+ </p></li>
+ <li><p>
+ <a href="http://tools.ietf.org/html/rfc4287#page-21">enclosure</a> has "good match" semantics,
+ but a name that's awkward for our case.
+ </p></li>
+ <li><p>
+ <a href="http://tools.ietf.org/html/rfc5005">Atom Feed Paging and Archiving</a> has no analog for the logical feed.
+ </p></li>
+ <li><p>
+ We also have the choice of defining-new, either an extension link relation (we just mint our own URI, done)
+ or as a short name (requiring a small-but-not-zero registration template).
+ </p></li>
+ </ul>
+ </div>
+
+ <section id="ldpr-notify-changes"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> MUST
+ enable a client to detect any change to the <a>paged resource</a> that occurs while the client is retrieving pages.
+ In order to do so, servers MUST include a HTTP <code>Link</code> header on all
+ HTTP <code>GET</code> responses
+ whose context URI identifies the <a>single-page resource</a> being retrieved,
+ whose target URI identifies the <a>paged resource</a>,
+ whose link relation type is <code>canonical</code>,
+ and
+ whose link extension parameters include the parameter name <code>etag</code>
+ and a corresponding parameter value that changes whenever the ETag [[!HTTP11]]
+ of the <a>paged resource</a> would change.
+ For example: <code>Link: <http://example.org/customer-relations>; rel='canonical'; etag="v1"</code>
+ </h2></section><!-- TODO: change http11 to bis -->
+
+ <section id="ldpr-pagingGET-sequences-change"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> MAY
+ add <a title="Single-page resource">single-page resources</a> to a
+ <a title="Paged resource">paged resource's</a> sequence over time,
+ but SHOULD only add pages to the end of a sequence.
+ </h2><!-- Was 4.10.2.1 / #ldpr-pagingGET-sequences-change -->
+ <blockquote>Non-normative note:
+ As a result, clients retrieving any <a>single-page resource</a> several times can observe its place in the sequence
+ change as the state of the <a>paged resource</a> changes.
+ For example, a nominally last page's server might provide a
+ <a>next page link</a> when the page is retrieved later. Similar situations arise when the page sequence crosses server boundaries;
+ server A might host the initial portion of a sequence that links to the last page server A is aware of,
+ hosted on server B, and server B might extend the sequence of pages.
+ </blockquote>
+ </section>
+
+ <section id="ldpr-pagingGET-first-allowed-onpages"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> MAY provide
+ a <a>first page link</a> when responding to
+ requests with any <a title="Single-page resource">single-page resource</a> as the <code>Request-URI</code>.
+ </h2></section><!-- Was 4.10.2.1.1 / #ldpr-pagingGET-sequences-change -->
+
+ <section id="ldpr-pagingGET-last-allowed-onpages"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> MAY
+ provide a <a>last page link</a>
+ in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a> as the <code>Request-URI</code>.
+ </h2></section><!-- Was 4.10.2.1.3 / #ldpr-pagingGET-last-allowed-onpages -->
+
+ <section id="ldpr-pagingGET-next-reqd"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> MUST
+ provide a <a>next page link</a>
+ in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a>
+ <em>other than the final page</em>
+ as the <code>Request-URI</code>.
+ This is the mechanism by which clients can discover the URL of the next page.
+ </h2><!-- Was 4.10.2.2 / #ldpr-pagingGET-next-reqd-change -->
+ </section>
+
+ <section id="ldpr-pagingGET-lastnext-prohibited"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> MUST NOT
+ provide a <a>next page link</a>
+ in responses to <code>GET</code> requests with the final <a title="Single-page resource">single-page resource</a>
+ as the <code>Request-URI</code>.
+ This is the mechanism by which clients can discover the end of the page sequence
+ as currently known by the server.
+ </h2></section><!-- Was 4.10.2.2.1 / #ldpr-pagingGET-lastnext-prohibited -->
+
+ <section id="ldpr-pagingGET-prev-allowed"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> MAY
+ provide a <a>previous page link</a>
+ in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a>
+ <em>other than the first page</em>
+ as the <code>Request-URI</code>.
+ This is one mechanism by which clients can discover the URL of the previous page.
+ </h2></section><!-- Was 4.10.2.2.2 / #ldpr-pagingGET-prev-allowed -->
+
+ <section id="ldpr-pagingGET-firstprev-prohibited"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> MUST NOT
+ provide a <a>previous page link</a>
+ in responses to <code>GET</code> requests with the <em>first</em> <a title="Single-page resource">single-page resource</a>
+ as the <code>Request-URI</code>.
+ This is one mechanism by which clients can discover the beginning of the page sequence
+ as currently known by the server.
+ </h2></section><!-- Was 4.10.2.2.3 / #ldpr-pagingGET-firstprev-prohibited -->
+
+ <section id="ldpr-pagingGET-page-type-reqd"><h2 class="normal">
+ <a title="LDP Paging server">LDP Paging servers</a> MUST
+ provide an HTTP <code>Link</code>
+ header whose target URI is <code>http://www.w3.org/ns/ldp#Page</code>, and whose link relation type is <code>type</code> [[!RFC5988]]
+ in responses to <code>GET</code> requests with any <a title="Single-page resource">single-page resource</a>
+ as the <code>Request-URI</code>.
+ This is one mechanism by which clients know that the resource is one of a sequence of pages.
+ </h2></section><!-- Was 4.10.2.4 / #ldpr-pagingGET-page-type-reqd -->
+
</section>
</section> <!-- h2 -->
@@ -676,7 +890,7 @@
<section id="ldpc-ordering"><h2 class="normal">Ordering</h2>
<p>
- There are many cases where an ordering of the members of the
+ There are many cases where an ordering of the members of a
container is important. LDP does not provide any particular support
for server ordering of members in containers, because any client can
order the members in any way it chooses based on the value of any
@@ -687,11 +901,12 @@
constructs like Seq and List for expressing order.
</p>
<p>
- Order becomes more important for <a title="LDP server">LDP servers</a> when containers are
+ 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.
- In cases where ordering is important, an LDP server exposes all the
+ <!-- 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. -->
+ 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.
When the sort is ascending, all the members on a current page have a
@@ -711,6 +926,7 @@
</p>
<p>Here is an example container described
previously, with representation for ordering of the assets:</p>
+<!-- TODO: fix ^ previously -->
<pre class="example" id="ldpc-ex-ordering">
# The following is the ordered representation of
# http://example.org/netWorth/nw1/assetContainer/
@@ -773,9 +989,10 @@
<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="ldpp-prefer"><h2 class="normal">(From [[!LDP]])<a title="LDP server">LDP servers</a>
+ <section id="ldpp-prefer"><h2 class="normal">(From [[!LDP]]) <a title="LDP Paging server">LDP Paging servers</a>
SHOULD respect all of a client's LDP-defined hints, for example
<a href="#prefer-parameters">which subsets of LDP-defined state</a>
the client is interested in processing,
@@ -788,16 +1005,19 @@
<a title="Single-page resource">pages</a>
(see <a href="#ldpr-Paging" class="sectionRef"></a>).
</h2></section>
- <!-- TODO: Need to rework this^ -->
+ <!-- TODO: Need to rework this^ and possibly relocate it ... does not apply only to LDPCs -->
</section>
<section id="ldpc-HTTP_GET">
<h2>HTTP GET</h2>
- <section id="ldpc-sortcriteriaobj"><h2 class="normal"><a title="LDP server">LDP servers</a> MAY
+ <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
- order. If the server does so, it MUST specify the order using a triple
+ <!-- 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
whose subject is the page URI,
whose predicate is <code>ldp:containerSortCriteria</code>,
and whose object is a <code>rdf:List</code> of
@@ -1013,6 +1233,8 @@
<!-- <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-05-20 - Spec Sandro's proposal, choose link relation for detection of paged resource changes (JA) </li>
+ <li>2014-05-19 - Rewrote non-normative parts, cleaned up terminology, ordering undefined when paging non-LDPC LDPRs (JA) </li>
<li>2014-05-15 - Fixed Respec messages by adding "terminology from LDP" section (JA) </li>
<li>2014-03-10 - Fixed namespaces (SS) </li>
<li>2014-02-18 - Split off LDP-Paging from LDP (SS) </li>