--- 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 <http://example.org/netWorth/nw1/>
@@ -974,22 +980,38 @@
a o:NetWorth;
o:netWorthOf <http://example.org/users/JohnZSmith>;
o:asset
- <assetContainer/a1>,
- <assetContainer/a2>;
+ <assets/a1>,
+ <assets/a2>;
o:liability
- <liabilityContainer/l1>,
- <liabilityContainer/l2>,
- <liabilityContainer/l3>.
+ <liabilities/l1>,
+ <liabilities/l2>,
+ <liabilities/l3>.
</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 <http://example.org/netWorth/nw1/>.
@@ -1000,18 +1022,30 @@
a o:NetWorth;
o:netWorthOf <http://example.org/users/JohnZSmith>;
o:asset
- <assetContainer/a1>,
- <assetContainer/a2>;
+ <assets/a1>,
+ <assets/a2>;
o:liability
- <liabilityContainer/l1>,
- <liabilityContainer/l2>,
- <liabilityContainer/l3>.
+ <liabilities/l1>,
+ <liabilities/l2>,
+ <liabilities/l3>.
</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 <http://example.org/netWorth/nw1/assetContainer/>.
+# @base <http://example.org/netWorth/nw1/assets/>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix o: <http://example.org/ontology/>.
@@ -1023,10 +1057,23 @@
ldp:contains <a1>, <a2>.
</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 <http://example.org/netWorth/nw1/liabilityContainer/>.
+# @base <http://example.org/netWorth/nw1/liabilities/>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix o: <http://example.org/ontology/>.
@@ -1038,34 +1085,25 @@
ldp:contains <l1>, <l2>, <l3>.
</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>(<>, 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 <http://example.org/netWorth/nw1/assetContainer/>.
+ # @base <http://example.org/netWorth/nw1/assets/>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix o: <http://example.org/ontology/>.
@@ -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 <http://example.org/netWorth/nw1/assetContainer/>.
+ # @base <http://example.org/netWorth/nw1/assets/>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix o: <http://example.org/ontology/>.
@@ -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 <http://example.org/netWorth/nw1/assetContainer/>.
+ # @base <http://example.org/netWorth/nw1/assets/>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix o: <http://example.org/ontology/>.
@@ -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 <http://example.org/netWorth/nw1/assetContainer/>.
+ # @base <http://example.org/netWorth/nw1/assets/>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix o: <http://example.org/ontology/>.
@@ -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>