ldp.html
changeset 373 0562f8c4d4d4
parent 372 d85ca5c8cb68
child 374 eeff2a51723d
--- a/ldp.html	Tue Oct 01 11:11:32 2013 -0400
+++ b/ldp.html	Tue Oct 01 14:50:16 2013 -0400
@@ -1,6 +1,9 @@
 <!DOCTYPE html>
 <!-- 
  Editor TODO:
+   - Once companion documents have URLs, link to them.  Search on "companion".
+   - Once the membership* names stabilize, take a pass through for "membership consistent value", membership-constant-URI
+     and see if there is a friendlier way to phrase it.
    - The word "canonical" is used twice in the document. Since we do not deal with URI 
      canonicalization in the specification, I would remove the word and the meaning of 
      the sentences is the same.
@@ -184,31 +187,37 @@
  
 <section class="informative" id="intro">
 <h1>Introduction</h1>
-	<p>This document describes the use
+	<p>This specification describes the use
 	of HTTP for accessing, updating, creating and deleting resources from
 	servers that expose their resources as Linked Data.  It provides clarifications
-	and extensions of the four rules of Linked Data [[LINKED-DATA]]:</p>
-	<p>1. Use URIs as names for things</p>
-	<p>2. Use HTTP URIs so that people can look up those
-		names</p>
-	<p>3. When someone looks up a URI, provide useful
-		information, using the standards (RDF*, <abbr title="SPARQL Protocol and RDF Query Language">SPARQL</abbr>)</p>
-	<p>4. Include links to other URIs, so that they can
-		discover more things</p>
-	<p>This specification discusses standard HTTP and RDF techniques and best practices that you 
-	should use, and anti-patterns you should avoid, when constructing clients and servers that 
-	read and write Linked Data resources.</p> 
-	<p>A special type of <a>Linked Data Platform Resource</a> is a 
-	<a>Container</a>.  Containers are very useful 
-	in building application models involving collections of homogeneous resources.  For example, universities offer a collection of classes 
-	and have a collection of faculty members, each faculty member teaches a collection of courses, etc.  
-	This specification discusses how to work with containers.  Resources can be added to containers in 
-	several ways. As a special case, members can both be created and added to a container by overloading 
-	the POST operation (see <a href="#ldpc-HTTP_POST" class="sectionRef"></a>).</p>
-	<p>Another contribution of this specification is how to deal with large amounts of data.  
-	Depending on the server’s capabilities, a GET request on a Linked Data Platform Resource 
-	returns a set of pages and uses a convention to access any subsequent page (see <a href="#ldpr-Paging" class="sectionRef"></a>). </p>
-	<p>The intention of this document is to enable additional rules and layered groupings of rules as 
+	and extensions of the rules of Linked Data [[LINKED-DATA]]:</p>
+	<ol>
+		<li>Use URIs as names for things</li>
+		<li>Use HTTP URIs so that people can look up those names</li>
+		<li>When someone looks up a URI, provide useful information, using the standards
+			(RDF*, <abbr title="SPARQL Protocol and RDF Query Language">SPARQL</abbr>)
+		</li>
+		<li>Include links to other URIs, so that they can discover more things</li>
+	</ol>
+	<p>This specification discusses standard HTTP and RDF techniques that you 
+	should use when constructing clients and servers that 
+	read and write <a title="Linked Data Platform Resource">Linked Data Platform Resources</a>.
+	A companion document discusses best practices that you 
+	should use, and anti-patterns you should avoid, when constructing these clients and servers.
+	</p> 
+	<p>This specification also provides a widely re-usable pattern to deal with large RDF resources.  
+	Depending on the server’s capabilities, a GET request on a <a>Linked Data Platform Resource</a> can
+	return a subset of the resource (one page), that provides access to subsequent pages 
+	(see <a href="#ldpr-Paging" class="sectionRef"></a>). </p>
+	<p>This specification defines a special type of <a>Linked Data Platform Resource</a>: a 
+	<a title="Linked Data Platform Container">Container</a>.  Containers are very useful 
+	in building application models involving collections of resources, often homogeneous ones. 
+	For example, universities offer a collection of classes 
+	and have a collection of faculty members, each faculty member teaches a collection of courses, and so on. 
+	This specification discusses how to work with containers.  Resources can be added to containers  
+	using standard HTTP operations like 
+	POST (see <a href="#ldpc-HTTP_POST" class="sectionRef"></a>).</p>
+	<p>The intention of this specification is to enable additional rules and layered groupings of rules as 
 	additional specifications.  The scope is intentionally narrow to provide a set of key rules for 
 	reading and writing Linked Data that most, if not all, other specifications will depend upon and 
 	implementations will support.</p>
@@ -254,13 +263,29 @@
 
 	<dt><dfn>Membership triples</dfn></dt>
 	<dd>A set of triples in an LDPC's state that lists its members.
-		The membership triples of a container all have the same
-		subject and predicate, and the objects of the membership triples identify
-		the container's members. 
-	<p></p></dd>
-	
-	<dt><dfn>Membership subject</dfn></dt>
-	<dd>The subject of all a LDPC's <a title="Membership triples">membership triples</a>.
+		A container's membership triples all have one of the following patterns:
+		<table style="margin-left: +3em">
+		<tr>
+		<td style="padding:0 0 0 +2ex"> <var style="background:#DDDDDD">membership-constant-URI</var> </td>
+		<td style="padding:0 0 0 +2ex"> <var>membership-predicate</var> </td>
+		<td style="padding:0 0 0 +2ex"> <var style="background:#CCFFFF">member-URI</var> </td>
+		</tr>
+		<tr>
+		<td style="padding:0 0 0 +2ex"> <var style="background:#CCFFFF">member-URI</var> </td>
+		<td style="padding:0 0 0 +2ex"> <var>membership-predicate</var> </td>
+		<td style="padding:0 0 0 +2ex"> <var style="background:#DDDDDD">membership-constant-URI</var> </td>
+		</tr>
+		</table>
+		The difference between the two is simply which position member-URI occupies, which is usually
+		driven by the choice of <var>membership-predicate</var>.  Most predicates have a natural forward direction
+		inherent in their name, and existing vocabularies contain useful examples that read naturally in
+		each direction.  <code>rdfs:member</code> and <code>dcterms:isPartOf</code> are representative examples.
+		<p>
+		Each container exposes properties that allow clients to determine which pattern it
+		uses, what the actual <var>membership-predicate</var> and <var>membership-constant-URI</var> values are, 
+		and (for containers that allow the creation of new members) what value is used
+		for the <var>member-URI</var> based on the client's input to the 
+		creation process.</p>
 	<p></p></dd>
 	
 	<dt><dfn>Membership predicate</dfn></dt>
@@ -268,8 +293,8 @@
 	<p></p></dd>
 	
 	<dt><dfn>Page resource</dfn></dt>
-	<dd>A type of LDPR that is associated to another LDPR and whose representation 
-	includes a subset of the triples in the associated LDPR.
+	<dd>A type of LDPR that is associated with another LDPR <var>R</var>, whose representation 
+	includes a subset of the triples in <var>R</var>.
 	<p></p></dd>
 	
 	<dt><dfn>Non-member resource</dfn></dt>
@@ -297,6 +322,7 @@
     
 <section id='conformance'>
 
+<p>LDP uses the term <b><dfn>informative</dfn></b> as a synonym for non-normative.</p>
 <p>The status of the sections of Linked Data Platform 1.0 (this document) is as follows:</p>
 <ul>
   <li>1. Introduction: <b>informative</b></li>
@@ -424,10 +450,10 @@
 		<li>What literal value types should be used?</li>
 		<li>Are there some typical vocabularies that should be reused?</li>
 	</ul>
-	<p>The following sections define the rules and
-		guidelines for use of LDPRs. This document also explains how to include
-		information about each member in the resource’s own representation
-		and how to paginate the resource representation if it gets too big.</p>
+	<p>The following sections define the conformance rules for LDP servers when serving LDPRs.
+		This document also explains how to paginate an LDPR's representation if it gets too big.
+		Companion documents describe additional guidelines for use when interacting with LDPRs. 
+	</p>
 
 </section>
 
@@ -864,12 +890,15 @@
 		This document defines the representation and behavior of containers
 		that address these issues. The set of members of a container is
 		defined by a set of triples in its representation (and state) called
-		the membership triples. The membership triples of a container all
-		have the same subject and predicate – the objects of the membership
-		triples define the members of the container. The subject of the
-		membership triples is called the membership subject and the predicate
-		is called the membership predicate. In the simplest cases, the
-		membership subject will be the LDPC resource itself, but it does not
+		the <a title="Membership triples">membership triples</a> that follow a consistent pattern
+		(see the linked-to definition for the possible patterns). 
+		The membership triples of a container all
+		have the same predicate, called the membership predicate, 
+		and either the subject or the object is also a consistent value
+		– the remaining position of the membership
+		triples (the one that varies) define the members of the container. 
+		In the simplest cases, the
+		consistent value will be the LDPC resource's URI, but it does not
 		have to be. The membership predicate is also variable and will often
 		be a predicate from the server application vocabulary or the <code>rdfs:member</code> predicate.
 	</p>
@@ -902,13 +931,15 @@
    rdfs:member &lt;member1&gt;, &lt;member2&gt;, &lt;member3&gt;.</pre>
 
 	<p>This example is very straightforward - the
-			membership predicate is <code>rdfs:member</code> and the membership subject is the container
-			itself. A POST to this container will create a new resource
+			membership predicate is <code>rdfs:member</code> and the other
+			consistent membership value is the container's
+			URI, occurring in the subject position of the triples. 
+			A POST to this container will create a new resource
 			and add it to the list of members by adding a new membership triple
 			to the container.</p>
 
 	<p>Sometimes it is useful to use a subject
-	other than the container itself as the membership subject and to use
+	other than the container itself as the consistent membership value, and/or to use
 	a predicate other than <code>rdfs:member</code> as the membership predicate. Let's
 	start with a domain resource for a person's net worth, as illustrated below:</p>
 			
@@ -971,7 +1002,7 @@
 </pre>
 
 	<p>The essential structure of the container is
-	the same, but in this example, the membership subject is not the
+	the same, but in this example, the consistent membership value (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
@@ -1003,9 +1034,8 @@
    a o:NetWorth;
    o:asset &lt;a1&gt;, &lt;a2&gt;.</pre>
 
-	<p>In this example, clients cannot simply guess
-			which resource is the membership subject and which predicate is the
-			membership predicate, so the example includes this information in
+	<p>In this example, clients cannot correctly guess
+			at the membership triples, so the example includes this information in
 			triples whose subject is the LDPC resource itself.
 	</p>
 	
@@ -1195,27 +1225,33 @@
 	<p>The Linked Data Platform does not define how clients
 		discover <dfn><abbr title="Linked Data Platform Containers">LDPCs</abbr></dfn>.</p>
 
-	<div id="ldpc-5_2_1" class="rule">5.2.1 <a title="LDP server">LDP servers</a> MUST also be conformant <a title="LDP server">LDP servers</a>. A Linked Data Platform
-		Container MUST also be a conformant Linked Data Platform Resource.
+	<div id="ldpc-5_2_1" class="rule">5.2.1 
+		Each Linked Data Platform Container MUST also be a conforming Linked Data Platform Resource.
 	</div>
 	<div id="ldpc-5_2_2" class="rule">5.2.2 LDPC membership is not exclusive; this means that the same resource
-	(LDPR or not) which is identified by its canonical URI, MAY be a member of 
-	more than one LDPC.
+	(LDPR or not) MAY be a member of more than one LDPC.
 	</div>
-	<div id="ldpc-5_2_3" class="rule">5.2.3 The state of an LDPC includes information about which
-		resources are its members. In the simplest cases, the membership subject
-		will be the LDPC resource itself, but it does not have to be. The
-		membership predicate is also variable and will often be a predicate
-		from the server application vocabulary. If there is no obvious
-		predicate from the server application vocabulary to use, <a title="LDP server">LDP servers</a>
-		SHOULD use the <code>rdfs:member</code> predicate. Member resources can be
-		any kind of resource identified by its URI, LDPR or otherwise.
+	<div id="ldpc-5_2_3" class="rule">5.2.3 <a title="LDP server">LDP servers</a>
+		SHOULD use the <code>rdfs:member</code> predicate
+		If there is no obvious predicate from an application vocabulary to use.
+		The state of an LDPC includes information about which
+		resources are its members, in the form of <a title="Membership triples">membership triples</a> that
+		follow a consistent pattern.  The LDPC's state contains enough information for clients to discern
+		the <a title="Membership predicate">membership predicate</a>, the other consistent membership
+		value used in the container's membership triples, and the position (subject or object) where the member's URI
+		occurs in those triples.
+		Member resources can be
+		any kind of resource identified by a URI, LDPR or otherwise.
 	</div>
 	<div id="ldpc-5_2_4" class="rule">5.2.4 An LDPC representation MUST contain exactly one triple 
 		whose subject is the LDPC URI, 
 		whose predicate is the <code>ldp:membershipSubject</code>, 
 		and whose object is the LDPC's membership subject URI.
 	</div>
+<div class="ldp-issue-open">
+<div class="ldp-issue-title">Issue-81: confusing predicate names</div>
+"membership subject" has been removed too.  Remove this use of it as part of Issue-81 resolution.
+</div>
 	<div id="ldpc-5_2_5" class="rule">5.2.5 An LDPC representation MUST contain exactly one triple 
 		whose subject is the LDPC URI, 
 		and whose predicate is either <code>ldp:membershipPredicate</code> or <code>ldp:membershipPredicateInverse</code>. 
@@ -1262,16 +1298,22 @@
 		While it is difficult to provide absolute implementation guarantees of non-reuse in all failure
 		scenarios, re-using URIs creates ambiguities for clients that are best avoided.
 	</div>
-	<div id="ldpc-5_2_10" class="rule">5.2.10 Some LDPCs have membership objects that are not directly
-	    URIs minted upon LDPC member creation, for example URIs with non-empty fragment identifier [[RFC3986]]. 
-	    To determine which object URI to use for the  membership triple, LDPCs MUST contain one triple whose
-	    subject is the LDPC URI, predicate is <code>ldp:membershipObject</code>, with an object <var>MO</var>. 
-	    Where <var>MO</var> and the HTTP URI <var>R</var> from <code>POST</code> create (as found in HTTP response <code>Location</code> header) can be 
-	    used to locate a triple of the form: <var>(R, MO, N)</var> and 
-	    where <var>N</var> can be used to construct the membership triple of the form: <var>(membership subject, membership predicate, N)</var>.
-	    When <code>ldp:membershipPredicateInverse</code> is used instead of <code>ldp:membershipPredicate</code>, the membership triple MUST be
-	    of the form: <var>(N, membership predicate, membership subject)</var>. To indicate that the member resource URI is the membership object
-	    (the default or typical case), the object MUST be set to predefined URI <code>ldp:MemberSubject</code> such that it forms the triple: 
+	<div id="ldpc-5_2_10" class="rule">5.2.10 Some LDPCs have members whose URIs are not directly
+	    URIs minted upon LDPC member creation, for example URIs with a non-empty fragment identifier [[RFC3986]]. 
+	    To determine which member URI to use in the  membership triple, LDPCs MUST contain one triple whose
+	    subject is the LDPC URI, whose predicate is <code>ldp:membershipObject</code>, and whose object is <var>MO</var>. 
+	    <var>MO</var> and the HTTP URI <var>R</var> from <code>POST</code> create 
+		(as found in HTTP response <code>Location</code> header) are 
+	    used to locate a triple in <var>R</var> of the form <var>(R, MO, N)</var>.
+		When the LDPC uses <code>ldp:membershipPredicate</code>, 
+	    <var>N</var> is then used to construct the membership triple of the form: 
+		<var>(membership consistent value, membership predicate, N)</var>.
+	    When the LDPC uses <code>ldp:membershipPredicateInverse</code>,
+		the membership triple is
+	    of the form: <var>(N, membership predicate, membership consistent value)</var>. 
+		To indicate that the member resource URI is the membership object
+	    (the default or typical case), the object MUST be set to predefined URI <code>ldp:MemberSubject</code> 
+		such that it forms the triple: 
 	    <var>(LDPC URI, <code>ldp:membershipObject</code>, <code>ldp:MemberSubject</code>)</var>.
 	</div>
 	
@@ -1306,13 +1348,15 @@
 <section id="ldpc-HTTP_GET">	
 <h2>HTTP GET</h2>
 
-	<div id="ldpc-5_3_1" class="rule">5.3.1 The representation of a LDPC MUST contain a set of triples with a
-		consistent subject and predicate whose objects indicate members of
-		the container. The subject of the triples MAY be the container itself
+	<div id="ldpc-5_3_1" class="rule">5.3.1 The representation of a LDPC MUST contain a set of 
+		<a href="Membership triples">membership triples</a> following one of the consistent 
+		patterns from that definition.
+		The membership-constant-URI of the triples MAY be the container itself
 		or MAY be another resource (as in the <a href="#ldpc-ex-membership-subj">example</a>).  See also
 		<a href="#ldpc-5_2_3">5.2.3</a>.
 	</div>
-	<div id="ldpc-5_3_2" class="rule">5.3.2 <a title="LDP server">LDP servers</a> MAY represent the members of a paged LDPC in a sequential
+	<div id="ldpc-5_3_2" class="rule">5.3.2 <a title="LDP server">LDP servers</a> MAY 
+		represent the members of a paged LDPC in a sequential
 		order.  If the server does so, it MUST be specify the order using a triple 
 		whose subject is the page URI, 
 		whose predicate is <code>ldp:containerSortCriteria</code>, 
@@ -1423,7 +1467,7 @@
 		triples in the created resource whose subject is the created
 		resource.  
 	</div>	
-	<div id="ldpc-5_4_8" class="rule">5.4.8 <a title="LDP server">LDP servers</a> SHOULD assign the subject URI for the resource to be
+	<div id="ldpc-5_4_8" class="rule">5.4.8 <a title="LDP server">LDP servers</a> SHOULD assign the 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>.
 	</div>
 	<div id="ldpc-5_4_9" class="rule">5.4.9 <a title="LDP server">LDP servers</a> SHOULD allow clients to create new resources without
@@ -1714,6 +1758,8 @@
 
 <!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130930/">Candidate Recommendation Draft</a></em></blockquote>  -->
 <ul>
+    <li>2013-10-01 - Revising terminology - membership triples and friends (JA)</li>
+    <li>2013-10-01 - Revising introduction (JA)</li>
     <li>2013-10-01 - Conformance section drafting (JA)</li>
     <li>2013-09-23 - Remove client/server-initiated paging terms (JA)</li>
     <li>2013-09-17 - Change must to MUST in <a href="#ldpc-5_6_4">5.6.4</a> (SS)</li>