ldp-paging.html
author Steve Speicher <sspeiche@gmail.com>
Mon, 26 Jan 2015 11:51:28 -0500
changeset 938 859f98c26867
parent 935 4c9e4a9dc2e8
child 972 7d0c5926dff6
permissions -rw-r--r--
AC rep comment #2 on clarity on types in examples
<!DOCTYPE html>
<!-- 
	TODO: Once companion documents (best practices, primer) have URLs, link to them.  Search on "companion".
	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 linkage amongst pages and (HEAD on) the base resource.
     Maybe also insert HEAD on base as new first example instead of relying on text alone.
 -->
<html>
  <head>
    <title>Linked Data Platform Paging 1.0</title>
    <meta http-equiv='Content-Type' content='text/html;charset=utf-8'/>
    <!-- 
      === NOTA BENE ===
      For the three scripts below, if your spec resides on dev.w3 you can check them
      out in the same tree and use relative links so that they'll work offline,
     -->
    <script src='https://www.w3.org/Tools/respec/respec-w3c-common' class='remove' async></script> 
    <script class='remove'>
      var respecConfig = {
          // specification status (e.g. WD, LCWD, NOTE, etc.). If in doubt use ED.
          specStatus:           "CR",
          
          // the specification's short name, as in http://www.w3.org/TR/short-name/
          shortName:            "ldp-paging",

          // if your specification has a subtitle that goes below the main
          // formal title, define it here
          // subtitle   :  "an excellent document",

          // if you wish the publication date to be other than today, set this
          publishDate:  "2014-12-11",

          // if the specification's copyright date is a range of years, specify
          // the start date here:
          // copyrightStart: "2005"

          // if there is a previously published draft, uncomment this and set its YYYY-MM-DD date
          // and its maturity status
          previousPublishDate:  "2014-09-09",
          previousMaturity:  	"WD",
          previousURI: 			"http://www.w3.org/TR/2014/WD-ldp-20140909/",
          
          processVersion: 		2005,

          // if there a publicly available Editor's Draft, this is the link
          edDraftURI:           "http://www.w3.org/2012/ldp/hg/ldp-paging.html",
          implementationReportURI: "https://dvcs.w3.org/hg/ldpwg/raw-file/default/tests/reports/paging/ldp-paging.html",

          // if this is a LCWD, uncomment and set the end of its review period
          // lcEnd: "2014-09-30",
          crEnd: "2014-01-08",
          
          // Only include h1 and h2 level
          maxTocLevel: 2,

          // if you want to have extra CSS, append them to this list
          // it is recommended that the respec.css stylesheet be kept
          //extraCSS:             ["https://dvcs.w3.org/hg/ldpwg/css/respec.css"],

          // editors, add as many as you like
          // only "name" is required
          editors:  [
              { name: "Steve Speicher", url: "http://stevespeicher.blogspot.com",
                company: "IBM Corporation", companyURL: "http://ibm.com/" },
              { name: "John Arwe", url: "https://www.ibm.com/developerworks/mydeveloperworks/groups/service/html/allcommunities?userid=120000CAW7",
                company: "IBM Corporation", companyURL: "http://ibm.com/" },
			  {name: "Ashok Malhotra", url: "mailto:ashok.malhotra@oracle.com",
			    company: "Oracle Corporation", companyURL: "http://www.oracle.com" },
          ],

          // authors, add as many as you like. 
          // This is optional, uncomment if you have authors as well as editors.
          // only "name" is required. Same format as editors.

          //authors:  [
          //    { name: "Your Name", url: "http://example.org/",
          //      company: "Your Company", companyURL: "http://example.com/" },
          //],
          
          // name of the WG
          wg:           "Linked Data Platform Working Group",
          
          // URI of the public WG page
          wgURI:        "http://www.w3.org/2012/ldp",
          
          // name (without the @w3c.org) of the public mailing to which comments are due
          wgPublicList: "public-ldp-comments",
          
          // URI of the patent status for this WG, for Rec-track documents
          // !!!! IMPORTANT !!!!
          // This is important for Rec-track documents, do not copy a patent URI from a random
          // document unless you know what you're doing. If in doubt ask your friendly neighbourhood
          // Team Contact.
          wgPatentURI:  "http://www.w3.org/2004/01/pp-impl/55082/status",
          doRDFa: "1.1",
			localBiblio:  {
				"READ-COMMITTED": {
					title:    "Wikipedia: Isolation (database systems)"
				,   href:     "http://en.wikipedia.org/wiki/Isolation_(database_systems)#Read_committed"
				,   authors:  [
						"Various"
					]
				,   status:   "N/A"
				,   publisher:  "Wikipedia"
				},
				"NON-REPEATABLE-READS": {
					title:    "Wikipedia: Isolation (database systems)"
				,   href:     "http://en.wikipedia.org/wiki/Isolation_(database_systems)#Non-repeatable_reads"
				,   authors:  [
						"Various"
					]
				,   status:   "N/A"
				,   publisher:  "Wikipedia"
				},
				"LDP-PAGING-TESTSUITE": {
					title:    "Linked Data Platform Paging 1.0 Test Cases"
				,   href:     "https://dvcs.w3.org/hg/ldpwg/raw-file/tip/tests/ldp-paging-testsuite.html"
				,   authors:  [
						"R. Garcia-Castro", "F. Serena"
					]
				,   status:   "Editor's Draft of Working Group Note"
				,   publisher:  "W3C"
				},				
				"REL-CANONICAL": {
					title:    "The Canonical Link Relation"
				,   href:     "http://tools.ietf.org/html/rfc6596"
				,   authors:  [
						"M. Ohye",
						"J. Kupke"
					]
				,   status:   "Informational"
				,   publisher:  "IETF"
				}
			},
      };
    </script>
    <style type="text/css">
    	div.rule {padding-top: 1em;}
    	div.ldp-issue-open {
	    	border-color: #E05252;
			background: #FBE9E9;
			padding: 0.5em;
			margin: 1em 0;
			position: relative;
			clear: both;
			border-left-width: .5em;
			border-left-style: solid;
    	}
    	div.ldp-issue-pending {
	    	border-color: #FAF602;
			background: #F7F6BC;
			padding: 0.5em;
			margin: 1em 0;
			position: relative;
			clear: both;
			border-left-width: .5em;
			border-left-style: solid;
    	}
    	div.ldp-issue-closed {
	    	border-color: #009900;
			background: #BCF7CF;
			padding: 0.5em;
			margin: 1em 0;
			position: relative;
			clear: both;
			border-left-width: .5em;
			border-left-style: solid;
    	}
    	div.ldp-issue-title {
    	    color: #E05252;
    	    padding-right: 1em;
            min-width: 7.5em;
    	}
		.atrisk {
			padding:    1em;
			margin: 1em 0em 0em;
			border: 1px solid #f00;
			background: #ffc;
		}
		.atrisktext {
			/* content:    "Feature At Risk"; */
			display:    block;
			width:  150px;
			margin: -1.5em 0 0.5em 0;
			font-weight:    bold;
			border: 1px solid #f00;
			background: #fff;
			padding:    3px 1em;
		}
		.normal { 
			font-weight: normal;
			font: normal 100% sans-serif;
		}
		.indented { 
			margin-left: +3em;
		}
		tr:nth-of-type(odd),.oddrow { 
			background:#F2F2F2; /* light grey, just enough to differentiate from white */
		}
		td { 
			padding:0 +1ex 0 +1ex; /* add a bit of space from rule/edge to text */
		}
		
    </style>
    <style type="text/css" media="all">
    	code {
    	    font-weight:bold;
			font-size:larger;
    	}
		 /* ReSpec uses color ff4500 for code elements, which does not print well on some black & white printers
		    and is a little hard to read for some folks even on-line. 
			The default code font size was also somewhat too small/hard to read.
		*/
    </style>
  </head>
<body>
<section id='abstract'>
This document describes a HTTP-based protocol for clients and servers to be able to efficiently retrieve large Linked Data Platform
Resource representations by splitting up the responses into separate URL-addressable page resources.
</section>
 
 <section id='sotd'>
   <p>
		The Working Group has addressed all
		raised issues, and other substantive changes have been made, including the decision to separate LDP Paging
		from the Linked Data Platform [[!LDP]].  A test suite has also been made available [[LDP-PAGING-TESTSUITE]]. 
   </p>
 </section>
 
<section class="informative" id="intro">

<h1>Introduction</h1> 
	<p>
		This specification provides a widely re-usable pattern to make the state of a large <a title="Paged resource">paged HTTP resource</a>
		available as a list of smaller subset resources (<a title="In-sequence page resource">pages</a>) whose 
		representations are less burdensome for servers to form.
		<a title="Paged resource">Paged resources</a> must be LDP Resources (LDPRs) [[!LDP]].
		Any LDPR can be paged, but certain aspects of paging like ordering are only well-defined for 
		particular sub-classes of LDPRs, like
		LDP-RSs or LDPCs.
	</p>
	<p>
		When a client attempts to retrieve a <a>paged resource</a>, the server either redirects the client to 
		a "first page" <a title="In-sequence page resource">resource</a> or provides the 
		representation of the "first page" <a title="In-sequence page resource">resource</a> in its response, 
		depending on the client's request preferences and the server's capabilities.  
		The response 
		includes links to other page(s) in the sequence, as do subsequent pages.
		<a title="LDP Paging client">Paging-aware clients</a>
		know how to combine pages of an LDP-RS, and possibly (via other specifications) other LDPRs.
		LDP Paging defines a mechanism by which clients can learn that the <a>paged resource</a> has been changed 
		so that they can, for example, abandon a page traversal as early as possible.
		A detailed example of paging is provided in <a href="#ldpp-ex-mx" class="sectionRef"></a>.
	</p>
	<p>
		When a <a>paged resource</a> is also an LDPC, some additional efficiencies become possible in cases
		where the server predictably assigns members to pages and is able to communicate its assignment
		algorithm to clients.  The <a href="#ldpc" class="sectionRef"></a> defines a facility to communicate 
		the sort order of member-to-page assignments, to handle that common implementation algorithm.
	</p>
	<p>
		For context and background, it could be useful to read <a href="#bib-LDP-UCR">Linked Data Platform Use Case and Requirements</a> [[LDP-UCR]]. 
	</p>
</section>
	
<section id="terms">
<h1>Terminology</h1>

<section id="terms-from-ldp">
<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>
  <dl class="glossary">	

	<dt><dfn>LDP server</dfn></dt>
	<dd>A conforming HTTP server [[RFC7230]] that follows the rules defined by [[LDP]]
	    when it is serving <abbr title="Linked Data Platform Resources">LDPRs</abbr> and 
		<abbr title="Linked Data Platform Containers">LDPCs</abbr>.
	<p></p></dd>	

	<dt><dfn>LDP client</dfn></dt>
	<dd>A conforming HTTP client [[RFC7230]] 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>
		
	<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 [[LDP]].
	<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> [[LDP]].
	<p></p></dd>
	
	<dt><dfn>Membership triples</dfn></dt>
	<dd>A set of triples that lists an <a title="Linked Data Platform Container">LDPC's</a> members [[LDP]].
	<p></p></dd>
	
	<dt><dfn>Containment triples</dfn></dt>
	<dd>
	A set of triples, maintained by an LDPC, that lists documents created by the LDPC but not yet deleted [[LDP]].
	<p></p></dd>

  </dl>

</section>
    
<section id="terms-from-paging">
<h2>Terms normatively defined by this specification</h2>

<p>The following terminology is based on W3C's Architecture of the World Wide Web [[!WEBARCH]], 
	Hyper-text Transfer Protocol ([[!RFC7230]], [[!RFC7231]]) and Linked Data Platform [[!LDP]].
</p>
  <dl class="glossary">	
	<dt><dfn>Paged resource</dfn></dt>
	<dd>A LDPR whose representation may be too large for a server to construct in a single HTTP response
	(e.g. without running out of memory), for which an
	<a>LDP Paging server</a> offers a <a>page sequence</a> that allows clients to obtain subsets of its state
	over some period of time by making multiple HTTP requests.
	<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></p></dd>
	
	<dt><dfn>Page sequence</dfn></dt>
	<dd>A sequence of related <a title="Linked Data Platform Resource">LDPRs</a>
	<var>P<sub>1 (first)</sub>, P<sub>2</sub>, ...,P<sub>n (last)</sub></var>, 
	each of which contains a subset of the <a>paged resource</a>'s state.  
	<p>
	When the representations of the sequence's <a title="In-sequence page resource">resources</a>
	are combined by a client, the client has a copy of the <a>paged resource</a>'s
	state; if the <a>paged resource</a> changed while the client was retrieving the sequence's resources, 
	then the client's copy of the <a>paged resource</a>'s state can be incomplete or inconsistent
	with the state of the <a>paged resource</a> at any single instant in time.
	Thus, it is impossible to strongly guarantee that the result of this retrieval and combination process is the same state that
	the client would obtain using a single request (if that were possible), but LDP does provide
	a way for <a href="#ldpr-notify-changes">clients to detect when the paged resource's state changed</a> during the retrieval process.
	As long as the <a>paged resource</a>'s state did not change during the retrieval process, the 
	client's copy of the <a>paged resource</a>'s state will be as accurate as the server implementation
	allows it to be.
	</p>  
	<p>
	If a paged resource <var>P</var> is a LDP-RS, 
	the representation of each <a>in-sequence page resource</a> contains
	a subset of the triples in <var>P</var>, and a client can merge those graphs to combine them.
	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" class="sectionRef"></a> for additional details.
	</p>  
	For readers
	familiar with paged feeds [[RFC5005]], a <a>page sequence</a> is similar to a paged feed
	and many of the same consideration (echoed above) apply.
	<p></p></dd>
	
	<dt><dfn>In-sequence page resource</dfn></dt>
	<dd>One LDPR in a <a>page sequence</a>, 
	which contains a subset of the state
	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.
	<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 
	<a title="In-sequence page resource"><em>individual page resources</em></a>, 
	in cases where both are mentioned in
	close proximity.  
	</p>
	<p>
	Note: page sequences are described and named with respect to how they are traversed starting from the <a>paged resource</a>,
	using only <a>forward traversal</a>.
	This <em>does not</em> imply anything more; the choice is arbitrary.
	For example, following forward links does not imply that resources later in the sequence are newer; the forward direction might
	correspond to moving forward or backward in time or along some other dimension, but any such relationship is server-specific.
	It is not implied by LDP Paging, 
	absent additional concrete assertions like those <a href="#ldpc-HTTP_GET">defined later</a> for LDPC representations.
	</p>
	<p></p></dd>
	
	<dt><dfn>first page link</dfn></dt>
	<dd>A link to the first <a title="In-sequence page resource">in-sequence page resource</a> <var>P<sub>1 (first)</sub></var>
	of a <a>page sequence</a>.  The first page is the one that a LDP Paging server
	redirects to (<code>303</code> response) in response
	to a retrieval request for the <a>paged resource</a>'s URI.
	Syntactically, a
	HTTP <code>Link &lt;<var>P<sub>1</sub></var>&gt;; rel="first"</code>
	header [[!RFC5988]].
	<p></p></dd>
	
	<dt><dfn>next page link</dfn></dt>
	<dd>A link to the next <a title="In-sequence page resource">in-sequence page resource</a> 
	of a <a>page sequence</a>.  Syntactically, a
	HTTP <code>Link &lt;<var>P<sub>i</sub></var>&gt;; rel="next"</code>
	header [[!RFC5988]] where 
	the context URI identifies some <var>P<sub>i=1 (first)...n-1 (next to last)</sub></var> and
	the target URI identifies <var>P<sub>i+1</sub></var>.
	<p></p></dd>
	
	<dt><dfn>last page link</dfn></dt>
	<dd>A link to the last <a title="In-sequence page resource">in-sequence page resource</a> <var>P<sub>n (last)</sub></var>
	of a <a>page sequence</a>.  
	The last page is the page that terminates a <a>forward traversal</a>, because it contains no <a>next page link</a>.
	Syntactically, a
	HTTP <code>Link &lt;<var>P<sub>n</sub></var>&gt;; rel="last"</code>
	header [[!RFC5988]].
	<p></p></dd>
	
	<dt><dfn>previous page link</dfn></dt>
	<dd>A link to the previous <a title="In-sequence page resource">in-sequence page resource</a>
	of a <a>page sequence</a>  Syntactically, a
	HTTP <code>Link &lt;<var>P<sub>i</sub></var>&gt;; rel="prev"</code>
	header [[!RFC5988]] where 
	the context URI identifies some <var>P<sub>i=2...n (last)</sub></var> and
	the target URI identifies <var>P<sub>i-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 <a>page sequence</a>.
	For example, following forward links does not imply that resources later in the <a>page sequence</a> 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 <a href="#ldpc-HTTP_GET">defined later</a> 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 <a>page sequence</a>.
	</p>
	<p></p></dd>
	
  </dl>
</section>

<section id="conventions">
<h2>Conventions Used in This Document</h2>

	<p>The namespace for LDP Paging is <code>http://www.w3.org/ns/ldp#</code>.</p>
	<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: &lt;http://purl.org/dc/terms/&gt;.
	@prefix foaf:    &lt;http://xmlns.com/foaf/0.1/&gt;.
	@prefix rdf:     &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
	@prefix ldp:     &lt;http://www.w3.org/ns/ldp#&gt;.
	</pre>
</section>
</section>
    
<section id='conformance'>

<p>The status of the sections of Linked Data Platform Paging 1.0 (this document) is as follows:</p>

<ul>
  <li><a href="#intro" class="sectionRef"></a>: <b>non-normative</b></li>
  <li><a href="#terms" class="sectionRef"></a>
	<ul>
	  <li><a href="#terms-from-ldp" class="sectionRef"></a>: <b>non-normative</b></li>
	  <li><a href="#terms-from-paging" class="sectionRef"></a>: <b>normative</b></li>
	  <li><a href="#conventions" class="sectionRef"></a>: <b>normative</b></li>
	</ul>
  </li>
  <li><a href="#conformance" class="sectionRef"></a>: <b>normative</b></li>
  <li><a href="#ldpp-ex-mx" class="sectionRef"></a>: <b>non-normative</b></li>
  <li><a href="#ldppclient" class="sectionRef"></a>: <b>normative</b></li>
  <li><a href="#ldpr" class="sectionRef"></a>: <b>normative</b></li>
  <li><a href="#ldpc" class="sectionRef"></a>: <b>normative</b></li>  
  <li><a href="#security" class="sectionRef"></a>: <b>non-normative</b></li> 
  <li><a href="#ldpr-impl" class="sectionRef"></a>: <b>non-normative</b></li> 
  <li><a href="#acks" class="sectionRef"></a>: <b>non-normative</b></li> 
  <li><a href="#history" class="sectionRef"></a>: <b>non-normative</b></li> 
  <li><a href="#normative-references" class="sectionRef"></a>: <b>normative</b></li>
  <li><a href="#informative-references" class="sectionRef"></a>: <b>non-normative</b></li>
</ul>

<p>A conforming <b><dfn>LDP Paging client</dfn></b> is a conforming LDP client [[!LDP]] that follows the rules defined by LDP Paging.
</p>

<p>A conforming <b><dfn>LDP Paging server</dfn></b> is a conforming LDP server [[!LDP]] that follows the rules defined by LDP Paging.</p>
</section>

<section class="informative" id="ldpp-ex-mx">
<h1>Example paging message exchanges</h1>

	<p>
		Example Co.'s customer
		relationship data is identified by the URI <code>http://example.org/customer-relations</code>,
		and is retrievable using the same URI.
	</p>

<section id="ldpp-ex-no-paging">
<h2>Traditional flow without paging</h2>

	<p>
		A standard HTTP client that knows nothing about LDP paging obtains a representation of the
		resource in the usual way.
	</p>

	<em>Request</em>
<pre class="example">GET /customer-relations HTTP/1.1
Host: example.org
Accept: text/turtle
</pre>

	<p>
		The server response is: 
	</p>

<em>Response:</em>
<pre class="example" id="ldpp-ex-no-paging-resp">
HTTP/1.1 200 OK
Content-Type: text/turtle
ETag: "_87e52ce291112"
Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel="type"
Allow: GET,OPTIONS,HEAD

@prefix rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
@prefix dcterms: &lt;http://purl.org/dc/terms/&gt;.
@prefix foaf: &lt;http://xmlns.com/foaf/0.1/&gt;.
@prefix ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
@prefix o: &lt;http://example.org/ontology/&gt;.
@base &lt;http://example.org/customer-relations&gt;.

&lt;&gt;
   a o:CustomerRelations;
   dcterms:title "The customer information for Example Co.";
   o:client &lt;#JohnZSmith&gt;, &lt;#BettyASmith&gt;, &lt;#JoanRSmith&gt;,
            &lt;#GlenWSmith&gt;, &lt;#AlfredESmith&gt;. 

&lt;#JohnZSmith&gt;
   a foaf:Person;
   o:status o:ActiveCustomer;
   foaf:name "John Z. Smith".
   
&lt;#BettyASmith&gt;
   a foaf:Person;
   o:status o:PreviousCustomer;
   foaf:name "Betty A. Smith".
 
 &lt;#JoanRSmith&gt;
   a foaf:Person;
   o:status o:PotentialCustomer;
   foaf:name "Joan R. Smith".
 
&lt;#GlenWSmith&gt;
   a foaf:Person;
   o:status o:ActiveCustomer, o:GoldCustomer;
   foaf:name "Glen W. Smith".

&lt;#AlfredESmith&gt;
   a foaf:Person;
   o:status o:ActiveCustomer, o:BronzeCustomer;
   foaf:name "Alfred E. Smith".
</pre>

	<p>
		As long as the resource being retrieved is small enough that the server can form its
		representation without running into implementation limits on memory etc., and as long
		as the client is likewise able to consume these representations, this pattern works
		fine.  Indeed, it's by far the most common pattern on the Web.
	</p>
	<p>
		At the point where server and/or client constraints or consumption preferences come into play, however, 
		something else is needed.  LDP Paging addresses this need by giving clients and 
		servers the ability to partition representations into smaller pieces, transfer
		as many as the client needs (potentially a small subset of the resource's full
		state), and allows the client to reassemble the pieces (or not) as it prefers.
		One sees this pattern in contexts such as search page results, as one common
		example.
	</p>

</section>

<section id="ldpp-ex-paging-303">
<h2>Simple paging flow using redirects</h2>

	<p>
		The simplest possible solution would be to redefine the meaning of the existing
		URI <code>http://example.org/customer-relations</code> from "all customer relations information"
		to "the first subset of all customer relations information".  This would require changes to
		any existing clients whose code was built using the original definition however, so it's 
		more likely that Example Co. would mint a new URI for "the first subset", define a way to 
		find subsequent subsets, and have clients use this new "first subset" URI approach.
	</p>
	<p>
		The "first subset" URI approach does not solve the problem of migrating existing clients from the old
		"all" to the new "first subset" semantic; neither would a <code>303 See Other</code> redirect
		from the old to the new URI, given the 
		<a href="http://www.w3.org/2001/tag/issues.html#httpRange-14">widespread historical client practice</a> of automatically
		following <code>303</code> redirects and treating the redirected-to resource as equivalent
		to the original, contrary to HTTP.  The safe route is to have clients explicitly tell the server that they
		are capable of handling the "first subset" semantic on the redirected-to URI; this is what
		LDP Paging does.
	</p>
	<p>
		A client aware of LDP paging obtains a representation of the
		resource in the usual way, and also signals its ability to handle redirection to a first-page resource:
	</p>

<em>Request</em>
<pre class="example">GET /customer-relations HTTP/1.1
Host: example.org
Accept: text/turtle
Prefer: return=representation; max-triple-count="500"
</pre>

	<p>
		The server's response contains a <code>303 See Other</code> status code and
		a <code>Location: http://example.org/customer-relations?page1</code> HTTP response header
		identifying the target resource, as shown below:
	</p>

<em>Response:</em>
<pre class="example" id="ldpp-ex-paging-303-resp1">
HTTP/1.1 303 See Other
Location: &lt;http://example.org/customer-relations?page1&gt;
</pre>

	<p>
		At this point the client does not know if the target
		resource is "all" or "the first subset"; it has to retrieve the resource to know.
	</p>

<em>Request</em>
<pre class="example">GET /customer-relations?page1 HTTP/1.1
Host: example.org
Accept: text/turtle
Prefer: return=representation; max-triple-count="500"
</pre>
	<p>
		The server's response is shown below:
	</p>

<em>Response:</em>
<pre class="example" id="ldpp-ex-paging-303-resp2">
HTTP/1.1 200 OK
Content-Type: text/turtle
ETag: "_87e52ce291112"
Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel="type",
      &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"
Link: &lt;http://example.org/customer-relations?p=2&gt;; rel="next"
Link: &lt;http://example.org/customer-relations&gt;; rel="canonical"; etag="customer-relations-v1"
Allow: GET,OPTIONS,HEAD

@prefix rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
@prefix dcterms: &lt;http://purl.org/dc/terms/&gt;.
@prefix foaf: &lt;http://xmlns.com/foaf/0.1/&gt;.
@prefix ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
@prefix o: &lt;http://example.org/ontology/&gt;.
@base &lt;http://example.org/customer-relations&gt;.

&lt;&gt;
   a o:CustomerRelations;
   dcterms:title "The customer information for Example Co.";
   o:client &lt;#JohnZSmith&gt;, &lt;#BettyASmith&gt;, &lt;#JoanRSmith&gt;. 

&lt;#JohnZSmith&gt;
   a foaf:Person;
   o:status o:ActiveCustomer;
   foaf:name "John Z. Smith".
&lt;#BettyASmith&gt;
   a foaf:Person;
   o:status o:PreviousCustomer;
   foaf:name "Betty A. Smith".
 &lt;#JoanRSmith&gt;
   a foaf:Person;
   o:status o:PotentialCustomer;
   foaf:name "Joan R. Smith".
</pre>

	<p>
		From this response, 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 specification, with the client's <code>max-triple-count</code> preference as one
		input; the simplest method is to make the server's page size equal
		to the client's preference.  In this example, the server chooses a smaller value so 
		there is a second page.
	</p>
	<ul>
	<li>
		The <code>Link: &lt;http://example.org/customer-relations&gt;; rel="canonical"</code>
		response header tells the client which resource <code>&lt;http://example.org/customer-relations?page1&gt;</code>
		is a page of.  The <code>etag="customer-relations-v1"</code> parameter value gives the client a way to know,
		during its page traversal, whether or not the canonical <a>paged resource</a> has changed; not all
		clients will use this information, but it is there for those that can make use of it.
	</li>
	<li>
		The <code>Link: &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"</code>
		response header tells the client that this is one <a>in-sequence page resource</a>, and therefore it
		needs to examine the other response headers to see if more data existed in the 
		canonical <a>paged resource</a> when the response
		was generated by the server.
	</li>
	<li>
		The <code>Link: &lt;http://example.org/customer-relations?p=2&gt;; rel="next"</code>
		response header tells the client that at least one more <a>in-sequence page resource</a> exists,
		and how to retrieve its representation.  The next page link's target URI is 
		defined by the server and is not constrained by this specification.
	</li>
	</ul>
	<p>
		The following example shows the message exchange for retrieving
		the next page:
	</p>

<em>Request</em>
<pre class="example">GET /customer-relations?p=2 HTTP/1.1
Host: example.org
Accept: text/turtle
Prefer: return=representation; max-triple-count="500"
</pre>
	<p>
		The server's response is shown below: 
	</p>

<em>Response:</em>
<pre class="example" id="ldpp-ex-paging-303-resp3">
HTTP/1.1 200 OK
Content-Type: text/turtle
ETag: "8_7e52ce291112"
Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel="type",
      &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"
Link: &lt;http://example.org/customer-relations&gt;; rel="canonical"; etag="customer-relations-v1"
Allow: GET,OPTIONS,HEAD

@prefix rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
@prefix dcterms: &lt;http://purl.org/dc/terms/&gt;.
@prefix foaf: &lt;http://xmlns.com/foaf/0.1/&gt;.
@prefix ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
@prefix o: &lt;http://example.org/ontology/&gt;.
@base &lt;http://example.org/customer-relations&gt;.

&lt;&gt;
   o:client &lt;#GlenWSmith&gt;, &lt;#AlfredESmith&gt;. 
 
&lt;#GlenWSmith&gt;
   a foaf:Person;
   o:status o:ActiveCustomer, o:GoldCustomer;
   foaf:name "Glen W. Smith".

&lt;#AlfredESmith&gt;
   a foaf:Person;
   o:status o:ActiveCustomer, o:BronzeCustomer;
   foaf:name "Alfred E. Smith".
 </pre>

	<p>
		In this example, there are only two customers provided in the
		second page.  
	</p>
		<!-- DONE: show it both ways; if a competing change hit the container, or not.
			 6.2.2.7's non-normative note covers this case.
		-->
	<ul>
	<li>
		The <code>Link: &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"</code>
		response header tells the client that this is one <a>in-sequence page resource</a>, and therefore it
		needs to examine the other response headers to see if more data existed in the 
		canonical <a>paged resource</a> when the response
		was generated by the server.
	</li>
	<li>
		The absence of a <code>Link: &lt;http://example.org/customer-relations?p=2&gt;; rel="next"</code>
		response header tells the client that no more <a>in-sequence page resource</a>s existed in this <a>paged resource</a>
		at the time the response was generated; repeating the request might result in a representation with links to more pages,
		if other processes are updating the customer relations data.
	</li>
	<li>
		Since the <code>etag="customer-relations-v1"</code> parameter value of the canonical <a>paged resource</a>
		did not change across the client's process of retrieving the entire <a>page sequence</a>, it is assured that 
		the merged response representations are equivalent to what it would have received had the server
		provided the entire representation of the <a>paged resource</a> in a single <code>200 OK</code> response.
		The client has <em>no assurance</em> that the current state of the <a>paged resource</a> remains unchanged
		since the final page's representation was generated.  For example, after the server constructs the final page representation, another
		actor could delete <code>client#BettyASmith</code> from the server.
	</li>
	</ul>

</section>

<section id="ldpp-ex-paging-other-links">
<h2>Optional paging links</h2>

	<p>
		The preceding paging examples in this section have all assumed that only <a>forward traversal</a>
		is supported by the server, to reduce complexity.
		A server might also support <a>backward traversal</a> through its pages, and/or direct access to the 
		<a title="first page link">first page</a> and/or <a title="last page link">last page</a> from any <a>in-sequence page resource</a>.
		Those options would be reflected by adding some combination of the links below, 
		or equivalent semantically equivalent syntactic variations of them, to the response messages.
	</p>

	<ul>
	<li>
		The <a title="first page link">first page</a>'s <a href="#ldpp-ex-paging-303-resp2">response message</a> might also have the following links:
<pre class="example">
Link: &lt;&gt;; rel="first"
Link: &lt;http://example.org/customer-relations?p=2&gt;; rel="last"
</pre>
	</li>
	<li>
		Any <a>in-sequence page resource</a>'s response message, including the <a title="first page link">first page</a> and the <a title="last page link">last page</a>,
		might also have the following links:
<pre class="example">
Link: &lt;http://example.org/customer-relations?page1&gt;; rel="first"
Link: &lt;http://example.org/customer-relations?p=2&gt;; rel="last"
</pre>
	</li>
	<li>
		The <a title="last page link">last page</a>'s <a href="#ldpp-ex-paging-303-resp3">response message</a> might also have the following links:
<pre class="example">
Link: &lt;http://example.org/customer-relations?page1&gt;; rel="first"
Link: &lt;http://example.org/customer-relations?page1&gt;; rel="prev"
Link: &lt;&gt;; rel="last"
</pre>
	</li>
	</ul>

</section>

</section> <!-- Example message exchanges -->

<section id="ldppclient">
<h1>Linked Data Platform Paging Clients</h1>
<p>All of the following are conformance rules for <a title="LDP Paging client">LDP Paging Clients</a>.
</p>
<section><h2>General requirements</h2>

	<section id="ldpp-client-advertise"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST
		<a href="#ldpp-hints">advertise their ability to support LDP Paging</a> on all retrieval requests that normally result in
		a response containing a representation.
	</h2>
	</section>
		
	<section id="ldpp-client-traversal"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST
		be capable of at least one of <a>forward traversal</a> and/or <a>backward traversal</a>.
	</h2>
	</section>
	
	<section id="ldpp-client-linkschg"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST NOT
		assume that any <a title="In-sequence page resource">in-sequence page resource's</a> <a title="paging link">paging links</a>
		will remain unchanged when the <a title="In-sequence page resource">in-sequence page resource</a>
		is retrieved more than once.  Such an assumption would 
		conflict with a server's ability to 
		<a href="#ldpr-pagingGET-sequences-change">add pages to a sequence</a> as the <a>paged resource</a> changes, for example.
	</h2>
	</section>
	
	<section id="ldpp-client-4xxok"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a> MUST NOT
		assume that any <a title="In-sequence page resource">in-sequence page resource's</a> <a title="paging link">paging links</a>
		will always be accessible.</h2>
		<blockquote><em>Non-normative note:</em> 
		Such an assumption would 
		conflict with a server's ability to <a href="#ldpr-pagingGET-sequences-change">remove pages from a sequence</a> 
		as the <a>paged resource</a> changes, for example.
		One consequence of this is that clients can receive responses with <code>4xx</code> status codes  
		when following page links, purely due to timing issues and without any error on the part of the client
		or the server.  Such a response would be unusual, and would likely signal an error, 
		if the response also indicates that the <a title="Paged resource">paged resource's</a> 
		<a href="#ldpr-notify-changes">state has <i>not</i> changed</a> 
		while the client was traversing its <a title="In-sequence page resource">pages</a>.
		Servers might also limit the lifetime of a particular <a>page sequence</a>, and client requests after the server has
		abandoned that sequence are likely to result in <code>410 Gone</code> or other <code>4xx</code> status codes.
		</blockquote>
	
	</section>
	
	<section id="ldpp-client-paging-incomplete"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a>  
		SHOULD NOT treat a page sequence as equivalent to the <a title="paged resource">paged resource</a> 
		when the <a href="#ldpr-notify-changes">paged resource changed</a> 
		<a href="#ldpr-guarantee-show-unchanged">during retrieval of the page sequence</a>.
	</h2></section>

	<section id="ldpp-client-nofollow-303"><h2 class="normal"><a title="LDP Paging client">LDP Paging clients</a>  
		MUST NOT treat the target of a <code>303 See Other</code> redirection as a replacement for the original resource.  
		That is, they cannot treat a <code>303</code> status code as if it was a 
		<code>307 Temporary Redirect</code> [[!RFC7231]] or <code>308 Permanent Redirect</code> [[!RFC7238]],
		as [[RFC7231]] makes clear.  This is critical to a client's ability to distinguish between the representation
		of a single <a>in-sequence page resource</a> and that of the <a>paged resource</a> when a <a>LDP Paging server</a>
		uses <a href="#ldpr-status-code">redirection</a> as a way to initiate paging.
	</h2></section>

</section>

<section id="ldpp-hints">
<h2>Client preferences</h2>
	<p>
		LDP Paging clients <a href="#ldpp-client-advertise">must provide paging-related hints</a> 
		in order to influence an LDP Paging server's choices.
	</p>

	<p>
		This specification introduces new 
		parameters on the HTTP <code>Prefer</code> request header's
		<code>return=representation</code> preference [[!RFC7240]], <a href="#ldpp-client-advertise">used by clients</a> to 
		supply a preference that helps the server form a response that is most appropriate to 
		the client's needs.  The presence of any parameter defined in this section serves several purposes:
		<ul>
		<li>It signals the client's support for LDP Paging to the request server</li>
		<li>It communicates the client's maximum desired size for a response representation</li>
		</ul>
	</p>

	<section id="ldpr-cli-paging"><h2 class="normal">
		<a title="LDP client">LDP clients</a> SHOULD 
		be capable of processing successful HTTP <code>GET</code> responses formed by a LDP server
		that independently initiated paging, returning a page of representation instead of full resource
		representation [[!LDP]].
	</h2>
	</section> 
	
	<p>
		LDP Paging defines <code>max-triple-count</code>, <code>max-member-count</code>, and <code>max-kbyte-count</code> 
		as new parameters on the existing 
		HTTP <code>Prefer</code> request header's
		<code>return=representation</code> preference [[!RFC7240]]; the presence of any of these parameters
		on the preference, not the preference alone, is what indicates to a server that the client
		supports LDP Paging.
		A client communicates its hint(s) to the server by adding the
		request header with a 
		<code>return=representation</code> preference that includes any of the following preference parameters
		<table class="indented">
		<tr>
		<td> <code>max-triple-count</code> </td>
		<td> The maximum decimal number of triples the client wishes to appear on each page.  </td>
		</tr>
		<tr>
		<td> <code>max-kbyte-count</code> </td>
		<td> The maximum decimal number of kilobytes (1024 byte units) the client wishes to receive as the page's representation.  </td>
		</tr>
		<tr>
		<td> <code>max-member-count</code> </td>
		<td> The maximum decimal number of members the client wishes to appear on each page.
				This parameter is only meaningful for paged <a title="Linked Data Platform Container">LDPCs</a>.
		</td>
		</tr>
		</table>
		<blockquote>
		<p>
		The generic preference BNF [[!RFC7240]] allows either a quoted string or a token as the value of a 
		preference parameter.
		</p>
		</blockquote>
	</p>

	<p id="prefer-examples-500-triples">
	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, as shown in <a href="#ldpp-ex-paging-303" class="sectionRef"></a>:
	<code>Prefer: return=representation; max-triple-count="500"</code>
	</p>

</section> <!-- Paging hints -->

</section> <!-- Client constraints -->

<section id="ldpr">
<h1>Linked Data Platform Resources</h1>

<section class="informative" id="ldpr-PagingIntro">

<h3>Paging considerations</h3>

	<p>
		As <a href="#intro">described</a> <a href="#ldpp-ex-mx">previously</a>,
		paging logically breaks up a <a>paged resource</a> 
		into a list of <a title="In-sequence page resource">in-sequence page resources</a> (pages) whose representations the client can retrieve, and serves each
		page with links to other <a title="In-sequence page resource">pages in the sequence</a>.
		Clients inspect each response to see if additional pages
		are available; paging does not affect the choice of HTTP status code.
		Clients generally have no insight into the allocation of information to pages, 
		although in <a href="#ldpc">some cases currently defined only for LDPCs</a> the server can expose its
		algorithm.
	</p>
	<p>
		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>in-sequence 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 <a href="#ldpr-guarantee-show-unchanged">guarantee</a>, 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>in-sequence page resource</a>.
	</p>
	<p>
		LDP Paging defines a mechanism by which <a href="#ldpr-notify-changes">clients can detect that the paged resource has been changed</a> so that they can, for example,
		abandon a page traversal as early as possible.
		This provides a stronger guarantee in certain cases
		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>in-sequence 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.
		A detailed example was provided in <a href="#ldpp-ex-mx" class="sectionRef"></a>.
		See <a href="#ldpr-impl" class="sectionRef"></a> for server implementation considerations.
	</p>
</section>

<section id="ldpr-PagingGET">
<h3>HTTP GET</h3>
	<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>.
	</p>
		
	<section id="ldpr-page-large"><h2 class="normal">
		<!-- 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 -->
	
	<section id="ldpr-split-any-resource"><h2 class="normal">
		<a title="LDP Paging server">LDP Paging servers</a> MAY 
		treat any resource (LDP-RS or not) as a <a>paged resource</a>.
	</h2></section><!-- Was 4.2.15 / #ldpr-4_2_15 -->

	<section id="ldpr-split-any-time"><h2 class="normal">
		<a title="LDP Paging server">LDP Paging servers</a> MAY 
		vary their treatment of any resource (LDP-RS or not) as a <a>paged resource</a> over time.
		In other words, given two attempts to retrieve the same resource at different points
		in time, the server can choose to return a representation of the first page at one time and 
		of the entire resource at a different time.  Clients distinguish between these cases based
		on the <a href="#ldpr-status-code">status code</a> 
		and <a href="#ldpr-pagingGET-page-type-reqd">response headers</a>.
	</h2></section>

	<section id="ldpp-prefer"><h2 class="normal"><a title="LDP Paging server">LDP Paging servers</a>
		SHOULD respect all of a client's <a href="#ldpp-hints">LDP Paging defined hints</a>, for example 
		<a href="#ldpp-hints">the largest page size</a>
		the client is interested in processing,
		to influence the amount of data returned in representations.</h2> 
	<blockquote>
		<em>Non-normative note</em>: LDP server implementers should be careful not to interpret a 
		<code>Prefer return=representation</code> request header that <em>lacks</em> any
		parameters defined here as a client's request for a <a>paged resource</a>.
		<a href="#ldpp-hints">A client's hints</a> indicate LDP Paging support <em>only</em>
		when at least one of the preference parameters defined by this specification is present.
	</blockquote>
	<blockquote>
		<em>Non-normative note</em>: LDP server implementers should carefully consider the effects of these
		preferences on caching, as described in section 2 of [[!RFC7240]].
	</blockquote>
	<blockquote>
		<em>Non-normative note</em>: [[!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.
	</blockquote>
	</section>

	<section id="ldpp-prefer-unrecognized"><h2 class="normal">
		<a title="LDP Paging server">LDP Paging servers</a> MAY 
		ignore a <a href="#ldpp-hints">page size hints</a> whose value is zero, 
		and process the request as if no maximum desired size was specified; in the latter case the server
		can select whatever page size it deems appropriate, or choose not to page the resource at all.
	</h2></section>
			
	<section id="ldpr-status-code"><h2 class="normal">
			<a title="LDP Paging server">LDP Paging servers</a> SHOULD NOT
			initiate paging unless the client has indicated it understands LDP Paging.
			<a title="LDP Paging server">LDP Paging servers</a> initiating paging SHOULD respond
			to successful <code>GET</code> requests with any <a title="Paged resource">paged resource</a> 
			as the <code>Request-URI</code> in one of the following ways:</h2>
			<ul>
			<li>
				If the client supports paging, respond with 
				status code <code>303 See Other</code> and a <code>Location</code> response header that identifies
				the first <a>in-sequence page resource</a>.
				The only standard means defined by LDP paging for a client to signal a server that the client
				understands paging is via the <a href="#ldpp-hints">client preference</a> defined for this purpose;
				other implementation-specific means could also be used.
			</li>
			<li>
				If the server is willing to provide a non-paged representation, respond
				with an appropriate status code (likely <code>200 OK</code>) and the potentially large
				non-paged representation.
			</li>
			<li>
				Either reject the request, most likely with a <code>4xx</code> status code,
				or (keeping in mind the note below)
				initiate paging as described above with a <code>303</code> status code, or
				choose another status code appropriate to the specific situation.
			</li>
			</ul>
			
			<blockquote>
				<em>Non-normative note:</em>
				<a title="LDP Paging server">LDP Paging servers</a> could choose to make any resource
				available <em>only</em> as a paged resource.  
				In so doing, when interacting with clients <em>unaware</em> of LDP Paging, 
				if the server initiates paging anyway then it runs the risk
				that an ill-behaved client will automatically follow a 
				<code>303 See Other</code> redirect and believe via the subsequent
				<code>200 OK</code> that it has obtained a complete representation of the <a>paged resource</a>
				rather than of a single <a>in-sequence page resource</a>.
				<a title="LDP Paging client">LDP Paging clients</a> <a href="#ldpp-client-nofollow-303">will not follow redirects in this way</a>,
				but some existing HTTP clients are known to treat <code>303 See Other</code> redirects as if they were 
				equivalent to the original request-URI, despite this being explicitly disclaimed in [[RFC7231]].
			</blockquote>
	</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>in-sequence 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><em>Non-normative note:</em> 
		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><em>Non-normative note:</em> 
		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">Feedback requested on the link relation type used below</p>
		<p>Background: 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
		by 
		including a HTTP <code>Link</code> header on all successful
		HTTP <code>GET</code> responses, and SHOULD include the same header on all <code>4xx</code>
		status code responses.
		The link's
		context URI identifies the <a>in-sequence page resource</a> being retrieved, 
		target URI identifies the <a>paged resource</a>,
		link relation type is <code>canonical</code> [[!REL-CANONICAL]],
		and 
		link extension parameters include the parameter name <code>etag</code>
		and a corresponding parameter value identical to the ETag [[!RFC7232]]
		of the <a>paged resource</a>.
		For example: <code>Link: &lt;http://example.org/customer-relations&gt;; rel="canonical"; etag="customer-relations-v1"</code>
		</h2>
		<blockquote><em>Non-normative note:</em> 
		If the <code>rel="canonical"; etag="..."</code> value changes as the client retrieves pages, 
		for example the value accompanying the first page's representation is <code>rel="canonical"; etag="v1"</code> 
		and the value accompanying the second page's representation is <code>rel="canonical"; etag="v2"</code>,
		the client can detect that the <a>paged resource</a>'s state has changed.
		Some clients will ignore such changes, but others may choose to react to them, for example by restarting the traversal.
		</blockquote>
	</section>

	<section id="ldpr-pagingGET-sequences-change"><h2 class="normal">
		<a title="LDP Paging server">LDP Paging servers</a> MAY
		add or remove <a title="in-sequence page resource">in-sequence page resources</a> to a 
		<a title="Paged resource">paged resource's</a> sequence over time.
		If the <a>page sequence</a> is <a href="#ldpc-HTTP_GET">ordered</a>, then the ordering communicated by the server MUST be maintained;
		the server SHOULD only add pages to the end of an unordered sequence.
		</h2><!-- Was 4.10.2.1 / #ldpr-pagingGET-sequences-change -->
		<blockquote><em>Non-normative note:</em> 
		Servers might abandon an ordered <a>page sequence</a>, resulting in <code>4xx</code> status codes to subsequent requests,
		although it will be less disruptive to clients if the server either adds content to the appropriate existing page or
		adds new pages at the proper point in the sequence.  Clients have no more efficient means than a conditional retrieval
		request on existing pages to detect the changed/added pages.
		</blockquote>
		<blockquote><em>Non-normative note:</em> 
		As a result, clients retrieving any <a>in-sequence 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 again later.  
		Similar situations arise when the <a>page sequence</a> 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.
		A nominally middle page <var>M</var> can become the last (or a non-existent) page if a competing request deletes
		part of the <a title="Paged resource">paged resource's</a> content after the client retrieves <var>M</var>.
		</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="in-sequence page resource">in-sequence 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="in-sequence page resource">in-sequence 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="in-sequence page resource">in-sequence 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="in-sequence page resource">in-sequence page resource</a> 
			as the <code>Request-URI</code>.
			This is the mechanism by which clients can discover the end of the <a>page sequence</a>
			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="in-sequence page resource">in-sequence 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="in-sequence page resource">in-sequence page resource</a> 
			as the <code>Request-URI</code>.
			This is one mechanism by which clients can discover the beginning of the <a>page sequence</a>
			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="in-sequence page resource">in-sequence 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 id="ldpr-pagingGET-abandon-pageseq"><h2 class="normal">
			<a title="LDP Paging server">LDP Paging servers</a> SHOULD
			indicate that they have abandoned a
			sequence by responding with at <code>410 Gone</code> to HTTP requests to any of the 
			<a title="in-sequence page resource">in-sequence page resources</a> with appropriate 
			paging link response headers, for example, rel="first".
		</h2></section><!-- #ldpr-pagingGET-abandon-pageseq -->

		<section id="ldpr-units-triple-count"><h2 class="normal">
			<a title="LDP Paging server">LDP Paging servers</a> SHOULD
			support the <code>max-triple-count</code> <a href="#ldpp-hints">client preference parameter</a>,
			which expresses a page size limiting the number of RDF triples represented on a page.
			For example, <code>max-triple-count="500"</code> expresses a limit of 500 RDF triples per page.
		</h2>
		</section> 

		<section id="ldpr-units-kbyte-count"><h2 class="normal">
			<a title="LDP Paging server">LDP Paging servers</a> SHOULD
			support the <code>max-kbyte-count</code> <a href="#ldpp-hints">client preference parameter</a>,
			which expresses a page size limit as kilobytes of representation size.
			For example, <code>max-kbyte-count="1"</code> expresses a limit of 1024 bytes per page.
		</h2>
		</section> 
	
		<section id="ldpr-pagesize-multiple-units"><h2 class="normal">
			<a title="LDP Paging server">LDP Paging servers</a> MUST, if provided with multiple 
			 <a href="#ldpp-hints">client preference parameters</a> limiting page size,
			honor all hints that it recognizes.  This has the net effect that the most restrictive
			hint for any given response governs the resulting page size.
			For example, <code>max-kbyte-count="1"</code> and <code>max-triple-count="500"</code>
			usually would result in pages whose size hits the 1 kilobyte limit first, since each triple very likely
			requires more than two bytes (500 triples/1024 bytes).
		</h2>
		</section> 
	
		<!-- combined into ldpr-status-code
		<section id="ldpr-pagingGET-only-paging-clients"><h2 class="normal">
			<a title="LDP Paging server">LDP Paging servers</a> SHOULD NOT
			initiate paging unless the client has indicated it understands LDP Paging or that it is prepared to 
			process <code>2NN Contents of Related</code> responses [[!2NN]].
			If the client supports paging but not <code>2NN</code> responses, a server initiating paging SHOULD respond with 
			status code <code>303 See Other</code> and a <code>Location</code> response header that identifies
			the URI of the first <a>in-sequence page resource</a> of the <a>paged resource</a>.
			The only standard means defined by LDP paging for a client to signal a server that the client
			understands paging is via the <a href="#ldpp-hints">client preference</a> defined for this purpose;
			other implementation-specific means could also be used.</h2>
			<blockquote>
				<em>Non-normative note:</em>
				<a title="LDP Paging server">LDP Paging servers</a> could choose to make any resource
				available <em>only</em> as a paged resource.  
				In so doing, when interacting with clients <em>unaware</em> of LDP Paging, 
				if the server initiates paging anyway then it runs the risk
				that an ill-behaved client will automatically follow a 
				<code>303 See Other</code> redirect and believe via the subsequent
				<code>200 OK</code> that it has obtained a complete representation of the <a>paged resource</a>
				rather than of what may be a single <a>in-sequence page resource</a>.
				The alternative is for the server to reject the request, most likely
				with a <code>4xx</code> status code.
				<a title="LDP Paging client">LDP Paging clients</a> <a href="#ldpp-client-nofollow-303">will not follow redirects in this way</a>,
				but some existing HTTP clients are known to treat <code>303 See Other</code> redirects as if they were 
				equivalent to the original request-URI, despite this being explicitly disclaimed in [[RFC7231]].
			</blockquote>
		</section>
		-->

</section>

</section> <!-- h1 -->

<section id="ldpc">
<h1>Linked Data Platform Containers</h1>

<section id="ldpc-general">
<h2>Requirements when paging LDP Containers</h2>

	<section id="ldpc-onsamepage"><h2 class="normal">
		<a title="LDP Paging server">LDP Paging servers</a> MUST
		ensure that the <a title="membership triples">membership triple</a> and 
		<a title="containment triples">containment triple</a> for each member are part of the
		same <a>in-sequence page resource</a>, whenever both triples are present in the <a>page sequence</a>
		for a <a title="paged resource">paged LDPC</a>.
	</h2></section>
	
	<section id="ldpr-units-record-count"><h2 class="normal">
		<a title="LDP Paging server">LDP Paging servers</a> SHOULD
		support the <code>max-member-count</code> <a href="#ldpp-hints">client preference parameter</a>,
		which expresses a page size limiting the number of members returned on each page of a <a title="paged resource">paged LDPC</a>.
		For example, <code>max-member-count="10"</code> expresses a limit of 10 members per page.
	</h2>
	</section> 
	
</section>

<section class="informative" id="ldpc-informative">		
<h2>Ordering of container members across pages</h2>

	<section id="ldpc-ordering"><h2 class="normal">Ordering</h2>
	<p>
		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
		available property of the members. In the example below, the value of
		the <code>o:marketValue</code> predicate is present for each
		member, so the client can easily order the members according to the
		value of that property.  Applications that require a way for clients to
		specify the order, can do so with application-specific extensions. 
	</p>
	<p>
		Order becomes more important when containers are
		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> ensures that all the
		members on any single page have the proper sort order with relation to all 
		members on any next and previous pages.
		<em>This says nothing about the ordering of members <strong>within</strong> any 
		<a title="In-sequence page resource">single page</a>.</em>
		When the sort is ascending, all the members on a current page have a 
		sort order no lower than all members on the previous page and 
		sort order no higher than all the members on the next page; 
		that is, it proceeds from low to high, but keep in mind that several 
		consecutive pages might have members whose sort criteria are equal. 
		When the sort is descending, the opposite order is used. 
		Since more than one value may be used to sort members, 
		the LDPC specification allows servers to assert the ordered list
		of sort criteria used to sort the members, using the 
		<code>ldp:pageSequence</code> HTTP link relation and its
		<code>ldp:pageSortCriteria</code> predicate.
		Each member of the ordered list exposes one <code>ldp:pageSortCriterion</code>, 
		consisting of a <code>ldp:pageSortOrder</code>, 
		<code>ldp:pageSortPredicate</code>, and 
		optionally a <code>ldp:pageSortCollation</code>.
	</p>
	<p>
		Here is an example asset container described in [[LDP]] section 5.1:
	</p>

<em>Request</em>
<pre class="example">GET /netWorth/nw1/assetContainer/ HTTP/1.1
Host: example.org
Accept: text/turtle
Prefer: return=representation; max-triple-count="500"
</pre>
	<p>
		The server might respond with status code <code>200 OK</code>, 
		and the following representation:
	</p>

<em>Response:</em>
<pre class="example" id="ldpc-ex-ordering-nopaging">
HTTP/1.1 200 OK
Content-Type: text/turtle
ETag: "_87e52ff291112"
Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel="type"
Link: &lt;http://www.w3.org/ns/ldp#DirectContainer&gt;; rel="type"
Allow: GET,OPTIONS,HEAD

# The following is the ordered representation of
#   http://example.org/netWorth/nw1/assetContainer/
<!-- @base is here only so it's easier to paste into validators for checking -->
# @base &lt;http://example.org/netWorth/nw1/assetContainer/&gt; .
@prefix dcterms: &lt;http://purl.org/dc/terms/&gt;.
@prefix ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
@prefix o: &lt;http://example.org/ontology/&gt;.

&lt;&gt;
   a ldp:DirectContainer;
   dcterms:title "The assets of JohnZSmith";
   ldp:membershipResource &lt;http://example.org/netWorth/nw1&gt;;
   ldp:hasMemberRelation o:asset;
   ldp:insertedContentRelation ldp:MemberSubject;
   ldp:contains &lt;a1&gt;, &lt;a2&gt;, &lt;a3&gt;.

&lt;http://example.org/netWorth/nw1&gt;
   a o:NetWorth;
   o:asset &lt;a1&gt;, &lt;a3&gt;, &lt;a2&gt;.

&lt;a1&gt;
   a o:Stock;
   o:marketValue 100.00 .
&lt;a2&gt;
   a o:Cash;
   o:marketValue 505.00 .
&lt;a3&gt;
   a o:RealEstateHolding;
   o:marketValue 100.00 .
</pre>
	<p>
		The client knows that LDP Paging was not used to form the response, because the HTTP status code is <code>200 OK</code>;
		the absence of a <code>Link: &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"</code> response header provides redundant
		confirmation of this.
		Since paging was not used, the server provides no information related to page sorting;
		providing page sorting information would have no value to the client, it would only waste resources.
	</p>

	<p>
		Had the server responded instead with a redirect to a first page <code>http://example.org/netWorth/nw1/assetContainer/?p=1</code>,
		whose representation was (after following the redirect):
	</p>

<em>Response:</em>
<pre class="example" id="ldpc-ex-ordering-page1">
HTTP/1.1 200 OK
Content-Type: text/turtle
ETag: "_87e52ff291112"
Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel="type",
      &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"
Link: &lt;http://example.org/netWorth/nw1/assetContainer/?p=2&gt;; rel="next"
Link: &lt;http://example.org/netWorth/nw1/assetContainer/&gt;; rel="canonical"; etag="v1"
Link: &lt;http://example.org/netWorth/nw1/assetContainer/sortedSequence/&gt;; rel="http://www.w3.org/ns/ldp#pageSequence"
Allow: GET,OPTIONS,HEAD

# The following is the ordered representation of
#   http://example.org/netWorth/nw1/assetContainer/ page 1 of 2
<!-- @base is required here because the page URI != container URI; any use for paste into validators for checking is free bonus -->
@base &lt;http://example.org/netWorth/nw1/assetContainer/&gt; .
@prefix dcterms: &lt;http://purl.org/dc/terms/&gt;.
@prefix ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
@prefix o: &lt;http://example.org/ontology/&gt;.

&lt;&gt;
   a ldp:DirectContainer;
   dcterms:title "The assets of JohnZSmith";
   ldp:membershipResource &lt;http://example.org/netWorth/nw1&gt;;
   ldp:hasMemberRelation o:asset;
   ldp:insertedContentRelation ldp:MemberSubject;
   ldp:contains &lt;a1&gt;, &lt;a2&gt;, &lt;a3&gt;.

&lt;http://example.org/netWorth/nw1&gt;
   a o:NetWorth;
   o:asset &lt;a1&gt;, &lt;a3&gt;, &lt;a2&gt;.

&lt;a1&gt;
   a o:Stock;
   o:marketValue 100.00 .
   
# The remainder of the content describes the sort order.
# Note that the new base URI here matches the target URI of the pageSequence Link header above.

@base &lt;http://example.org/netWorth/nw1/assetContainer/sortedSequence/&gt; .
@prefix rdf: &lt;http://www.w3.org/1999/02/22-rdf-syntax-ns#&gt;.
<!-- (#Sort-o.marketValue-Ascending) does not work, because the subject uri would be a blank node -->
&lt;&gt; ldp:pageSortCriteria  ( &lt;#Sort-o.marketValue-Ascending&gt; ).

&lt;#Sort-o.marketValue-Ascending&gt;
   a ldp:pageSortCriterion;
   ldp:pageSortOrder ldp:Ascending;
   ldp:pageSortPredicate o:marketValue.
</pre>
	
	<p>
		In this case the server does provide information on the assignment of members to pages.
	</p>
	<ul>
	<li>
		A <code>Link: rel="http://www.w3.org/ns/ldp#pageSequence"</code> response header has been
		added, allowing the client to where to find information about the page sequence;
		its content includes a <code>ldp:pageSortCriteria</code> triple, 
		allowing the client to know what sort criteria the server used when allocating members
		to pages.
	</li>
	<li>
		The server also chose to include assertions about the sort criteria in the content for the
		first page, namely the triples occurring after the second <code>@base</code> directive.
		This is an optional exemplary optimization, and the client must decide for itself using means outside of
		LDP and HTTP whether or not to trust those assertions.
		If the client trusts those assertions, it need not retrieve them; retrieving them would in this case
		result in another <code>HTTP GET</code> request.  For the purposes of this example, assume that
		the assertions match what the client would obtain by retrieving them itself.
	</li>
	<li>
		The contents of the sort criteria resource
		asserts that the <code>o:marketValue</code> predicate will be used 
		to assign sets of members to pages in ascending order.  
		The server is telling the client that the values of <code>o:marketValue</code> of all assets
		on the first page are no lower than the values on subsequent pages.
		Since only one such value happens to fall on the first page, this is trivially satisfied.
	</li>
	</ul>
	
	<p>
		When the client retrieves the second page by following the <code>rel="next"</code> link,
		its representation might be:
	</p>

<em>Response:</em>
<pre class="example" id="ldpc-ex-ordering-page2">
HTTP/1.1 200 OK
Content-Type: text/turtle
ETag: "_87e52ff291112"
Link: &lt;http://www.w3.org/ns/ldp#Resource&gt;; rel="type",
      &lt;http://www.w3.org/ns/ldp#Page&gt;; rel="type"
Link: &lt;http://example.org/netWorth/nw1/assetContainer/?pageSortOrder&gt;; rel="prev"
Link: &lt;http://example.org/netWorth/nw1/assetContainer/&gt;; rel="canonical"; etag="v1"
Link: &lt;http://example.org/netWorth/nw1/assetContainer/sortedSequence/&gt;; rel="http://www.w3.org/ns/ldp#pageSequence"
Allow: GET,OPTIONS,HEAD

# The following is the ordered representation of
#   http://example.org/netWorth/nw1/assetContainer/ page 2 of 2
<!-- @base is required here because the page URI != container URI; any use for paste into validators for checking is free bonus -->
@base &lt;http://example.org/netWorth/nw1/assetContainer/&gt; .
@prefix dcterms: &lt;http://purl.org/dc/terms/&gt;.
@prefix ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
@prefix o: &lt;http://example.org/ontology/&gt;.

&lt;a2&gt;
   a o:Cash;
   o:marketValue 505.00 .
&lt;a3&gt;
   a o:RealEstateHolding;
   o:marketValue 100.00 .
</pre>
	
	<ul>
	<li>
		The same <code>Link: rel="http://www.w3.org/ns/ldp#pageSequence"</code> response header is present,
		allowing the client to know what page sequence, and hence what sort criteria, the server used.
	</li>
	<li>
		The server chose not to include assertions about the sort criteria in the content for the
		second page.  Since LDP Paging <a href="#ldpc-sort-consistent">requires that the page sequence is sorted consistently</a>,
		any client that already retrieved the first page has already seen the sorting criteria.  If a client is given
		the URI of an <a>in-sequence page resource</a> through means other than following links, it always has the option 
		to retrieve the sort criteria.
	</li>
	<li>
		As the example shows, the values of <code>o:marketValue</code> all assets
		on the second page are greater than or equal to the values on earlier pages.
		<em>The values within this page are not ordered according to the 
		sort criterion</em>, illustrating that this criterion applies only to the 
		sorting of "assigning members to pages", not
		to the ordering within any single page's representation.
		Typically those representations have not guarantee of ordering and are generated by libraries,
		whose serializers do not provide a way to control how the order is conveyed.
	</li>
	</ul>
	<p>
		It is up to the domain model
		and server to determine the appropriate predicate to indicate the
		resource’s order within a page (or globally), and up to the client receiving this 
		representation to use that order in whatever way is appropriate to meet its needs, for 
		example to sort the data prior to presentation on a user interface. Also,
		as it is possible for a container to have as its members other containers,
		the ordering approach doesn't change as containers themselves are LDPRs and the
		properties from the domain model can be leveraged for the sort criteria.
	</p>
	</section><!-- Was 5.1.2 / #ldpc-ordering -->
</section> <!-- containers . intro -->

<section id="ldpc-HTTP_GET">	
<h2>HTTP GET requirements for member ordering across pages</h2>

	<p>
		If a <a>LDP Paging server</a> chooses to use LDP Paging-defined mechanisms to 
		tell clients the order it uses to assign LDPC members to pages, 
		which is optional, then it does so as described in this section.
		LDP Paging does not specify ordering for <a title="in-sequence page resource">pages</a> in other cases.
		See <a href="#ldpc-ordering" class="sectionRef"></a> for
		exemplary message exchanges.
	</p>
	
	<section id="ldpc-sort-criteria-consistent"><h2 class="normal">
		<a title="LDP Paging server">LDP Paging servers</a> MAY 
		communicate the order used to allocate LDPC members to <a title="in-sequence page resource">pages</a>.
		If they choose to communicate the order, they MUST respond 
		consistently to retrieval requests for each <a title="in-sequence page resource">page</a> in the same sequence.
		That is, they must communicate the same criteria (or absence of it) for all pages in the same sequence; if
		the criteria were allowed to vary, the ordering among members of a container
		across <a title="in-sequence page resource">pages</a> would be undefined.
	</h2></section><!-- Was 5.3.2 / #ldpc-5_3_2 -->
	
	<blockquote>
		<em>Non-normative note:</em> A server can offer different sequences for the same <a>paged resource</a>,
		for example, sequences that have differing sort criteria, and they can be offered serially or concurrently.
	</blockquote>
	
	<section id="ldpc-sort-criteria-link"><h2 class="normal">
		<a title="LDP Paging server">LDP Paging servers</a> <a href="#ldpc-sort-criteria-consistent">communicating order</a> MUST 
		specify the order using a <code>HTTP Link</code> header
		whose context URI is the page URI, 
		whose link relation is <code>http://www.w3.org/ns/ldp#pageSequence</code>, 
		and whose target IRI identifies a LDP-RS whose content includes the 
		sort criteria.
		The resource identified by the <code>Link</code> header's target IRI MUST contain a triple
		whose subject is the <code>Link</code> header's target IRI, 
		whose predicate is <code>ldp:pageSortCriteria</code> 
		and whose object is a
		page sort criteria resource compliant with this section's requirements on its content.
	</h2></section><!-- Was 5.3.2 / #ldpc-5_3_2 -->
	
	<section id="ldpc-sort-criteria-content"><h2 class="normal">
		<a title="LDP Paging server">LDP Paging servers</a> <a href="#ldpc-sort-criteria-consistent">communicating order</a> MUST 
		expose page sort criteria resources that describe the allocation of members to pages; each resource consists of a <code>rdf:List</code> of
		<code>ldp:pageSortCriterion</code> resources.  
		The first list entry provides the primary
		sorting criterion, any second entry provides a secondary criterion used to order members considered
		equal according to the primary criterion, and so on.
		The resulting page sort order MUST be as defined by SPARQL <code>SELECT</code>’s <code>ORDER BY</code> clause 
		[[!sparql11-query]].
	</h2></section><!-- Was 5.3.2 / #ldpc-5_3_2 -->
	
	<section id="ldpc-sortliteraltype"><h2 class="normal">
		<a title="LDP Paging server">LDP Paging servers</a> <a href="#ldpc-sort-criteria-consistent">communicating order</a> MUST 
		expose page sort criteria resources that contain, 
		in every <code>ldp:pageSortCriterion</code> list entry, 
		a triple
		whose subject is the sort criterion identifier, 
		whose predicate is <code>ldp:pageSortPredicate</code> 
		and whose object is 
		the predicate whose value is used to order members between pages (the <dfn>page-ordering values</dfn>).
		The only literal data types whose behavior LDP constrains are those defined
		by SPARQL <code>SELECT</code>’s <code>ORDER BY</code> clause [[!sparql11-query]].  Other data types
		can be used, but LDP
		assigns no meaning to them and interoperability will be limited.
	</h2></section><!-- Was 5.3.3 / #ldpc-5_3_3 -->
	
	<section id="ldpc-sortorder"><h2 class="normal">
		<a title="LDP Paging server">LDP Paging servers</a> <a href="#ldpc-sort-criteria-consistent">communicating order</a> MUST 
		expose page sort criteria resources that contain, 
		in every <code>ldp:pageSortCriterion</code> list entry, 
		a triple
		whose subject is the sort criterion identifier, 
		whose predicate is <code>ldp:pageSortOrder</code> 
		and whose object describes the order used.</h2>
		<blockquote>
		<p>
		LDP defines two values,
		<code>ldp:Ascending</code> and <code>ldp:Descending</code>, for use
		as the object of this triple.  Other values can be used, but LDP
		assigns no meaning to them and interoperability will be limited.
		</p>
		</blockquote>
	</section><!-- Was 5.3.4 / #ldpc-5_3_4 -->
	
	<section id="ldpc-sortcollation"><h2 class="normal">
		<a title="LDP Paging server">LDP Paging servers</a> <a href="#ldpc-sort-criteria-consistent">communicating order</a> MAY 
		expose page sort criteria resources that contain, 
		in any <code>ldp:pageSortCriterion</code> list entry,
		a triple
		whose subject is the sort criterion identifier, 
		whose predicate is <code>ldp:pageSortCollation</code> 
		and whose object identifies the collation used.
		The <code>ldp:pageSortCollation</code> triple MUST be omitted for comparisons
		involving <a title="page-ordering values">page-ordering values</a> for which [[!sparql11-query]] does not use collations.</h2>
		<blockquote>
		<p>
		LDP defines no values for use
		as the object of this triple.  While it is better for interoperability to use
		open standardized values, any value can be used.
		</p>
		<p>
		When the <code>ldp:pageSortCollation</code> triple is absent and the 
		<a title="page-ordering values">page-ordering values</a> are strings or simple literals [[!sparql11-query]], the
		resulting order is as defined by SPARQL <code>SELECT</code>’s <code>ORDER BY</code> clause 
		[[!sparql11-query]] using two-argument <code>fn:compare</code>, that is, 
		it behaves as if <code>http://www.w3.org/2005/xpath-functions/collation/codepoint</code> 
		was the specified collation.
		</p>
		<p>
		When the <code>ldp:pageSortCollation</code> triple is present and the 
		<a title="page-ordering values">page-ordering values</a> are strings or simple literals 
		[[!sparql11-query]], the
		resulting order is as defined by SPARQL <code>SELECT</code>’s <code>ORDER BY</code> clause 
		[[!sparql11-query]] using three-argument <code>fn:compare</code>, that is, the 
		specified collation.
		</p>
		</blockquote>
	</section><!-- Was 5.3.5 / #ldpc-5_3_5 -->

</section> <!-- h2 -->

</section> <!-- h1 LDPC -->

<section class='informative' id='security'>
<h1>Security Considerations</h1>
As with any protocol that is implemented leveraging HTTP, implementations should take advantage of the many 
security-related facilities associated with it and are not required to carry out LDP operations 
that may be in contradistinction to a particular security policy in place. For example, when faced with an 
unauthenticated request to replace system critical RDF statements in a graph through the PUT method, applications may
consider responding with the 401 status code (Unauthorized), indicating that the appropriate authorization 
is required. In cases where authentication is provided fails to meet the requirements of a particular access control 
policy, the 403 status code (Forbidden) can be sent back to the client to indicate this failure to meet the
access control policy.
</section>

<section class="appendix informative" id="ldpr-impl">

<h2>Paging LDPRs without maintaining server-side session state</h2>
	<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 <a href="#ldpp-ex-mx" class="sectionRef">preceding examples</a>, 
		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>.  This is likely true in general practice.
		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>in-sequence 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: &lt;http://example.org/customer-relations?resumeafter=JoanRSmith&gt;; 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: &lt;http://example.org/customer-relations?resumebefore=GlenWSmith&gt;; 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 within the constraints of all normative references is permissible.
	</p>
</section>


<section class='appendix informative' id="acks">
<h2>Acknowledgements</h2>
     
  <p>The following people have been instrumental in providing thoughts, feedback,
reviews, content, criticism and input in the creation of this specification:</p>

  <p style="margin-left: 3em;">
  Alexandre Bertails, Andrei Sambra, Andy Seaborne, Antonis Loizou,  Arnaud Le Hors, Ashok Malhotra, Bart van Leeuwen, Cody Burleson, David Wood, Eric Prud'hommeaux, Erik Wilde, Gregory McFall, Henry Story, John Arwe, Kevin Page, Kingsley Idehen, Mark Baker, Martin P. Nally, Miel Vander Sande, Miguel Esteban Gutiérrez, Nandana Mihindukulasooriya, Olivier Berger, Pierre-Antoine Champin, Raúl García Castro, Reza B'Far, Richard Cyganiak, Roger Menday, Ruben Verborgh, Sandro Hawke, Serena Villata, Sergio Fernandez, Steve Battle, Steve Speicher, Ted Thibodeau, Tim Berners-Lee, Yves Lafon
  </p>

</section>

<section class='appendix informative' id="history">
<h1>Change History</h1>
<!-- 
<p>The change history is up to the editors to insert a brief summary of
changes, ordered by most recent changes first and with heading from which
public draft it has been changed from.
</p>  -->

<em>Summary</em>
<ul>
	<li>Sections previously marked "at risk" are no longer marked (the content remains in this document)
		<a href="#ldpr-cli-paging">client should be prepared for pages</a>, hint units (<a href="#ldpr-units-kbyte-count">max-kbytes-count</a>
		and 
		<a href="#ldpr-units-record-count">max-member-count</a>) and <a href="#ldpr-pagesize-multiple-units">honor all size hints</a>.
		</li>
	<li>Removed "Feature at Risk" content for <code>2NN Contents of Related</code> status code and usage.</li>
</ul>
<!-- 
<em>Summary</em>
<ul>
	<li>Split paging out from core LDP 1.0 specification into this document</li>
	<li>Updated detection of paged resources based on link relations</li>
	<li>Added rule to keep containment and membership triples for same resource on same page</li>
	<li>Use of link header to location sort criteria</li>
	<li>Added additional ways to request paging based kilobyte and membership count</li>
</ul>
 -->
 
<!-- <p>The change history is up to the editors to insert a brief summary of
changes, ordered by most recent changes first and with heading from which
public draft it has been changed from.
</p>  -->

<!-- 
<h2>Detailed history</h2> -->

<!-- <blockquote><em><a href="http://www.w3.org/TR/2014/CR-ldp-paging-20141216/">Candidate Recommendation Draft</a></em></blockquote> wah -->
<!-- 
<ul>
	<li>2015-01-26 - Align usage of Link: rel= to not use single quotes per RFC5988 (SS)</li>
</ul>
-->

<!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-paging-20140930/">Candidate Recommendation Draft</a></em></blockquote> wah -->
<!-- 
<ul>
	<li>2014-11-05 - Removed "at risk" content for "2NN Contents of Related" status code and usage (SS) </li>
	<li>2014-11-05 - Removed "at risk" markers for max-member-count and max-kbyte-count, honor all hints and clients should expect paging (SS) </li>
	<li>2014-10-10 - Clarified "new protocol" in 4.2, hyper-linked max-member-count to LDPCs per 10/10 public comments email (JA) </li>
	<li>2014-09-26 - Added non-norm items about extensions to supply client requested ordering (SS) </li>
</ul>

<blockquote><em><a href="http://www.w3.org/TR/2014/WD-ldp-paging-20140909/">Last Call Draft - 9 September 2014</a></em></blockquote>
<ul>
	<li>2014-08-25 - max-triple-count, max-member-count, max-kbyte-count support must > should per Aug 25 mtg (JA) </li>
	<li>2014-08-25 - Clarify example (JA) </li>
	<li>2014-08-22 - AT RISK the three limits, first reached per Aug 18 mtg (JA) </li>
	<li>2014-08-21 - max-triple-count, max-member-count, max-kbyte-count with parms being integers per Aug 18 mtg (JA) </li>
	<li>2014-08-05 - Re-cast sort criteria as rdf:List compatible with syntactic sugar for those (JA) </li>
	<li>2014-08-05 - Fuss SOTD for Arnaud (JA) </li>
	<li>2014-08-04 - Fuss with SortValueAscending value for Sandro (JA) </li>
	<li>2014-08-04 - Incorporating resolutions from today's WG meeting (JA) </li>
	<li>2014-07-30 - Rewording based on SS's 7/17 email comments (JA) </li>
	<li>2014-07-29 - Fully specify 303+location's URI (JA) </li>
	<li>2014-07-29 - Fuss with SortValueAscending value for Sandro (JA) </li>
	<li>2014-07-29 - Update 6.2.9 to resolve the "add only at the end"/sorted container conflict (JA) </li>
	<li>2014-07-29 - Remove chunked transfer encoding, which readers were conflating with paging (chunking) (JA) </li>
	<li>2014-07-29 - Finish Turtle updates for change to Link header to locate sort criteria (JA) </li>
	<li>2014-07-28 - Updates based on Sandro's email, excluding those on public comments list (JA) </li>
	<li>2014-07-28 - Updates to address public review comment on must-not initiate paging (JA) </li>
	<li>2014-07-28 - Updates to address public review comment on Prefer (JA) </li>
	<li>2014-07-17 - Fixed minor spelling/grammar and validation problems (SS)</li>
	<li>2014-07-15 - Final updates hopefully before LC2 draft issued (JA) </li>
	<li>2014-07-09 - Fix Ashok's emailed comments (JA) </li>
	<li>2014-07-09 - Clean up clients chapter, references, non/normative section listing in conformance, kitchen sink (JA) </li>
	<li>2014-07-09 - Move paging example into "intro" chapter 4 (JA) </li>
	<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>
	<li>2014-05-22 - Spec membership &amp; containment triples on same page (JA) </li>
	<li>2014-05-22 - Spec syntax for page size hint; still need to wrap more text and examples around it (JA) </li>
	<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>
</ul>
<blockquote><em><a href="https://dvcs.w3.org/hg/ldpwg/raw-file/94420c5678ae/ldp.html">February 18, 2014 Editor's Draft</a></em></blockquote>
 -->
</section>
    
  </body>
</html>