Fix respec messages that only show up on remote server, hit paging examples to remove appearance of inlining
authorJohn Arwe
Tue, 12 Nov 2013 13:20:44 -0500
changeset 413 55af75032d16
parent 412 b5f309858d98
child 414 a5d0c19a9474
Fix respec messages that only show up on remote server, hit paging examples to remove appearance of inlining
ldp.html
--- a/ldp.html	Mon Nov 11 16:33:38 2013 -0500
+++ b/ldp.html	Tue Nov 12 13:20:44 2013 -0500
@@ -344,7 +344,7 @@
 	LDP allows paging of resources other than LDPRs, but does not specify how clients combine
 	their representations.  See <a href="#ldpr-Paging" class="sectionRef"></a> for additional details.  For readers
 	familiar with paged feeds [[!RFC5005]], a paged resource is similar to a logical feed.
-	Any non-paged resource could be considered to be a paged resource consisting of exactly one page, 
+	Any resource could be considered to be a paged resource consisting of exactly one page, 
 	although there is no known advantage in doing so.
 	<p></p></dd>
 	
@@ -355,12 +355,13 @@
 	For readers
 	familiar with paged feeds [[!RFC5005]], a single-page resource is similar to a feed document and the same
 	coherency/completeness considerations apply.
+	<a href="#ldpr-pagingGET-sequences-change">LDP provides no guarantees that the sequence is stable</a>.
 	</p><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="Single-page resource"><em>individual page resources</em></a>, 
 	in cases where both are mentioned in
-	close proximity.  Both are resources in both the HTTP and RDF senses.
+	close proximity.  
 	<p></p></dd>
 	
 	<dt><dfn>first page link</dfn></dt>
@@ -538,8 +539,8 @@
 		<li>Are there some typical vocabularies that should be reused?</li>
 	</ul>
 	<p>The following sections define the conformance rules for LDP servers when serving LDPRs.
-		This document also explains <a href="#ldpr-Paging">how to paginate an LDPR's representation</a> if it gets too big.
-		Companion documents describe additional guidelines for use when interacting with LDPRs. 
+		This document also explains <a href="#ldpr-Paging">how a server paginates an LDPR's representation</a> if it gets too big.
+		Companion informative documents describe additional guidelines for use when interacting with LDPRs. 
 	</p>
 
 </section>
@@ -848,7 +849,7 @@
 	<p>It sometimes happens that a
 		resource is too large to reasonably transmit its representation in a
 		single HTTP response.  
-		To address this problem, resources should support a technique called Paging.  
+		To address this problem, servers should support a technique called Paging.  
 		When a client retrieves such a resource, the server includes in its response
 		a link to the next part of the resource's state, at a URL of the server's choosing.
 		The triples in the representation of the each page of an LDPR
@@ -857,8 +858,9 @@
 	<p><a title="LDP server">LDP servers</a> may respond to requests for a
 		resource by returning the first page of the resource
 		with a <code>Link &lt;next-page-URL&gt;;type='next'</code> header containing the URL for the next page.
-		Clients inspect each response to see if additional pages
-		are available.  Note that paging is lossy, as described in [[RFC5005]], and so (as stated there)
+		Clients inspect each response for the link header to see if additional pages
+		are available; paging does not affect the choice of HTTP status code.
+		Note that paging is lossy, as described in [[RFC5005]], and so (as stated there)
 		clients should not make any assumptions about a set of pages being a complete or 
 		coherent snapshot of a resource's state.</p>
 	<p>
@@ -866,13 +868,13 @@
 		relationship data, identified by the URI <code>http://example.org/customer-relations</code>,
 		we’ll split the response across two pages.  
 		The client 
-		retrieves the first page of <code>http://example.org/customer-relations</code>, and
-		the server responds with the following representation:
+		retrieves <code>http://example.org/customer-relations</code>, and
+		the server responds with status code 200 (OK) and the following representation:
 	</p>
 
 <pre class="example"># The following is the representation of
 #    http://example.org/customer-relations
-#    Requests on the ?firstPage URI will result in responses that include the following HTTP header
+#    Requests on the URI will result in responses that include the following HTTP header
 #       Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='next'
 #    This Link header is how clients discover the URI of the next page in sequence,
 #    and that the resource supports paging.
@@ -881,33 +883,37 @@
 @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;http://example.org/customer-relations&gt;
+&lt;&gt;
    a o:CustomerRelations;
    dcterms:title "The customer information for Example Co.";
-   o:client &lt;client#JohnZSmith&gt;, &lt;client#BettyASmith&gt;, &lt;client#JoanRSmith&gt;. 
+   o:client &lt;#JohnZSmith&gt;, &lt;#BettyASmith&gt;, &lt;#JoanRSmith&gt;. 
 
-&lt;client#JohnZSmith&gt;
+&lt;#JohnZSmith&gt;
    a foaf:Person;
    o:status o:ActiveCustomer;
    foaf:name "John Z. Smith".
-&lt;client#BettyASmith&gt;
+&lt;#BettyASmith&gt;
    a foaf:Person;
    o:status o:PreviousCustomer;
    foaf:name "Betty A. Smith".
- &lt;client#JoanRSmith&gt;
+ &lt;#JoanRSmith&gt;
    a foaf:Person;
    o:status o:PotentialCustomer;
    foaf:name "Joan R. Smith".</pre>
 
 	<p>
+		Because the server includes a <code>Link: &lt;http://example.org/customer-relations?p=2&gt;; rel='next'</code>
+		response header, the client knows that more data exists and where to find it.
 		The server determines the size of the pages using application specific methods not defined
 		within this specificiation. The next page link's target URI is also
 		defined by the server and not this specification.
 	</p>
 	<p>
-		The following example is the result of retrieving the representation
-		for the next page:
+		The following example is the result of retrieving
+		the next page; 
+		the server responds with status code 200 (OK) and the following representation:
 	</p>
 
 <pre class="example"># The following is the representation of
@@ -920,19 +926,21 @@
 @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;http://example.org/customer-relations&gt;
-   o:client &lt;client#GlenWSmith&gt;, &lt;client#AlfredESmith&gt;. 
+&lt;&gt;
+   o:client &lt;#GlenWSmith&gt;, &lt;#AlfredESmith&gt;. 
  
-&lt;client#GlenWSmith&gt;
+&lt;#GlenWSmith&gt;
    a foaf:Person;
    o:status o:ActiveCustomer, o:GoldCustomer;
    foaf:name "Glen W. Smith".
 
-&lt;client#AlfredESmith&gt;
+&lt;#AlfredESmith&gt;
    a foaf:Person;
    o:status o:ActiveCustomer, o:BronzeCustomer;
-   foaf:name "Alfred E. Smith".</pre>
+   foaf:name "Alfred E. Smith".
+ </pre>
 	<p>
 		In this example, there are only two customers provided in the
 		final page.  To indicate this is the last page, the server omits the <code>Link rel='next'</code> 
@@ -954,7 +962,19 @@
 		and their associated <a title="Single-page resource">single-page resources</a>.
 	</p>
 
-	<div id="ldpr-pagingGET-first-reqd-onbase" class="rule">4.10.2.1 removed
+	<div id="ldpr-pagingGET-sequences-change" class="rule">4.10.2.1 <a title="LDP server">LDP servers</a> MAY
+		add <a title="Single-page resource">single-page resources</a> to a 
+		<a title="Paged resource">paged resource's</a> sequence over time,
+		but SHOULD only add pages to the end of a sequence.
+		</div><div class="rule">
+		<blockquote>Informative note: 
+		As a result, clients retrieving any <a>single-page resource</a> several times can observe its place in the sequence
+		change as the state of the <a title="Paged resource">paged resource</a> changes.
+		For example, a nominally last page's server might provide a
+		<a>next page link</a> when the page is retrieved.  Similar situations arise when the page sequence crosses server boundaries; 
+		server A might host the initial portion of a sequence that links to the last page server A is aware of,  
+		hosted on server B, and server B might extend the sequence of pages.
+		</blockquote>
 	</div>
 	<!-- Removed - action-113
 	<div id="ldpr-pagingGET-first-reqd-onbase" class="rule">4.10.2.1 <a title="LDP server">LDP servers</a> MAY
@@ -973,7 +993,7 @@
 	<div id="ldpr-pagingGET-first-allowed-onpages" class="rule">4.10.2.1.1 
 		<a title="LDP server">LDP servers</a> MAY provide 
 		a <a>first page link</a> when responding to 
-		requests with any <a>single-page resource</a> as the <code>Request-URI</code>.
+		requests with any <a title="Single-page resource">single-page resource</a> as the <code>Request-URI</code>.
 	</div>
 	<div id="ldpr-pagingGET-last-allowed-onbase" class="rule">4.10.2.1.2 removed
 	</div>
@@ -1007,9 +1027,7 @@
 		in responses to <code>GET</code> requests with the final <a title="Single-page resource">single-page resource</a> 
 		as the <code>Request-URI</code>.
 		This is the mechanism by which clients can discover the end of the page sequence
-		as currently known by the server.  The server is permitted to append pages over time,
-		so clients retrieving a final page several times can observe a "formerly last" page
-		having a <a>next page link</a> added.
+		as currently known by the server.  
 	</div>
 	<div id="ldpr-pagingGET-prev-allowed" class="rule">4.10.2.2.2 <a title="LDP server">LDP servers</a> MAY
 		provide a <a>previous page link</a>
@@ -1021,7 +1039,8 @@
 		provide a <a>previous page link</a>
 		in responses to <code>GET</code> requests with the <em>first</em> <a title="Single-page resource">single-page resource</a> 
 		as the <code>Request-URI</code>.
-		This is one mechanism by which clients can discover the beginning of the page sequence.
+		This is one mechanism by which clients can discover the beginning of the page sequence
+		as currently known by the server.  
 	</div>
 	<div id="ldpr-pagingGET-collection-reqd" class="rule">4.10.2.2.4 removed
 	</div>
@@ -1883,7 +1902,7 @@
 	<div class="atrisk"><p class="atrisktext">Feature At Risk</p>
 		<p>The LDP Working Group proposes incorporation of the features described in this section.</p>
 		<ul>
-		<li>The addition of <a>Accept-Post</a> in this specification is pending 
+		<li>The addition of <code>Accept-Post</code> in this specification is pending 
 		advancement of an <a href="https://datatracker.ietf.org/doc/draft-wilde-accept-post/">IETF draft</a>
 		that would fully include it, based on the Accept-Patch header's design from [[!RFC5789]].  Once LDP is in
 		Candidate Recommendation, the LDP WG will make an assessment based on the status at IETF
@@ -1940,6 +1959,7 @@
 </section>
 </section> <!-- Header defns -->
     
+<!-- Removed for action-113
 <section>
 <h1>HTTP Status Code Definitions</h1>
      
@@ -2186,6 +2206,7 @@
 
 <!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130930/">Candidate Recommendation Draft</a></em></blockquote> wah -->
 <ul>
+    <li>2013-11-12 - Fix respec messages that only show up on remote server, hit paging examples to remove appearance of inlining (JA)</li>
     <li>2013-11-11 - Resolve ACTION-113 Update spec to reflect 11/04 resolution to remove 303 and have client use first/next links to detect paging (JA)</li>
     <li>2013-10-25 - Resolve ACTION-105 Update spec to reflect 9/30 resolution moving Paging links to HTTP headers (JA)</li>
     <li>2013-10-25 - Resolve ACTION-110 Update spec to reflect 10/21 resolution for normative changes to align vanilla/chocolate (JA)</li>