ldp.html
changeset 175 bcc13fba2593
parent 174 72ce83f4ec7f
child 176 60b0a09af2c4
--- a/ldp.html	Tue Jul 09 13:29:24 2013 -0400
+++ b/ldp.html	Tue Jul 09 18:13:39 2013 -0400
@@ -236,6 +236,23 @@
 	In other words, the union of the non-member resource's state and the LDPC's membership triples
 	exactly equals the LDPC's state.
 	<p></p></dd>
+	
+	<dt><dfn>Resource inlining</dfn></dt>
+	<dd>
+		The practice of responding to a HTTP <code>GET</code> request made to a <code>request-URI</code> R0 with
+		a representation that includes the state of R0, the <em>entire</em> state of resources accessed through
+		<em>other</em> <code>request-URI</code>(s) R1...Rn, and assertions from the server identifying the resources whose
+		entire state has been provided.
+		R1...Rn identify the inlined resource(s).
+		See <a href="#ldpr-inlining" class="sectionRef"></a> for details.
+	<p></p></dd>
+	
+	<dt><dfn>Member inlining</dfn></dt>
+	<dd>A special case of <a title="Resource inlining">resource inlining</a>, where all members of a container on a given
+		page are inlined.  The response page may or may not include all of the container's members.
+		See <a href="#ldpc-inlining" class="sectionRef"></a> for details.
+	<p></p></dd>
+	
   </dl>
 
 <section>
@@ -355,6 +372,7 @@
 		object of the triple representing the link (relationship) is enough and
 		does not require the creation of an intermediate link resource to
 		describe the relationship.
+	</div>
 		
 	<div class="ldp-issue-closed">
 	<div class="ldp-issue-title"><a href="http://www.w3.org/2012/ldp/track/issues/44">ISSUE-44</a></div>
@@ -411,7 +429,7 @@
 		a link relation type of <code>type</code> (that is, <code>rel="type"</code>)
 		in all responses to requests made 
 		to the resource's HTTP <code>request-URI</code>. This is notionally equivalent to the
-		presence of a <code>< subject-URI, rdf:type , ldp:Resource ></code> triple in the resource.
+		presence of a <code>&lt; subject-URI, rdf:type , ldp:Resource &gt;</code> triple in the resource.
 		The HTTP <code>Link</code> header is the method by which servers assert their support for the LDP spec in a way
 		that clients can introspect dynamically at run-time.  Conservative clients should note that 
 		a server can host a mixture of LDPRs and other resources, and therefore there is no implication
@@ -787,43 +805,76 @@
 </section>
 
 <section>
-<h2 id="ldpr-inlining">Representing Multiple Resources in a Response</h2>
+<h2 id="ldpr-inlining">Resource Inlining: Representing Multiple Resources in a Response</h2>
+
+	<div class="ldp-issue-open">
+	The contents of this section are AT RISK.  They may be removed after Last Call based on community feedback.
+	</div>
 
 <section>
 <h3 id="ldpr-InliningIntro">Introduction</h3>
 	<em>This section is non-normative.</em>
 	
 	<p>Servers whose resources are relatively granular may wish to optimistically provide more information
-		in a response than what the client actually requested, in order to reduce the overall number of client
-		application HTTP flows on average.  LDP provides some basic building blocks to enable
-		this, that implementations can re-use to build complete solutions.  These building blocks are 
-		collectively referred to as resource inlining.
+		in a response than what the client actually requested, in order to reduce the average number of client
+		application HTTP flows.  LDP provides some basic building blocks to enable
+		this, that implementations can re-use to build complete solutions, and they may serve as 
+		complete solutions in applications with sufficient controls on resource content.
+		These building blocks are <a>resource inlining</a> and <a>member inlining</a>.
 	</p>
 	
 	<p>LDP does not provide clients with any way to detect whether or not the server is capable of 
-		resource inlining (all its resources or any specific resource), nor does it provide clients 
+		inlining (all its resources or any specific resource), nor does it provide clients 
 		with any way to influence which (if any) resources are inlined in any given response.
 	</p>
+	
+	<p>
+		Servers can return extra triples on any response, but fail to meet the definition of <a>resource inlining</a>, 
+		by either returning a subset of the other resource(s) triples or by failing to assert that
+		all triples were included (even through they were).  Clients might still find the extra
+		information useful, but the only way for clients to be sure they had all available 
+		information would be to make a HTTP <code>GET</code> request against all the other resource(s).
+		In some applications, knowing that these requests are unnecessary saves significant latency
+		and server/network load.
+	</p>
 </section> <!-- h3 -->
 
 <section>
 <h3 id="ldpr-InliningWarnings">Use with Care</h3>
 	<em>This section is non-normative.</em>
 	
-	<div class="ldp-issue-open">
+	<div class="ldp-issue-pending">
 	<div class="ldp-issue-title"><a href="http://www.w3.org/2012/ldp/track/issues/58">ISSUE-58</a></div>
 	Action 87: Add an informative section on the possible dangers of inlining resources
 	</div>
 
-	<p>The building blocks LDP provides can only be safely used if certain assumptions hold.
-	...
+	<p>The building blocks LDP provides can only be safely used if certain assumptions hold.  
+	Said another way, resource inlining solves a subset of scenarios, not all scenarios in the general case &mdash;
+	so if you care about any of the following in a given application, your server should avoid returning
+	<em>any</em> triples beyond those found at the HTTP <code>request-URI</code>.
 	</p>
+	<ul>
+	<li><p>
+		Provenance is lost: because RDF graphs from multiple HTTP resources are merged in the
+		response without quotation, it is impossible for a client to reliably know which
+		triples came from which HTTP resource(s).  A general solution allowing quotation is
+		RDF Datasets; that is expected to be standardized independently, and can be used in these cases
+		once it is available.
+	</p></li>
+	<li><p>
+		The response may contain contradictions that are trivially obvious (or subtle), and those may or 
+		may not be a problem at the application level.  For a trivial example, two triples may have
+		identical subjects and predicates but different objects: "75F is too hot"; "75F is too cold".
+		Again, quotation via RDF Datasets (or any equivalent mechanism) is believed to provide a 
+		long term solution once standardized.
+	</p></li>
+	</ul>
 </section> <!-- h3 -->
 
 <section>
 <h3 id="ldpr-InliningGET">HTTP GET</h3>
 	<p>In addition to the requirements set forth in other sections, 
-		LDPR Servers that support resource inlining 
+		LDPR Servers that support <a>resource inlining</a>
 		must also follow the requirements in this section.</p>
 
 	<div class="ldp-issue-pending">
@@ -832,11 +883,7 @@
 	marked as AT RISK.
 	</div>
 
-	<div class="ldp-issue-open">
-	The contents of this section are AT RISK.  They may be removed after Last Call based on community feedback.
-	</div>
-
-	<div id="ldpr-4_10_2_1" class="rule">4.10.2.1 LDPR servers that inline triples from other resource(s) in a representation SHOULD 
+	<div id="ldpr-4_10_2_1" class="rule">4.10.2.1 LDPR servers that support <a>resource inlining</a> MUST 
 		include a <code>ldp:Page</code> resource in the representation describing the set of inlined resources, 
 		whether or not the representation contains subsequent pages.  The <code>ldp:Page</code> resource conceptually contains
 		metadata about the representation; it is usually not part of the HTTP resource's state, and its presence does not indicate that
@@ -846,12 +893,12 @@
 		in order to minimize client code complexity.
 		The <code>ldp:Page</code> resource's triples are the LDP-defined means by which the servers communicate to LDP clients 
 		the set of HTTP resources whose state is included in a representation, allowing clients to avoid HTTP <code>GET</code>
-		requests for them, reducing client application latency and reducing load on the server and network.
+		requests for them.
 	</div>
 
-	<div id="ldpr-4_10_2_2" class="rule">4.10.2.2 LDPR servers that 
-		include a <code>ldp:Page</code> resource as described in <a href="#ldpr-4_10_2_1">section 4.10.2.1</a> MUST
-		include in it one triple for each fully inlined resource, 
+	<div id="ldpr-4_10_2_2" class="rule">4.10.2.2 LDPR servers that support <a>resource inlining</a> MUST 
+		include the <code>ldp:Page</code> resource described in <a href="#ldpr-4_10_2_1">section 4.10.2.1</a> 
+		one triple for each inlined resource, 
 		whose subject is the <code>ldp:Page</code> resource URI,
 		whose predicate is <code>ldp:inlinedResource</code>, and
 		whose object is the HTTP <code>request-URI</code> of an inlined resource [[!HTTP11]].
@@ -870,8 +917,8 @@
 		listed in the representation whose HTTP <code>request-URI</code> differs from 
 		the HTTP <code>request-URI</code> used by the client.  
 		The representation might in fact contain all such triples, or some
-		subset of them, that might or might not be completely adequate for the client's intended usage, but
-		an LDP client has no way to discern which interpretation is accurate.
+		subset of them, and that might or might not be completely adequate for the client's intended usage, but
+		an LDP client has no way to discern from such a representation which interpretation is accurate.
 	</div>
 
 </section>
@@ -1692,7 +1739,11 @@
 </section>
 
 <section>
-<h2 id="ldpc-inlining">Inlining Members in a Response</h2>
+<h2 id="ldpc-inlining">Member Inlining: Returning All of a Container Page's Members in a Response</h2>
+
+		<div class="ldp-issue-open">
+	The contents of this section are AT RISK.  They may be removed after Last Call based on community feedback.
+	</div>
 
 <section>
 <h3 id="ldpc-InliningIntro">Introduction</h3>
@@ -1702,13 +1753,13 @@
 		<i>m</i> members from having to perform <i>m+1</i> HTTP requests (or <i>m+p</i>, if the container
 		is paged into <i>p</i> pages).  The desire is to allow the server to reduce the number of HTTP
 		round-trips by returning some (perhaps all) members' content as part of the container's representation.
-		In addition to the general <a href="#ldpr-inlining">resource inlining building blocks</a> that can
-		be used in cases where only a subset of the members' content is inlined, LDP also provides 
+		In addition to the general <a>resource inlining</a> mechanism useful
+		in cases where only a subset of the members' content is inlined, LDP also provides 
 		a predicate for the special case where <i>all</i> of a container's or page's members are inlined.
 		Rather than forcing the server to add a triple for each inlined member, forcing clients to
 		compare the list of inlined members against the set of members in the representation, 
 		and enlarging the representation needlessly,
-		a single triple can be used.
+		a single triple can be used.  This is called <a>member inlining</a>.
 	</p>
 
 	<p>LDP does not provide clients with any way to detect whether or not the server is capable of 
@@ -1716,12 +1767,12 @@
 		with any way to influence which (if any) resources are inlined in any given response.
 	</p>
 
-	<div class="ldp-issue-open">
+	<div class="ldp-issue-pending">
 	<div class="ldp-issue-title"><a href="http://www.w3.org/2012/ldp/track/issues/58">ISSUE-58</a></div>
 	Action 87: Add an informative section on the possible dangers of inlining resources
 	</div>
 
-	<p>The building blocks LDP provides can only be safely used if certain assumptions hold.
+	<p>The inlining building blocks LDP provides can only be safely used if certain assumptions hold.
 		This is no less true for containers than for LDPRs in general.  
 		See the general <a href="#ldpr-InliningWarnings">cautions on resource inlining</a>.
 	</p>
@@ -1730,7 +1781,7 @@
 <section>
 <h3 id="ldpc-InliningGET">HTTP GET</h3>
 	<p>In addition to the requirements set forth in other sections, 
-		LDPC Servers that support resource inlining of all members in a page or container,
+		LDPC Servers that support <a>member inlining</a>,
 		and LDP Clients aware of the same facility,
 		must also follow the requirements in this section.
 	</p>
@@ -1743,26 +1794,22 @@
 		marked as AT RISK.
 	</div>
 
-		<div class="ldp-issue-open">
-	The contents of this section are AT RISK.  They may be removed after Last Call based on community feedback.
-	</div>
-
-	<div id="ldpc-5_10_2_1" class="rule">5.10.2.1 LDPC servers that inline all members in a representation SHOULD 
+	<div id="ldpc-5_10_2_1" class="rule">5.10.2.1 LDPC representations that are <a title="member inlining">member inlined</a> MUST 
 		include a <code>ldp:Page</code> resource in the representation, whether or not the representation contains
-		multiple pages, as described in <a href="#ldpr-inlining">resource inlining</a>.  In addition to satisfying
+		multiple pages, as described in <a href="#ldpr-4_10_2_1">section 4.10.2.1</a>.  In addition to satisfying
 		those requirements, the representation MUST contain a triple
 		whose subject is the <code>ldp:Page</code> resource URI,
 		whose predicate is <code>ldp:membersInlined</code>, and
 		whose object is <code>true</code>.
 		This is means by which the server communicates to LDP clients that they can avoid HTTP <code>GET</code>
-		requests for the inlined members, reducing their own latency and reducing server and network load.
+		requests for the members listed on the page.
 	</div>
 
 	<div id="ldpc-5_10_2_2" class="rule">5.10.2.2 LDPC clients SHOULD avoid making HTTP <code>GET</code> requests
 		against any members in a LDPC representation containing a <code>ldp:Page</code> resource with the triple
 		described in <a href="#ldpc-5_10_2_1">section 5.10.2.1</a>, unless there are application-specific
 		reasons for doing so.  Clients should note that by the time the representation is received, the actual state
-		of any inlined members may have changed due to subsequent requests.
+		of inlined members may have changed due to subsequent requests.
 	</div>
 
 	<div id="ldpc-5_10_2_3" class="rule">5.10.2.3 LDPC clients MUST NOT assume that LDPC representations
@@ -1770,7 +1817,7 @@
 		described in <a href="#ldpc-5_10_2_1">section 5.10.2.1</a> contain all the triples for all members
 		listed in the representation.  The representation might in fact contain all those triples, or some
 		subset of them, that might or might not be completely adequate for the client's intended usage, but
-		an LDP client has no way to discern which interpretation is accurate.
+		an LDP client has no way to discern from such a representation which interpretation is accurate.
 	</div>
 
 	</section>
@@ -1781,10 +1828,10 @@
 </section>
 
 <section>
-<h2>HTTP Header Definitions</h2>
+<h1>HTTP Header Definitions</h1>
      
 <section>
-<h3 id="header-accept-post">The Accept-Post Response Header</h3>
+<h2 id="header-accept-post">The Accept-Post Response Header</h2>
 
 	<div class="ldp-issue-pending">
 	<div class="ldp-issue-title"><a href="http://www.w3.org/2012/ldp/track/issues/80">ISSUE-80</a></div>
@@ -1817,7 +1864,7 @@
 	</div>
 	
 <section>
-<h4 id="header-accept-post-iana">IANA Registration Template</h4>
+<h3 id="header-accept-post-iana">IANA Registration Template</h3>
 	<blockquote>
 	<p>
 	The Accept-Post response header must be added to the permanent registry (see [[!RFC3864]]).
@@ -1864,6 +1911,7 @@
 <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130701/">Third Public Working Draft</a></em></blockquote>
 -->
 <ul>
+	<li>2013-07-09 - ISSUE-58 inlining - actions 87-89 inclusive  (JA)</li>
 	<li>2013-07-08 - Moved 5.7.* sections out of HEAD and into OPTIONS as 5.9.*, added 4.6.2 (SS)</li>
 	<li>2013-07-08 - ISSUE-15 Inserted 5.4.12, 5.6.4, 5.7.2 to describe link-relation meta usage (SS)</li>
 	<li>2013-07-08 - ISSUE-79 ldp:contains  (JA)</li>