Add Prefer header examples, define new URIs from -126 in ttl, tweak acks per Arnaud
authorJohn Arwe
Sat, 08 Feb 2014 13:11:14 -0500
changeset 473 1557b3c92200
parent 472 00f0d6677c0c
child 474 a074b88f9b68
Add Prefer header examples, define new URIs from -126 in ttl, tweak acks per Arnaud
ldp.html
ldp.ttl
--- a/ldp.html	Sat Feb 08 02:19:12 2014 +0000
+++ b/ldp.html	Sat Feb 08 13:11:14 2014 -0500
@@ -1457,7 +1457,8 @@
 	</p>
 	<p>Here is an example container described
 		previously, with representation for ordering of the assets:</p>
-<pre class="example" id="ldpc-ex-ordering"># The following is the ordered representation of
+<pre class="example" id="ldpc-ex-ordering">
+# 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;
@@ -1494,7 +1495,8 @@
    o:value 50.00 .
 &lt;a3&gt;
    a o:RealEstateHolding;
-   o:value 300000 .</pre>
+   o:value 300000 .
+</pre>
 		<p>
 			As you can see by the addition of the <code>ldp:ContainerSortCriteria</code> 
 			predicate, the <code>o:value</code> predicate is used
@@ -2225,6 +2227,9 @@
 <section id="prefer-parameters">
 <h2>Preferences on the Prefer Request Header</h2>
 
+<section id="prefer-summary">
+<h3>Summary</h3>
+
 	<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.  
@@ -2247,7 +2252,19 @@
 	Non-normative note: LDP server implementers should carefully consider the effects of these
 	preferences on caching, as described in section 2 of [[!Prefer]].
 	</p>
-   
+
+	<p>
+	Non-normative note: [[!Prefer]] recommends that server implementers include a 
+	Preference-Applied response header when the client cannot otherwise determine the server's
+	behavior with respect to honoring hints from the response content.
+	<a href="#prefer-examples">Examples</a> illustrates some cases where the header is unnecessary.
+	</p>
+
+</section> <!-- Prefer summary -->
+
+<section id="prefer-rules">
+<h3>Specification</h3>
+
 	<section id="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.
@@ -2257,15 +2274,15 @@
 		<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.
+		Where <code>WSP</code> is whitespace [[!RFC5234]], and
+		<code>ldp-uri-list</code> is a double-quoted 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
+		where <code>DQUOTE</code> is a double quote [[!RFC5234]], and <code>URI</code> is an absolute URI with an optional
 		fragment component [[!RFC3986]].
 		</p>
 		</blockquote>
@@ -2300,8 +2317,9 @@
 		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.
+		<!-- TODO: use css instead - be careful of the other tables -->
 		<table style="margin-left: +3em">
-		<tr>
+		<tr style="background:#F2F2F2">
 		<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>
@@ -2309,7 +2327,7 @@
 		<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>
+		<tr style="background:#F2F2F2">
 		<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
@@ -2321,7 +2339,7 @@
 		<blockquote>
 		<p>
 		Non-normative note: all currently defined URIs are only coherent for LDP-RRs, 
-		and in fact LDPCs, however in
+		and in fact only for LDPCs, however in
 		the future it is possible that additional URIs with other scopes of applicability
 		could be defined.
 		</p>
@@ -2330,7 +2348,106 @@
 		</h2>
 	</section>
 
-</section>
+</section> <!-- Prefer specification -->
+<section id="prefer-examples" class="informative">
+<h3>Examples</h3>
+<!-- TODO: flesh out examples 
+		Ted's email http://lists.w3.org/Archives/Public/public-ldp-wg/2014Jan/0136.html had:
+		none, c only, m only, m+c, all
+		separate ex's for basic, in/direct, include, exclude?
+		ex for complete absence of hint?
+-->
+	<p>
+	If we assume a <a title="Linked Data Platform Direct Container">LDP Direct Container</a> like
+	the one below:
+	</p>
+	<pre class="example" id="prefer-examples-direct">
+	# The following is the 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:Container, ldp:DirectContainer;
+	   dcterms:title "The assets of JohnZSmith";
+	   ldp:containerResource &lt;http://example.org/netWorth/nw1&gt;;
+	   ldp:containsRelation o:asset;
+	   ldp:insertedContentRelation ldp:MemberSubject.
+
+	&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:value 100.00 .
+	&lt;a2&gt;
+	   a o:Cash;
+	   o:value 50.00 .
+	&lt;a3&gt;
+	   a o:RealEstateHolding;
+	   o:value 300000 .
+	</pre>
+
+	<p id="prefer-examples-direct-non-member-only">
+	A server that honors a 
+	<code>Prefer: return=representation; omit="http://www.w3.org/ns/ldp#PreferMembership http://www.w3.org/ns/ldp#PreferContainment"</code> hint would return the following in response to a <code>GET</code> request.
+	Clients interested only in information about the container 
+	(for example, which membership predicate it uses) might use such a hint.
+	</p>
+	
+	<pre class="example">
+	# 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:Container, ldp:DirectContainer;
+	   dcterms:title "The assets of JohnZSmith";
+	   ldp:containerResource &lt;http://example.org/netWorth/nw1&gt;;
+	   ldp:containsRelation o:asset;
+	   ldp:insertedContentRelation ldp:MemberSubject.
+	</pre>
+
+	<p id="prefer-examples-direct-membershiponly">
+	A server that honors a 
+	<code>Prefer: return=representation; include="http://www.w3.org/ns/ldp#PreferMembership http://www.w3.org/ns/ldp#PreferUnmanaged"</code> hint would return (at least) the following in response to a <code>GET</code> request, and perhaps only this (it might
+	well omit containment triples if they are not specifically requested).  
+	Clients interested only in information about the container 
+	(for example, which membership predicate it uses) and its membership might use such a hint.
+	</p>
+	
+	<pre class="example">
+	# 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:Container, ldp:DirectContainer;
+	   dcterms:title "The assets of JohnZSmith";
+	   ldp:containerResource &lt;http://example.org/netWorth/nw1&gt;;
+	   ldp:containsRelation o:asset;
+	   ldp:insertedContentRelation ldp:MemberSubject.
+
+	&lt;http://example.org/netWorth/nw1&gt;
+	   a o:NetWorth;
+	   o:asset &lt;a1&gt;, &lt;a3&gt;, &lt;a2&gt;.
+	</pre>
+
+	</section> <!-- Prefer examples -->
+
+</section> <!-- Prefer defns -->
 </section> <!-- Header defns -->
     
 <!-- Removed for action-113
@@ -2427,12 +2544,9 @@
   <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;">Tim Berners-Lee, Steve Battle, 
-  Olivier Berger, Alexandre Bertails, Reza B'Far, Cody Burleson, Richard Cyganiak, Raúl García Castro, 
-  Miguel Esteban Gutiérrez,
-  Sandro Hawke, Kingsley Idehen, Yves Lafon, Arnaud Le Hors, Antonis Loizou, Ashok Malhota, Roger Menday,
-  Nandana Mihindukulasooriya, Kevin Page, Eric Prud'hommeaux, Andy Seaborne, Steve Speicher,
-  Henry Story, Ted Thibodeau, Bart van Leeuwen, Miel Vander Sande, Ruben Verborgh, Serena Villata, Erik Wilde, David Wood, Martin P. Nally</p>
+  <p style="margin-left: 3em;">
+  Alexandre Bertails, Andrei Sambra, Andy Seaborne, Antonis Loizou,  Arnaud Le Hors, Ashok Malhota, Bart van Leeuwen, Cody Burleson, David Wood, Eric Prud'hommeaux, Erik Wilde, 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>
 
@@ -2446,6 +2560,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-08 - Add Prefer header examples, define new URIs from -126 in ttl, tweak acks per Arnaud email (JA)</li>
 	<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>
--- a/ldp.ttl	Sat Feb 08 02:19:12 2014 +0000
+++ b/ldp.ttl	Sat Feb 08 13:11:14 2014 -0500
@@ -210,8 +210,30 @@
 	
 
 :MemberSubject
-	a rdf:Description;
+	a rdf:Description;		# individual
 	rdfs:comment "Used to indicate default and typical behavior for ldp:insertedContentRelation, where the member-URI value in the membership triple added when a creation request is successful is the URI assigned to the newly created resource.";
 	vs:term_status "unstable";
 	rdfs:isDefinedBy :;
 	rdfs:label "MemberSubject".
+
+:PreferContainment
+ 	a rdf:Description;		# individual
+	rdfs:comment "URI identifying a LDPC's containment triples, for example to allow clients to express interest in receiving them.";
+	vs:term_status "unstable";
+	rdfs:isDefinedBy :;
+	rdfs:label "PreferContainment".
+
+:PreferMembership
+ 	a rdf:Description;		# individual
+	rdfs:comment "URI identifying a LDPC's membership triples, for example to allow clients to express interest in receiving them.";
+	vs:term_status "unstable";
+	rdfs:isDefinedBy :;
+	rdfs:label "PreferMembership".
+
+:PreferUnmanaged
+ 	a rdf:Description;		# individual
+	rdfs:comment "URI identifying a subset of a LDPC's triples that excludes triples managed by the LDPC, for example to allow clients to express interest in receiving them.  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.";
+	vs:term_status "unstable";
+	rdfs:isDefinedBy :;
+	rdfs:label "PreferUnmanaged".
+	
\ No newline at end of file