ACTION-126: Add Prefer header, adjusted for TallTed's results
authorJohn Arwe
Fri, 07 Feb 2014 19:23:17 -0500
changeset 470 eb040e50a66f
parent 469 6970791bad8e
child 471 5aabdca8ea7b
ACTION-126: Add Prefer header, adjusted for TallTed's results
ldp.html
--- a/ldp.html	Fri Feb 07 13:25:51 2014 -0500
+++ b/ldp.html	Fri Feb 07 19:23:17 2014 -0500
@@ -490,6 +490,7 @@
 <p>All of the following are conformance rules for <a title="LDP server">LDP Clients</a>.
 </p>
 <section><h2>General</h2>
+
 	<section id="ldp-cli-multitype"><h2 class="normal">In the absence of special knowledge of the application or domain, 
 		<a title="LDP client">LDP clients</a> MUST assume that any LDP-RR can have multiple values for <code>rdf:type</code>.
 	</h2></section> <!-- Was 4.3.5 / #ldpr-4_3_5 -->
@@ -514,6 +515,20 @@
 		<code>PATCH</code> instead of HTTP <code>PUT</code> for update avoids this burden for clients
 		[[RFC5789]].
 	</h2></section> <!-- Was 4.5.5 / #ldpr-ldpr-4_5_5 -->
+	
+	<section id="ldpr-cli-can-hint"><h2 class="normal">
+		<a title="LDP client">LDP clients</a> MAY 
+		provide LDP-defined hints that allow servers to optimize the content of responses.
+		<a href="#prefer-parameters" class="sectionRef"></a> defines hints that apply to 
+		<a title="Linked Data Platform RDF Resource">LDP-RRs</a>.
+	</h2></section> 
+	
+	<section id="ldpr-cli-hints-ignorable"><h2 class="normal">
+		<a title="LDP client">LDP clients</a> MUST 
+		be capable of processing responses formed by an LDP server that ignores hints,
+		including LDP-defined hints.
+	</h2></section> 
+	
 </section>
 </section> <!-- Client constraints -->
 
@@ -1643,6 +1658,20 @@
 		equally to LDPCs.
 	</h2></section><!-- Was 5.2.11 / #ldpc-5_2_11 -->
 	
+	<section id="ldpc-prefer"><h2 class="normal"><a title="LDP server">LDP servers</a>
+		SHOULD respect all of a client's LDP-defined hints, for example 
+		<a href="#prefer-parameters">which subsets of LDP-defined state</a>
+		the client is interested in processing,
+		to influence the set of triples returned in representations of an LDPC, 
+		particularly for large LDPCs.  
+		Non-normative note: the LDPC might be paged; <a title="Paged resource">paged resources</a> provide 
+		no guarantee that all triples of a given subset, for example 
+		<a title="Containment triples">containment triples</a>, 
+		are grouped together on one page or on a sequence of consecutive 
+		<a title="Single-page resource">pages</a>
+		(see <a href="#ldpr-Paging" class="sectionRef"></a>).
+	</h2></section>
+	
 </section>
 
 <section id="ldpc-HTTP_GET">	
@@ -2191,6 +2220,120 @@
 	</section><!-- Was 6.1.3 / #header-accept-post-iana -->
 
 </section>
+     
+<section id="prefer-parameters">
+<h2>Preferences on the Prefer Request Header</h2>
+
+	<div class="ldp-issue-pending">
+	<div class="ldp-issue-title">Need to update normative reference once RFC number is assigned.</div>
+	The <a href="http://tools.ietf.org/html/draft-snell-http-prefer-18">HTTP Prefer header</a> is queued for an RFC number behind HTTPbis, whose BNF Prefer normatively refers to.  
+	</div>
+	
+	<p>This specification introduces new parameters on the HTTP <code>Prefer</code> request header's
+	<code>return=representation</code> preference [[!Prefer]], used optionally by clients to 
+	supply a hint to help the server form a response that is most appropriate to 
+	the client's needs.  The LDP-defined parameters suggest the portion(s) of a resource's state that the 
+	client application is interested in, and if received is likely to be 
+	processed.  LDP Containers with large numbers of associated documents 
+	and/or members will have large representations, and many client 
+	applications may be interested in processing only a subset of the LDPC's 
+	information (for example, only membership triples or only containment triples), 
+	resulting in a potentially large savings in server, client, 
+	and network processing.  
+	</p>
+	
+	<p>
+	Non-normative note: LDP server implementers should carefully consider the effects of these
+	preferences on caching, as described in section 2 of [[!Prefer]].
+	</p>
+   
+	<section id="prefer-include"><h2 class="normal">
+		The <code>include</code> hint defines a subset of an LDPR's content that a client
+		would like included in a representation.
+		The syntax for the <code>include</code> parameter of the 
+		HTTP <code>Prefer</code> request header's
+		<code>return=representation</code> preference [[!Prefer]] is:</h2>
+		<blockquote>
+		<code>include-parameter = "include" *WSP "=" *WSP ldp-uri-list</code>
+		<p>
+		Where <code>WSP</code> is whitespace [[!RFC4234]], and
+		<code>ldp-uri-list</code> is a blank-delimited unordered set of URIs whose ABNF is given below.
+		The generic preference BNF [[!Prefer]] allows either a quoted string or a token as the value of a 
+		preference parameter; LDP assigns a meaning to the value only when it is a quoted string of
+		the form:
+		</p>
+		<code>ldp-uri-list = DQUOTE *WSP URI *[ 1*WSP URI ] *WSP DQUOTE</code>
+		<p>
+		where DQUOTE is a double quote [[!RFC4234]], and URI is an absolute URI with an optional
+		fragment component [[!RFC3986]].
+		</p>
+		</blockquote>
+		</h2>
+	</section>
+
+	<section id="prefer-omit"><h2 class="normal">
+		The <code>omit</code> hint defines a subset of an LDPR's content that a client
+		would like omitted from a representation.
+		The syntax for the <code>omit</code> parameter of the 
+		HTTP <code>Prefer</code> request header's
+		<code>return=representation</code> preference [[!Prefer]] is:</h2>
+		<blockquote>
+		<code>omit-parameter = "omit" *WSP "=" *WSP ldp-uri-list</code>
+		<p>
+		Where <code>WSP</code> is whitespace [[!RFC4234]], and
+		<code>ldp-uri-list</code> is re-uses the definition from <a href="#">include</a>.
+		The generic preference BNF [[!Prefer]] allows either a quoted string or a token as the value of a 
+		preference parameter; LDP assigns a meaning to the value only when it is a quoted string of
+		the form in the ABNF.
+		</p>
+		</blockquote>
+		</h2>
+	</section>
+
+	<section id="prefer-conflicts"><h2 class="normal">
+		When LDP servers receive a request with conflicting hints, this specification imposes
+		no requirements on their behavior.  They are free to reject the request, process it
+		applying some subset of the hints, or anything else appropriate to the server.
+		[[!Prefer]] suggests treating similar requests as though none of the conflicting
+		preferences were specified.
+		</h2>
+	</section>
+
+	<section id="prefer-uris"><h2 class="normal">
+		This specification defines the following URIs for clients to use with <code>include</code>
+		and <code>omit</code> parameters.  It assigns no meaning to other URIs, although
+		other specifications MAY do so.
+		<table style="margin-left: +3em">
+		<tr>
+		<td style="padding:0 0 0 +2ex"> Containment triples </td>
+		<td style="padding:0 0 0 +2ex; white-space:nowrap"> <code>http://www.w3.org/ns/ldp#PreferContainment</code> </td>
+		</tr>
+		<tr>
+		<td style="padding:0 0 0 +2ex"> Membership triples </td>
+		<td style="padding:0 0 0 +2ex; white-space:nowrap"> <code>http://www.w3.org/ns/ldp#PreferMembership</code> </td>
+		</tr>
+		<tr>
+		<td style="padding:0 0 0 +2ex"> All triples other than triples managed by an LDPC.
+		Currently an LDPC manages only containment and membership triples, but in the future others
+		might be added.  This definition is written to automatically exclude those new classes of
+		triples, as long as they are the responsibility of the LDPC to manage.
+		</td>
+		<td style="padding:0 0 0 +2ex; white-space:nowrap"> <code>http://www.w3.org/ns/ldp#PreferUnmanaged</code> </td>
+		</tr>
+		</table>
+		<blockquote>
+		<p>
+		Non-normative note: all currently defined URIs are only coherent for LDP-RRs, 
+		and in fact LDPCs, however in
+		the future it is possible that additional URIs with other scopes of applicability
+		could be defined.
+		</p>
+		</blockquote>
+		
+		</h2>
+	</section>
+
+</section>
 </section> <!-- Header defns -->
     
 <!-- Removed for action-113
@@ -2306,6 +2449,7 @@
 <!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130930/">Candidate Recommendation Draft</a></em></blockquote> wah -->
 <!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130730/">Last Call Draft</a></em></blockquote> -->
 <ul>
+	<li>2014-02-07 - ACTION-126: Add Prefer header (JA)</li>
 	<li>2014-02-07 - LDP-BCs use ldp:contains not ldp:member (JA)</li>
 	<li>2014-02-07 - Simplified some of the container examples (SS)</li>
 	<li>2014-02-06 - partial first pass at arnaud's email comments (JA)</li>