ldp.html
changeset 174 72ce83f4ec7f
parent 173 116161fab05a
child 175 bcc13fba2593
--- a/ldp.html	Tue Jul 09 08:05:53 2013 -0400
+++ b/ldp.html	Tue Jul 09 13:29:24 2013 -0400
@@ -339,7 +339,6 @@
 	<div class="ldp-issue-title"><a href="http://www.w3.org/2012/ldp/track/issues/77">ISSUE-77</a></div>
 	why MUST a LDPR declare its type?  remove 4.1.5
 	</div>
-	</div>
 	<div id="ldpr-4_1_5" class="rule"><del>4.1.5 LDPRs MUST use the predicate <code>rdf:type</code> to
 		represent the concept of type. The use of non-standard type
 		predicates, as well as <code>dcterms:type</code>, is
@@ -361,7 +360,6 @@
 	<div class="ldp-issue-title"><a href="http://www.w3.org/2012/ldp/track/issues/44">ISSUE-44</a></div>
 	4.1.9.(now 4.1.7) is obscure or too restrictive
 	</div>
-	</div>
 	<div id="ldpr-4_1_8" class="rule">4.1.8 LDPR servers MAY support standard representations beyond those
 		necessary to conform to this specification. These
 		could be other RDF formats, like N3 or NTriples, but non-RDF formats
@@ -788,8 +786,100 @@
 
 </section>
 
+<section>
+<h2 id="ldpr-inlining">Representing Multiple Resources in a Response</h2>
+
+<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.
+	</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 
+		with any way to influence which (if any) resources are inlined in any given response.
+	</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-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>
+</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 
+		must also follow the requirements in this section.</p>
+
+	<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 89: Add a predicate ldp:inlinedResource the object of which is a URI of a linked resource that is fully inlined, 
+	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 
+		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
+		the LDPR server supports <a href="#ldpr-Paging">paging</a> in general.  
+		LDPR servers that include the <code>ldp:Page</code> resource for inlining and also support 
+		paging MUST use the same <code>ldp:Page</code> resource for the triples required by both,
+		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.
+	</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, 
+		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]].
+	</div>
+
+	<div id="ldpc-4_10_2_3" class="rule">4.10.2.3 LDPR clients SHOULD avoid making HTTP <code>GET</code> requests
+		against any resource whose HTTP <code>request-URI</code> is the object of a triple of the form 
+		described in <a href="#ldpc-4_10_2_2">section 4.10.2.2</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 resource(s) may have changed due to subsequent requests.
+	</div>
+
+	<div id="ldpc-4_10_2_4" class="rule">4.10.2.4 LDPR clients MUST NOT assume that LDPR representations
+		lacking a <code>ldp:Page</code> resource or lacking the triple
+		described in <a href="#ldpc-4_10_2_2">section 4.10.2.2</a> contain all the triples for any resource(s)
+		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.
+	</div>
+
 </section>
 
+</section> <!-- h2 -->
+
+</section> <!-- h1 -->
+
 <section>
 <h1 id="ldpc">Linked Data Platform Containers</h1>
 
@@ -1390,12 +1480,12 @@
 		triples whose subject is the null relative URI will usually result in
 		triples in the created resource whose subject is the created
 		resource.  
+	</div>	
 		
 	<div class="ldp-issue-closed">
 	<div class="ldp-issue-title"><a href="http://www.w3.org/2012/ldp/track/issues/20">ISSUE-20</a></div>
 	Identifying and naming POSTed resources using &lt;&gt;
 	</div>	
-	</div>
 	
 	<div id="ldpc-5_4_8" class="rule">5.4.8 LDPC servers SHOULD assign the subject URI for the resource to be
 		created using server application specific rules in the absence of a <a href="#ldpc-5_4_10">client hint</a>.
@@ -1435,6 +1525,7 @@
 	cases the header registration says SHOULD, and the LDP spec says MUST.  What makes that look a bit odd is
 	that in the Accept-Post case, the registration and LDP are the same document.  Thus I added informative
 	text here explicitly talking to the apparent discrepancy.
+	</p>
 	</div>	
 		
 	<div id="ldpr-5_4_13" class="rule">5.4.13 LDPR servers that support <code>POST</code> MUST
@@ -1569,6 +1660,8 @@
 
 <section>
 <h2 id="ldpc-HTTP_OPTIONS">HTTP OPTIONS</h2>
+	<p>This specification imposes the following new requirements on HTTP OPTIONS for LDPCs.
+		</p>
 
 	<div id="ldpc-5_9_1" class="rule">5.9.1  
 		LDPC servers SHOULD define a corresponding
@@ -1597,6 +1690,94 @@
 	header whose target URI is the associated LDPR, and whose link relation type is 
 	<code>meta</code> [[!RFC5988]].</div>
 </section>
+
+<section>
+<h2 id="ldpc-inlining">Inlining Members in a Response</h2>
+
+<section>
+<h3 id="ldpc-InliningIntro">Introduction</h3>
+	<em>This section is non-normative.</em>
+	
+	<p>One of the most commonly cited scenarios for resource inlining is to save clients enumerating a container of 
+		<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 
+		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.
+	</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 
+		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-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.
+		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>
+</section> <!-- h3 -->
+
+<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,
+		and LDP Clients aware of the same facility,
+		must also follow the requirements in this section.
+	</p>
+
+	<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 88: Add a property ldp:membersInlined true/false. The default (if not specified) is false. 
+		If true, it means that a complete description of all members [on the current page] are inlined with the container document [or page], 
+		and therefore clients SHOULD NOT do GET on the member URIs to retrieve additional triples.
+		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 
+		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
+		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.
+	</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.
+	</div>
+
+	<div id="ldpc-5_10_2_3" class="rule">5.10.2.3 LDPC clients MUST NOT assume that LDPC representations
+		lacking a <code>ldp:Page</code> resource or lacking the triple
+		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.
+	</div>
+
+	</section>
+
+</section> <!-- h2 -->
+
+
 </section>
 
 <section>