More example revisions, and fix bug in advisors example
authorJohn Arwe
Wed, 16 Apr 2014 17:36:23 -0400
changeset 564 cba76c3813b9
parent 563 4e61db8dbfa2
child 565 76006e897d7f
More example revisions, and fix bug in advisors example
ldp.html
--- a/ldp.html	Wed Apr 16 16:34:32 2014 -0400
+++ b/ldp.html	Wed Apr 16 17:36:23 2014 -0400
@@ -963,7 +963,7 @@
 	<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; 
+	LDP patterns onto existing 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
@@ -989,16 +989,16 @@
 </pre>
 	<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 
+	resource represents an instance of a person's net worth and a <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.  Existing domain-specific applications exist that depend on those types and 
-	predicates, so changing them <strong>incompatibly</strong> would be frowned upon.
+	predicates, so changing them <em>incompatibly</em> 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>
+	Doing so using a Basic Container would require duplicating much of the information with different types and
+	predicates, which would be onerous for large resources.  <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, 
@@ -1032,13 +1032,13 @@
 
 
 	<p>The structure of the net worth resource is completely unchanged, so any existing 
-	domain-specific applications continue to work without change.
+	domain-specific applications continue to work without impact.
 	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>
+	Direct Containers add the concept of <a title="Membership">membership</a>
 	and flexibility on how to specify the <a title="Membership triples">membership triples</a>.
 	</p>
 
@@ -1089,6 +1089,29 @@
 	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>
+	To add a another liability, a client would POST something like this to the liability container:
+	</p>
+
+<pre class="example" id="ldpc-ex-membership-add-new-liability"># The following is a representation of the liability to be added
+#   http://example.org/netWorth/nw1/liabilities/new
+<!-- @base is here only so it's easier to paste into validators for checking -->
+# @base &lt;http://example.org/netWorth/nw1/liabilities/new&gt;.
+@prefix o: &lt;http://example.org/ontology/&gt;.
+&lt;&gt;
+   a o:Liability.
+   # plus any other properties that the domain says liabilities have
+</pre>
+
+	<p>
+	Assuming the server successfully processes this request and assigns the URI
+	<code>&lt;http://example.org/netWorth/nw1/liabilities/l4&gt;</code> to the 
+	newly created liability resource, at least two new triples would be added.
+	</p>
+	<ol>
+	<li>In the net worth resource, <code>o:liability &lt;l4&gt;</code></li>
+	<li>In the liability container, <code>ldp:contains &lt;l4&gt;</code>.</li>
+	</ol>
 
 	<p>
 	You might wonder why we chose to create two new containers instead of making
@@ -1100,7 +1123,8 @@
 	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.
+	allows both assets and liabilities to be created.  Similar ambiguities arise
+	if the client wishes to list the members and/or contained resources.
 	</p>
 
 	<p>Continuing in the multiple containers direction, we will now extend our net worth example to add a container for
@@ -1121,18 +1145,18 @@
    a o:NetWorth;
    o:netWorthOf &lt;http://example.org/users/JohnZSmith&gt;;
    o:advisor
-   	 &lt;advisorContainer/bob#me&gt;,
-   	 &lt;advisorContainer/marsha#me&gt;.
+   	 &lt;advisors/bob#me&gt;,
+   	 &lt;advisors/marsha#me&gt;.
    	 
-&lt;advisorContainer/&gt;
+&lt;advisors/&gt;
    a ldp:IndirectContainer;
    dcterms:title "The asset advisors of JohnZSmith";
    ldp:membershipResource &lt;&gt;;
    ldp:hasMemberRelation o:advisor;
    ldp:insertedContentRelation foaf:primaryTopic;
    ldp:contains
-   	 &lt;advisorContainer/bob&gt;,
-   	 &lt;advisorContainer/marsha&gt;.
+   	 &lt;bob&gt;,
+   	 &lt;marsha&gt;.
 </pre>	
 	
 	<p>To handle this type of indirection, the triple with predicate of <code>ldp:insertedContentRelation</code> and object of 
@@ -1142,11 +1166,37 @@
 	
 	<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, 
+	but it provides an indirection to add (via a create request) as a member any resource, 
 	such as a URI representing a real-world object,
 	that is different from the document that is created.</p>
 
-	<p><a href="#fig-ldpc-types"></a> illustrates the 3 types: Container, Basic Container and Direct Container, along
+	<p>
+	To add a another advisor, a client would POST something like this to the advisors container:
+	</p>
+
+<pre class="example" id="ldpc-ex-membership-add-new-advisor"># The following is a representation of the advisor to be added
+#   http://example.org/netWorth/nw1/advisors/new
+<!-- @base is here only so it's easier to paste into validators for checking -->
+# @base &lt;http://example.org/netWorth/nw1/advisors/new&gt;.
+@prefix foaf: &lt;http://xmlns.com/foaf/0.1/&gt;.
+@prefix o: &lt;http://example.org/ontology/&gt;.
+&lt;&gt;
+   a o:Advisor;
+   foaf:primaryTopic &lt;#me&gt;.
+   # plus any other properties that the domain says advisors have
+</pre>
+
+	<p>
+	Assuming the server successfully processes this request and assigns the URI
+	<code>&lt;http://example.org/netWorth/nw1/advisors/george&gt;</code> to the 
+	newly created advisor resource, at least two new triples would be added.
+	</p>
+	<ol>
+	<li>In the net worth resource, <code>o:advisor &lt;advisors/george#me&gt;</code></li>
+	<li>In the advisors container, <code>ldp:contains &lt;george&gt;</code></li>
+	</ol>
+
+	<p>In summary, <a href="#fig-ldpc-types"></a> illustrates the LDP-defined container types: Basic, Direct, and Indirect, along
 	with their class relationship to types of LDPRs.</p>
 	
 	 <figure id="fig-ldpc-types">