Issue-64 change ?non-member-properties into Link header with extension relation type
authorJohn Arwe
Fri, 07 Jun 2013 13:31:26 -0400
changeset 120 edf269bcce8a
parent 119 28a06040491c
child 121 4d4f2bc76575
child 122 14197f56039e
Issue-64 change ?non-member-properties into Link header with extension relation type
ldp.html
ldp.ttl
--- a/ldp.html	Tue Jun 04 19:10:09 2013 +0200
+++ b/ldp.html	Fri Jun 07 13:31:26 2013 -0400
@@ -16,7 +16,6 @@
           
           // the specification's short name, as in http://www.w3.org/TR/short-name/
           shortName:            "ldp",
-          // TODO: Confirm short name
 
           // if your specification has a subtitle that goes below the main
           // formal title, define it here
@@ -104,9 +103,12 @@
     <style type="text/css" media="all">
     	code {
     	    font-weight:bold;
+			font-size:larger;
     	}
 		 /* ReSpec uses color ff4500 for code elements, which does not print well on some black & white printers
-		    and is a little hard to read for some folks even on-line. */
+		    and is a little hard to read for some folks even on-line. 
+			The default code font size was also somewhat too small/hard to read.
+		*/
     </style>
   </head>
 <body>
@@ -193,19 +195,26 @@
 		or tunnel, switching behavior based on the nature of each request
 		[[HTTP11]]. </p></dd>
 
-	<dt>Membership triples</dt>
+	<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 define
 		the container's members. 
 	<p></p></dd>
 	
-	<dt>Membership subject</dt>
-	<dd>The subject of all an LDPC's <a title="Membership triples">membership triples</a>.
+	<dt><dfn>Membership subject</dfn></dt>
+	<dd>The subject of all a LDPC's <a title="Membership triples">membership triples</a>.
 	<p></p></dd>
 	
-	<dt>Membership predicate</dt>
-	<dd>The predicate of all an LDPC's <a title="Membership triples">membership triples</a>.
+	<dt><dfn>Membership predicate</dfn></dt>
+	<dd>The predicate of all a LDPC's <a title="Membership triples">membership triples</a>.
+	<p></p></dd>
+	
+	<dt><dfn>Non-member resource</dfn></dt>
+	<dd>A resource associated with a LDPC by a server for the purpose of enabling clients to
+	retrieve a subset of the LDPC's state, namely the subset that omits the LDPC's membership triples.
+	In other words, the union of the non-member resource's state and the LDPC's membership triples
+	exactly equals the LDPC's state.
 	<p></p></dd>
   </dl>
 
@@ -240,7 +249,7 @@
 
 <p>A conforming <b>LDP Server</b> is an application program that processes HTTP 
 requests and generates HTTP responses that conform to the rules defined in sections on <a href="#linked-data-platform-resources">LDPRs</a>
-and <a href="#linked-data-platform-containers">LDPCs</a></p>
+and <a href="#linked-data-platform-containers">LDPCs</a></p>.
 
 <div class="ldp-issue">
 	<div class="ldp-issue-title"><a href="http://www.w3.org/2012/ldp/track/issues/57">ISSUE-57</a></div>
@@ -249,7 +258,7 @@
 
 <p>A conforming <b>LDP Client</b> is an application program that generates HTTP 
 requests and processes HTTP responses that conform to the rules defined in sections on <a href="#linked-data-platform-resources">LDPRs</a>
-and <a href="#linked-data-platform-containers">LDPCs</a></p>
+and <a href="#linked-data-platform-containers">LDPCs</a></p>.
 
 </section>
 
@@ -735,7 +744,7 @@
 		get this information may be onerous for clients and cause unnecessary
 		overhead on servers, it is desired to define a way to retrieve only
 		the non-member property values. Defining for each LDPC a corresponding
-		resource, called the “non-member resource”, whose state is a subset
+		resource, called the “<a>non-member resource</a>”, whose state is a subset
 		of the state of the container, does this.</p>
 	<p>The example listed here only show
 		a simple case where only a few simple non-member properties are
@@ -744,8 +753,9 @@
 		associating SPARQL endpoints. [[SPARQL-QUERY]]</p>
 	<p>
 		Here is an example requesting the non-member properties of a
-		container identified by the URL <code>http://example.org/container1/</code>
-		and adding the query string <code>?non-member-properties</code> :
+		container identified by the URL <code>http://example.org/container1/</code>.
+		In this case, the non-member resource is identified by the URL 
+		<code>http://example.org/container1?non-member-properties</code>:
 	</p>
 <p>Request:</p>
 <pre class="example">GET /container1?non-member-properties HTTP/1.1
@@ -767,6 +777,10 @@
    dcterms:title "A Linked Data Platform Container of Acme Resources";
    ldp:membershipPredicate rdfs:member;
    dcterms:publisher &lt;http://acme.com/&gt;.</pre>
+   
+	<p>While the same non-member resource could be used to update the non-member properties via PUT,
+		LDP recommends using PATCH for this purpose.</p>
+
 
 	<div id="ldpc-paging" class="rule">5.1.3 Paging</div>
 	<em>This section is non-normative</em>
@@ -1036,28 +1050,16 @@
 
 <section>	
 <h2 id="ldpc-HTTP_GET">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
 		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 LDPC servers SHOULD support requests for information about a known LDPC
-		without retrieving a full representation including all of its
-		members, by the existence of the token "<code>non-member-properties</code>" on the query
-		component of the LDPC URL.  For example, if there is a LDPC URL <code>&lt;containerURL&gt;,</code> the URL to request the
-		non-membership properties would be <code>&lt;containerURL&gt;?non-member-properties</code>.
-		See section <a href="#ldpc-get_non-member_props">5.1.2 Retrieving Only Non-member Properties</a> for
-		examples. An LDPC server that does not support a request to
-		retrieve non-member resource properties via a Request-URI of “<code>&lt;containerURL&gt;?non-member-properties</code>”,
-		MUST return a HTTP status code 404 (Not Found).  An LDPC server that supports a request to
-		retrieve non-member resource properties via a different Request-URI than “<code>&lt;containerURL&gt;?non-member-properties</code>”,
-		MUST return a HTTP Redirection 3xx status code such as 301 (Moved Permanently) or 302 (Found).
-	</div>
-	
-	<div class="ldp-issue">
-	<div class="ldp-issue-title"><a href="http://www.w3.org/2012/ldp/track/issues/64">ISSUE-64</a></div>
-	Non-member-properties and Hypermedia as the Engine of Application State (HATEOAS) Compliance
+
+	<div id="ldpc-5_3_2" class="rule">5.3.2  Empty after resolution of Issue-64,
+		left here for now to avoid renumbering all that follows.  Content moved to <a href="#ldpc-HTTP_HEAD">LDPC HEAD</a>.
 	</div>
 	
 	<div id="ldpc-5_3_3" class="rule">5.3.3 Empty after resolution of Issue-65, 
@@ -1080,7 +1082,7 @@
 		header is present, then conservative clients will assume that the LDPC does not support paging.
 		For example, if there is a LDPC with URL <code>&lt;containerURL&gt;</code> that supports paging and whose
 		first page URL is <code>&lt;containerURL&gt;?theFirstPage</code>, then the corresponding link header
-		would be <code>Link: &lt;?theFirstPage&gt;;rel="first"</code>
+		would be <code>Link: &lt;?theFirstPage&gt;;rel="first"</code>.
 		The representation for any page, including the first, will include
 		the URL for the next page. See section <a href="#ldpc-paging">5.1.3 Paging</a> for additional details.
 	</div>
@@ -1212,7 +1214,7 @@
 	
 	<div id="ldpc-5_4_11" class="rule">5.4.11 LDPC servers that allow member creation via POST 
 		SHOULD NOT re-use URIs, per the<a href="#ldpc-5_2_9">
-		general requirements on LDPCs<a>.
+		general requirements on LDPCs</a>.
 	</div>
 	
 </section>
@@ -1233,9 +1235,12 @@
 		(Conflict) status code.
 	</div>
 	<div id="ldpc-5_5_2" class="rule">5.5.2 LDPC servers MAY allow updating LDPC non-membership properties using
-		HTTP PUT on <code>&lt;containerURL&gt;?non-member-properties</code>, which
+		HTTP PUT on a corresponding <a>non-member resource</a>, which
 		MAY exclude server-managed properties such as <code>ldp:membershipSubject</code>, <code>ldp:membershipPredicate</code>
 		and <code>ldp:membershipPredicateInverse</code>.
+		Section <a href="#ldpc-5_7_1">5.7.1 HTTP HEAD</a> describes the process by which clients
+		discover whether the server offers such a resource, and if so its URL. 
+
 	</div>
 	    
     <div id="ldpc-5_5_3" class="rule">5.5.3 LDPC servers SHOULD NOT allow HTTP PUT requests
@@ -1246,7 +1251,7 @@
 	
 	<div id="ldpc-5_5_4" class="rule">5.5.4 LDPC servers that allow member creation via PUT 
 		SHOULD NOT re-use URIs, per the <a href="#ldpc-5_2_9">
-		general requirements on LDPCs<a>.
+		general requirements on LDPCs</a>.
 	</div>
 	
 </section>
@@ -1272,12 +1277,33 @@
 
 <section>
 <h2 id="ldpc-HTTP_HEAD">HTTP HEAD</h2>
-	<p>There are no additional requirements on HTTP
-		HEAD.</p>
+
 	<p>Note that certain LDP mechanisms, such as paging, rely on HTTP headers, and HTTP generally requires that
 		HEAD responses include the same headers as GET responses.  
 		Thus, implementers supporting HEAD should also carefully read the
 		<a href="#ldpc-HTTP_GET">GET section</a>.</p>
+
+	<div id="ldpc-5_7_1" class="rule">5.7.1  
+		LDPC servers SHOULD define a corresponding
+		<a>non-member resource</a>
+		to support requests for information about a LDPC
+		without retrieving a full representation including all of its members; 
+		see section <a href="#ldpc-get_non-member_props">5.1.2 Retrieving Only Non-member Properties</a> for
+		examples. 
+		In responses to <code>GET</code> requests with an LDPC as the Request-URI, 
+		LDPC servers that define a non-member resource SHOULD provide an HTTP <code>Link</code>
+		header whose target URI is the <a>non-member resource</a>, and whose link relation type is 
+		<code>http://www.w3.org/ns/ldp#non-member-resource</code> [[!RFC5988]]. 
+		This is the mechanism by which clients discover the URL of the non-member resource.  
+		If no such <code>Link</code>
+		header is present, then conservative clients will assume that the LDPC does not have a corresponding
+		non-member resource.
+		For example, if there is a LDPC with URL <code>&lt;containerURL&gt;</code> whose corresponding
+		non-member resource 
+		URL is <code>&lt;containerURL&gt;?nonMemberProperties</code>, then the corresponding link header
+		would be <code>Link: &lt;?nonMemberProperties&gt;;rel="http://www.w3.org/ns/ldp#non-member-resource"</code>
+	</div>
+	
 </section>
 
 <section>
@@ -1314,6 +1340,7 @@
 </p>
 <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130307/">Second Public Working Draft</a></em></blockquote>
 <ul>
+	<li>2013-06-05 - ISSUE-64 Remove ?non-member-properties; 5.1.2, 5.3.2, 5.5.2 (JA)</li>
 	<li>2013-05-21 - ISSUE-35 Re-use of URIs on create; 5.2.9, 5.4.11, 5.5.4 (JA)</li>
 	<li>2013-05-21 - ISSUE-43 Slug in LDPC POSTs; 5.4.8, 5.4.10 (JA)</li>
 	<li>2013-05-21 - ISSUE-65 Remove firstPage in favor of Link rel=first, mostly hits 5.3.3/5.3.4 (JA)</li>
--- a/ldp.ttl	Tue Jun 04 19:10:09 2013 +0200
+++ b/ldp.ttl	Fri Jun 07 13:31:26 2013 -0400
@@ -94,4 +94,13 @@
 	rdfs:domain :Page;
 	rdfs:isDefinedBy :;
 	rdfs:label "pageOf";
-	rdfs:range :Container.
\ No newline at end of file
+	rdfs:range :Container.
+	
+:non-member-resource
+	a rdf:Resource;  # Not positive this is right.  Seems right to "flag" the URI in this doc, but not "really" defining RDF with it.  But anything defined here would be of type rdf:Resource anyway, so no harm in rendering that explicit.
+	rdfs:comment "Extension link relation type URI for use in HTTP Link header.  When a server offers clients the ability to retrieve non-member properties of an LDPC through an associated non-member resource, this Link header is how clients discover the existence of that resource and its URI.";
+	vs:term_status "unstable";
+	rdfs:isDefinedBy :;
+	rdfs:label "non-member-resource";
+	rdfs:domain ldp:Container;
+	rdfs:range ldp:Container.