ldp.html
changeset 563 4e61db8dbfa2
parent 562 e6d8108df386
child 564 cba76c3813b9
--- a/ldp.html	Wed Apr 16 11:48:36 2014 -0400
+++ b/ldp.html	Wed Apr 16 16:34:32 2014 -0400
@@ -951,20 +951,26 @@
     </figure>
      -->
 
-	<p>This example is very straightforward - there is the containment triple
-	with subject of the container, predicate of  
-	<code>ldp:contains</code> and objects indicating the URIs of the contained resources. 
+	<p>The preceding example is very straightforward: there are containment triples
+	whose subject is the container, whose predicate is  
+	<code>ldp:contains</code>, and whose objects are the URIs of the contained resources,
+	and there is no distinction between member resources and contained resources. 
 	A POST to this container will create a new resource
 	and add it to the list of contained resources by adding a new containment triple
-	to the container.  This type of container is also referred to as a
-	<a title="">Linked Data Platform Basic Container</a>.</p>
+	to the container.  This type of container is called a
+	<a title="">Linked Data Platform Basic Container</a>.  </p>
 
-	<p>Sometimes it is useful to use a subject
+	<p>
+	Sometimes you have to build on existing models incrementally, so you have fewer degrees of
+	freedom in the resource model.  In these situations, it can be useful to help clients map
+	LDP patterns onto other vocabularies, or to include members not created via the container; 
+	<a title="Linked Data Platform Direct Container">LDP Direct Containers</a>
+	meet those kinds of needs.  Direct Containers allow membership triples to use a subject
 	other than the container itself as the consistent membership value, and/or to use
 	a  predicate from an application's domain model as the membership predicate. Let's
-	start with a domain resource for a person's net worth, as illustrated below:</p>
+	start with a pre-existing domain resource for a person's net worth, as illustrated below:</p>
 			
-<pre class="example" id="ldpc-ex-membership-partial"># The following is a partial representation of
+<pre class="example" id="ldpc-ex-membership-partial"># The following is a representation of
 #   http://example.org/netWorth/nw1
 <!-- @base is here only so it's easier to paste into validators for checking -->
 # @base &lt;http://example.org/netWorth/nw1/&gt;
@@ -974,22 +980,38 @@
    a o:NetWorth;
    o:netWorthOf &lt;http://example.org/users/JohnZSmith&gt;;
    o:asset 
-      &lt;assetContainer/a1&gt;,
-      &lt;assetContainer/a2&gt;;
+      &lt;assets/a1&gt;,
+      &lt;assets/a2&gt;;
    o:liability 
-      &lt;liabilityContainer/l1&gt;,
-      &lt;liabilityContainer/l2&gt;,
-      &lt;liabilityContainer/l3&gt;.
+      &lt;liabilities/l1&gt;,
+      &lt;liabilities/l2&gt;,
+      &lt;liabilities/l3&gt;.
 </pre>
-	<p>From this example, there is a <code>rdf:type</code> of <code>o:NetWorth</code> indicating the
+	<p>
+	In the preceding example, there is a <code>rdf:type</code> of <code>o:NetWorth</code> indicating the
 	resource represents an instance of a person's net worth and <code>o:netWorthOf</code> predicate indicating 
 	the associated person.  There are two sets of same-subject, same-predicate pairings; one for assets and
-	one for liabilities.  It would be helpful to be able to associate these multi-valued sets using a URL
-	for them to assist with managing these; this is done by associating containers with them as 
-	illustrated in the set of related examples (one example per HTTP resource) below:
+	one for liabilities.  Existing domain-specific applications exist that depend on those types and 
+	predicates, so changing them <strong>incompatibly</strong> would be frowned upon.
+	</p>
+	
+	<p>
+	It would be helpful to be able to use LDP patterns to manage the assets and liabilities-related triples.
+	Doing so using a Basic Container would require duplicating much of the information with different types
+	predicates, which is less helpful.  <a title="Linked Data Platform Direct Container">Direct Containers</a>
+	provide a middle ground, by giving LDP clients a way to map existing domain-specific resources to LDP's
+	types and interaction models.  
+	In this specific example, 
+	it would be helpful to be able to manage the assets and liabilities triples consistently, for example
+	by using LDP containers.
+	One way to do this is to create two containers, one to manage assets and another liabilities, 
+	as separate HTTP resources.  Existing clients would have no need to interact with those containers,
+	whereas LDP-enabled clients now have container URLs that they can interact with, and the existing
+	resource can remain unchanged so that existing clients continue to function normally.
+	This is illustrated in the set of related examples (one example per HTTP resource) below:
 	</p>
 
-<pre class="example" id="ldpc-ex-membership-full"># The following is an elaborated representation of LDPR
+<pre class="example" id="ldpc-ex-membership-full"># The following is a representation of the unchanged net worth LDPR
 #   http://example.org/netWorth/nw1
 <!-- @base is here only so it's easier to paste into validators for checking -->
 # @base &lt;http://example.org/netWorth/nw1/&gt;.
@@ -1000,18 +1022,30 @@
    a o:NetWorth;
    o:netWorthOf &lt;http://example.org/users/JohnZSmith&gt;;
    o:asset 
-      &lt;assetContainer/a1&gt;,
-      &lt;assetContainer/a2&gt;;
+      &lt;assets/a1&gt;,
+      &lt;assets/a2&gt;;
    o:liability 
-      &lt;liabilityContainer/l1&gt;,
-      &lt;liabilityContainer/l2&gt;,
-      &lt;liabilityContainer/l3&gt;.
+      &lt;liabilities/l1&gt;,
+      &lt;liabilities/l2&gt;,
+      &lt;liabilities/l3&gt;.
 </pre>
 
-<pre class="example" id="ldpc-ex-membership-subj"># The following is an elaborated representation of LDPC
-#   http://example.org/netWorth/nw1/assetContainer/
+
+	<p>The structure of the net worth resource is completely unchanged, so any existing 
+	domain-specific applications continue to work without change.
+	LDP clients, on the other hand, have no way to understand that the asset and
+	liability triples correspond in any way to LDP containers.  For that, they need the
+	next two resources.
+	</p>
+	<p>The first container is a <a title="Linked Data Platform Direct Container">LDP Direct Container</a> to manage assets.  
+	<a title="Linked Data Platform Direct Container">LDP Direct Container</a> adds the concept of <a title="Membership">membership</a>
+	and flexibility on how to specify the <a title="Membership triples">membership triples</a>.
+	</p>
+
+<pre class="example" id="ldpc-ex-membership-subj"># The following is a representation of the asset container
+#   http://example.org/netWorth/nw1/assets/
 <!-- @base is here only so it's easier to paste into validators for checking -->
-# @base &lt;http://example.org/netWorth/nw1/assetContainer/&gt;.
+# @base &lt;http://example.org/netWorth/nw1/assets/&gt;.
 @prefix ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
 @prefix dcterms: &lt;http://purl.org/dc/terms/&gt;.
 @prefix o: &lt;http://example.org/ontology/&gt;.
@@ -1023,10 +1057,23 @@
    ldp:contains &lt;a1&gt;, &lt;a2&gt;.
 </pre>
 
-<pre class="example" id="ldpc-ex-membership-full-liabcont"># The following is an elaborated representation of LDPC
-#   http://example.org/netWorth/nw1/liabilityContainer/
+	<p>
+	In the preceding asset container, the consistent membership value 
+	(<a title="Membership triples">membership-constant-URI</a>, still in the subject position) is not the
+	container itself – it is the (separate) net worth resource. The
+	membership predicate is <code>o:asset</code>,
+	from the domain model. A POST of an asset representation to the asset container will create a new
+	asset and add it to net-worth's list of	assets by adding a new membership triple
+	to the resource and containment triple to the container. 
+	</p>
+
+	<p>The second container is a <a title="Linked Data Platform Direct Container">LDP Direct Container</a> to manage liabilities.  
+	</p>
+
+<pre class="example" id="ldpc-ex-membership-full-liabcont"># The following is a representation of the liability container
+#   http://example.org/netWorth/nw1/liabilities/
 <!-- @base is here only so it's easier to paste into validators for checking -->
-# @base &lt;http://example.org/netWorth/nw1/liabilityContainer/&gt;.
+# @base &lt;http://example.org/netWorth/nw1/liabilities/&gt;.
 @prefix ldp: &lt;http://www.w3.org/ns/ldp#&gt;.
 @prefix dcterms: &lt;http://purl.org/dc/terms/&gt;.
 @prefix o: &lt;http://example.org/ontology/&gt;.
@@ -1038,34 +1085,25 @@
    ldp:contains &lt;l1&gt;, &lt;l2&gt;, &lt;l3&gt;.
 </pre>
 
-	<p>The essential structure of the container is
-	the same, but in this example, the consistent membership value 
-	(<a title="Membership triples">membership-constant-URI</a>, still in the subject position) is not the
-	container itself – it is a separate net worth resource. The
-	membership predicates are <code>o:asset</code> and <code>o:liability</code> – predicates
-	from the domain model. A POST of an asset representation to the asset container will create a new
-	asset and add it to the list of	members by adding a new membership triple
-	to the resource and containment triple to the container. You might wonder why
-	<code>http://example.org/netWorth/nw1</code> isn't made a container itself and POST
-	the new asset directly there. That would be a fine design if <code>http://example.org/netWorth/nw1</code>
-	had only assets, but if it has separate predicates for assets and liabilities,
-	that design will not work because it is unspecified to which predicate the POST
-	should add a membership triple. Having separate <code>http://example.org/netWorth/nw1/assetContainer/</code> 
-	and <code>http://example.org/netWorth/nw1/liabilityContainer/</code> container
-	resources allows both assets and liabilities to be created.
-	</p>
-	<p>This type of container is referred to as an <a title="Linked Data Platform Direct Container">LDP Direct Container</a>.  
-	<a title="Linked Data Platform Direct Container">LDP Direct Container</a> adds the concept of <a title="Membership">membership</a>
-	and flexibility on how to specify the <a title="Membership triples">membership triples</a>.
+	<p>
+	The preceding liability container is completely analogous to the asset container above, simply
+	managing liabilities instead of assets and using the <code>o:liability</code> predicate.
 	</p>
 
-	<p>As seen in the <a href="#ldpc-ex-membership-subj"><code>assetContainer/</code> example</a>, 
-	clients cannot correctly guess
-	at the membership triples, so the example includes this information in
-	triples whose subject is the LDPC resource itself.
+	<p>
+	You might wonder why we chose to create two new containers instead of making
+	<code>http://example.org/netWorth/nw1</code> itself a (single) container.
+	A single net worth container would be a fine design if <code>http://example.org/netWorth/nw1</code>
+	had only assets or only liabilities (basically: only a single predicate to manage), 
+	but since it has separate predicates for assets and liabilities an ambiguity arises:
+	it is unspecified to whether a client's creation request (POST)
+	should add a new <code>o:asset</code> or <code>o:liability</code> triple. 
+	Having separate <code>http://example.org/netWorth/nw1/assets/</code> 
+	and <code>http://example.org/netWorth/nw1/liabilities/</code> containers
+	allows both assets and liabilities to be created.
 	</p>
-	
-	<p>Additionally, we could extend our net worth example to include a container for
+
+	<p>Continuing in the multiple containers direction, we will now extend our net worth example to add a container for
 	advisors (people) that have managed the assets and liabilities.  We have decided
 	to identify these advisors with URLs that contain a fragment (hash) to represent
 	these real-world resources, not the documents that describe them.</p>
@@ -1102,7 +1140,7 @@
 	form <code>(&lt;&gt;, foaf:primaryTopic, topic-URI)</code> to inform the server which URI to use 
 	(<code>topic-URI</code>) in the new membership triple.</p>
 	
-	<p>This type of container is also referred to as a <a title="Linked Data Platform Indirect Container">LDP Indirect Container</a>. 
+	<p>This type of container is referred to as a <a title="Linked Data Platform Indirect Container">LDP Indirect Container</a>. 
 	It is similar to an <a title="Linked Data Platform Direct Container">LDP Direct Container</a> 
 	but it provides an indirection to add (via a create request) as member any resource, 
 	such as a URI representing a real-world object,
@@ -1972,9 +2010,9 @@
 	</p>
 	<pre class="example" id="prefer-examples-direct">
 	# The following is the representation of
-	#   http://example.org/netWorth/nw1/assetContainer/
+	#   http://example.org/netWorth/nw1/assets/
 	<!-- @base is here only so it's easier to paste into validators for checking -->
-	# @base &lt;http://example.org/netWorth/nw1/assetContainer/&gt;.
+	# @base &lt;http://example.org/netWorth/nw1/assets/&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;.
@@ -2014,9 +2052,9 @@
 	
 	<pre class="example">
 	# The following is the representation of
-	#   http://example.org/netWorth/nw1/assetContainer/
+	#   http://example.org/netWorth/nw1/assets/
 	<!-- @base is here only so it's easier to paste into validators for checking -->
-	# @base &lt;http://example.org/netWorth/nw1/assetContainer/&gt;.
+	# @base &lt;http://example.org/netWorth/nw1/assets/&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;.
@@ -2045,9 +2083,9 @@
 	
 	<pre class="example">
 	# The following is the representation of
-	#   http://example.org/netWorth/nw1/assetContainer/
+	#   http://example.org/netWorth/nw1/assets/
 	<!-- @base is here only so it's easier to paste into validators for checking -->
-	# @base &lt;http://example.org/netWorth/nw1/assetContainer/&gt;.
+	# @base &lt;http://example.org/netWorth/nw1/assets/&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;.
@@ -2081,9 +2119,9 @@
 	
 	<pre class="example">
 	# The following is the representation of
-	#   http://example.org/netWorth/nw1/assetContainer/
+	#   http://example.org/netWorth/nw1/assets/
 	<!-- @base is here only so it's easier to paste into validators for checking -->
-	# @base &lt;http://example.org/netWorth/nw1/assetContainer/&gt;.
+	# @base &lt;http://example.org/netWorth/nw1/assets/&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;.
@@ -2258,6 +2296,7 @@
 <h2>Detailed history</h2>
 <!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130930/">Candidate Recommendation Draft</a></em></blockquote> -->
 <ul>
+	<li>2014-04-16 - Update narrative on net worth example (#s 2-5, section 5.1, at time of writing) (JA) </li>
 	<li>2014-04-16 - Clarify language of 5.2.5.1/2 (JA) </li>
 	<li>2014-04-16 - Clarify definitions of membership and containment triples (JA) </li>
 	<li>2014-04-15 - Rename empty-container triples to minimal-container triples (JA) </li>