--- a/ldp.html Sat Feb 08 13:11:14 2014 -0500
+++ b/ldp.html Sat Feb 08 14:43:27 2014 -0500
@@ -374,11 +374,12 @@
These triples <strong>always</strong> have the form: <var>( LDPC URI, ldp:contains , document-URI )</var>.
<p></p></dd>
- <dt><dfn>Non-member resource</dfn></dt>
- <dd>A HTTP 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.
+ <dt><dfn>Empty-container triples</dfn></dt>
+ <dd>
+ The portion of an LDPC's state that would be present when the container is empty. Currently, this definition
+ is equivalent to all the LDPC's triples minus its containment triples and minus its membership
+ triples, but if future versions of LDP define additional classes of triples then this definition
+ would expand to subtract out those classes as well.
<p></p></dd>
<dt><dfn>Paged resource</dfn></dt>
@@ -1367,35 +1368,41 @@
</td></tr>
<tr><td>LDPC is deleted</td><td>Triples and member resources may be removed</td><td>Triples of form
(LDPC, ldp:contains, LDPR) and contained LDPRs are removed</td></tr>
-
+<!-- TODO: "and contained LDPRs are removed" implies cascading delete to me, ensure matches rest of content -->
</table>
</div>
- <section id="ldpc-get_non-member_props"><h2 class="normal">Retrieving Only Non-member Properties
- </h2><!-- Was 5.1.1 / #ldpc-get_non-member_props -->
+ <section id="ldpc-get_empty-container_props"><h2 class="normal">Retrieving Only Empty-Container Triples
+ </h2><!-- Was 5.1.1 / #ldpc-get_empty-container_props -->
<p>The representation of a container
that has many members will be large. There are several important
- cases where clients need to access only the non-member properties of
- the container. Since retrieving the whole container representation to
+ cases where clients need to access only the subset of the container's properties
+ that are unrelated to member resources and unrelated to contained documents, for
+ example to determine the membership triple pattern and membership predicate of a
+ LDP-DC. LDP calls these <a title="Empty-container triples">empty-container triples</a>,
+ because they are what remains when the container has zero members and zero contained resources.
+ Since retrieving the whole container representation to
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 “<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
+ overhead on servers, we define a way to retrieve only
+ these property values (and more generally, a way to retrieve only the
+ subset of properties used to address other major clusters of use cases).
+ LDP adds parameters to the HTTP <code>Prefer</code> header's
+ <code>return=representation</code> preference for this
+ (see <a href="#prefer-parameters" class="sectionRef"></a> for details).
+ </p>
+ <p>The example listed here only shows
+ a simple case where few empty-container triples are
retrieved. In real world situations more complex cases are likely, such as those that add other predicates to
containers, for example providing validation information and
associating SPARQL endpoints. [[SPARQL-QUERY]]</p>
<p>
- Here is an example requesting the non-member properties of a
+ Here is an example requesting the empty-container triples of a
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 id="ldpc-ex-non-member">Request:</p>
-<pre class="example">GET /container1?non-member-properties HTTP/1.1
+<p id="ldpc-ex-empty-container">Request:</p>
+<pre class="example">GET /container1 HTTP/1.1
Host: example.org
Accept: text/turtle; charset=UTF-8
+Prefer: return=representation; include="http://www.w3.org/ns/ldp#PreferEmptyContainer"
</pre>
<p>Response:</p>
<pre class="example">HTTP/1.1 200 OK
@@ -1403,6 +1410,7 @@
ETag: "_87e52ce291112"
Content-Length: 325
Link: <http://www.w3.org/ns/ldp/Container>; rel="type"
+Preference-Applied: return=representation
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@@ -1415,10 +1423,12 @@
ldp:insertedContentRelation ldp:MemberSubject;
dcterms:publisher <http://acme.com/>.</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>
+ <p>
+ LDP recommends using PATCH to update these properties, if necessary. It provides no facility
+ for updating them via PUT without replacing the entire container's state.
+ </p>
- </section><!-- ldpc-get_non-member_props -->
+ </section><!-- ldpc-get_empty-container_props -->
<section id="ldpc-ordering"><h2 class="normal">Ordering</h2>
<p>
@@ -1532,7 +1542,7 @@
might have additional types</a>, like any RDF resource.
</h2></section><!-- Was 5.2.7 / #ldpc-5_2_7 -->
- <!-- TODO: For LDP-BC, are the non-member props still needed or infered? -->
+ <!-- TODO: For LDP-BC, are the empty-container props still needed or infered? -->
<section id="ldpc-nordfcontainertypes"><h2 class="normal">LDPC representations SHOULD NOT use RDF container types <code>rdf:Bag</code>,
<code>rdf:Seq</code> or <code>rdf:List</code>.
@@ -1920,14 +1930,6 @@
(Conflict) status code.
</h2></section><!-- Was 5.5.1 / #ldpc-5_5_1 -->
- <section id="ldpc-put-nonmbrprops"><h2 class="normal"><a title="LDP server">LDP servers</a> MAY allow updating LDPC non-membership properties using
- HTTP <code>PUT</code> on a corresponding <a>non-member resource</a>, which
- MAY exclude server-managed properties such as <code>ldp:containerResource</code>, <code>ldp:containsRelation</code>
- and <code>ldp:containedByRelation</code>.
- The <a href="#ldpc-HTTP_OPTIONS" class="sectionRef"></a> describes the process by which clients
- use HTTP <code>OPTIONS</code> to discover whether the server offers such a resource, and if so its URL.
- </h2></section><!-- Was 5.5.2 / #ldpc-5_5_2 -->
-
<section id="ldpc-put-create"><h2 class="normal"><a title="LDP server">LDP servers</a> that allow member creation via <code>PUT</code>
SHOULD NOT re-use URIs. For RDF representations (LDP-RRs),the created resource
can be thought of as a RDF <a href="http://www.w3.org/TR/rdf11-concepts/#dfn-named-graph">named graph</a> [[rdf11-concepts]].
@@ -1995,8 +1997,10 @@
<a href="#ldpr-gen-pubclireqs">must be advertised</a> to clients.
</p>
- <section id="ldpc-patch-req"><h2 class="normal"><a title="LDP server">LDP servers</a> are RECOMMENDED to support HTTP <code>PATCH</code> as the preferred
- method for updating LDPC non-membership properties.
+ <section id="ldpc-patch-req"><h2 class="normal">
+ <a title="LDP server">LDP servers</a> are RECOMMENDED
+ to support HTTP <code>PATCH</code> as the preferred method for
+ updating a LDPC's <a title="Empty-container triples">empty-container triples</a>.
</h2></section><!-- Was 5.8.1 / #ldpc-5_8_1 -->
</section>
@@ -2005,27 +2009,6 @@
<p>This specification imposes the following new requirements on HTTP <code>OPTIONS</code> for LDPCs.
</p>
- <section id="ldpc-options-nonmbrprops"><h2 class="normal">
- <a title="LDP server">LDP servers</a> 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" class="secitonRef"></a> for
- examples.</h2>
- In responses to <code>OPTIONS</code> requests with an LDPC as the <code>Request-URI</code>,
- <a title="LDP server">LDP servers</a> 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#nonMemberResource</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 clients will assume that the LDPC does not have a corresponding
- non-member resource.
- For example, if there is a LDPC with URL <code><containerURL></code> whose corresponding
- non-member resource
- URL is <code><containerURL>?nonMemberProperties</code>, then the corresponding link header
- would be <code>Link: <?nonMemberProperties>;rel='http://www.w3.org/ns/ldp#nonMemberResource'</code>
- </section><!-- Was 5.9.1 / #ldpc-5_9_1 -->
-
<section id="ldpc-options-linkmetahdr"><h2 class="normal">When a LDPC creates a <a title="Linked Data Platform Binary Resource">LDP-BR</a> member (for example, one whose
representation was HTTP <code>POST</code>ed to the LDPC and then referenced by a membership triple) it might create an associated <a title="Linked Data Platform RDF Resource">LDP-RR</a> to contain data about the
non-LDPR (see <a href="#ldpc-post-createbinlinkmetahdr">LDPC POST section</a>). For LDP-BRs that have this associated LDP-RR, an LDPC server MUST provide an HTTP <code>Link</code>
@@ -2255,7 +2238,7 @@
<p>
Non-normative note: [[!Prefer]] recommends that server implementers include a
- Preference-Applied response header when the client cannot otherwise determine the server's
+ <code>Preference-Applied</code> response header when the client cannot otherwise determine the server's
behavior with respect to honoring hints from the response content.
<a href="#prefer-examples">Examples</a> illustrates some cases where the header is unnecessary.
</p>
@@ -2320,20 +2303,17 @@
<!-- TODO: use css instead - be careful of the other tables -->
<table style="margin-left: +3em">
<tr style="background:#F2F2F2">
- <td style="padding:0 0 0 +2ex"> Containment triples </td>
+ <td style="padding:0 0 0 +2ex"> <a title="Containment triples">Containment triples </a></td>
<td style="padding:0 0 0 +2ex; white-space:nowrap"> <code>http://www.w3.org/ns/ldp#PreferContainment</code> </td>
</tr>
<tr>
- <td style="padding:0 0 0 +2ex"> Membership triples </td>
+ <td style="padding:0 0 0 +2ex"> <a title="Membership triples">Membership triples </a></td>
<td style="padding:0 0 0 +2ex; white-space:nowrap"> <code>http://www.w3.org/ns/ldp#PreferMembership</code> </td>
</tr>
<tr style="background:#F2F2F2">
- <td style="padding:0 0 0 +2ex"> All triples other than triples managed by an LDPC.
- Currently an LDPC manages only containment and membership triples, but in the future others
- might be added. This definition is written to automatically exclude those new classes of
- triples, as long as they are the responsibility of the LDPC to manage.
+ <td style="padding:0 0 0 +2ex"> <a title="Empty-container triples">Empty-container triples</a>
</td>
- <td style="padding:0 0 0 +2ex; white-space:nowrap"> <code>http://www.w3.org/ns/ldp#PreferUnmanaged</code> </td>
+ <td style="padding:0 0 0 +2ex; white-space:nowrap"> <code>http://www.w3.org/ns/ldp#PreferEmptyContainer</code> </td>
</tr>
</table>
<blockquote>
@@ -2351,14 +2331,14 @@
</section> <!-- Prefer specification -->
<section id="prefer-examples" class="informative">
<h3>Examples</h3>
-<!-- TODO: flesh out examples
+<!-- TODO: flesh out examples ? not sure how many we really need.
Ted's email http://lists.w3.org/Archives/Public/public-ldp-wg/2014Jan/0136.html had:
none, c only, m only, m+c, all
separate ex's for basic, in/direct, include, exclude?
ex for complete absence of hint?
-->
<p>
- If we assume a <a title="Linked Data Platform Direct Container">LDP Direct Container</a> like
+ If we assume a container like
the one below:
</p>
<pre class="example" id="prefer-examples-direct">
@@ -2392,11 +2372,46 @@
o:value 300000 .
</pre>
- <p id="prefer-examples-direct-non-member-only">
- A server that honors a
- <code>Prefer: return=representation; omit="http://www.w3.org/ns/ldp#PreferMembership http://www.w3.org/ns/ldp#PreferContainment"</code> hint would return the following in response to a <code>GET</code> request.
+ <p id="prefer-examples-direct-empty-container-only1">
Clients interested only in information about the container
- (for example, which membership predicate it uses) might use such a hint.
+ (for example, which membership predicate it uses) might use this hint on a <code>GET</code> request:
+ <code>Prefer: return=representation; include="http://www.w3.org/ns/ldp#PreferEmptyContainer"</code>
+ </p>
+ <p>
+ A server that honors this hint would return a following response containing the HTTP header
+ <code>Preference-Applied: return=representation</code>
+ and this representation:
+ </p>
+
+ <pre class="example">
+ # The following is the ordered representation of
+ # http://example.org/netWorth/nw1/assetContainer/
+ <!-- @base is here only so it's easier to paste into validators for checking -->
+ # @base <http://example.org/netWorth/nw1/assetContainer/>.
+ @prefix dcterms: <http://purl.org/dc/terms/>.
+ @prefix ldp: <http://www.w3.org/ns/ldp#>.
+ @prefix o: <http://example.org/ontology/>.
+
+ <>
+ a ldp:Container, ldp:DirectContainer;
+ dcterms:title "The assets of JohnZSmith";
+ ldp:containerResource <http://example.org/netWorth/nw1>;
+ ldp:containsRelation o:asset;
+ ldp:insertedContentRelation ldp:MemberSubject.
+ </pre>
+
+ <p id="prefer-examples-direct-empty-container-only2">
+ Clients interested only in information about the container
+ (same as before) might use this hint instead:
+ <code>Prefer: return=representation; omit="http://www.w3.org/ns/ldp#PreferMembership http://www.w3.org/ns/ldp#PreferContainment"</code>. Note: <strong>Treating the two as equivalent is not recommended.</strong> While today this
+ <code>omit</code> parameter value is equivalent to the preceding <code>include</code> parameter value,
+ they may not be equivalent in the future
+ due to the definition of <a title="Empty-container triples">empty-container triples</a>.
+ Clients should preferentially use the <code>include</code> parameter, as it more precisely communicates their needs.
+ </p>
+ <p>
+ A <strong>LDP 1.0</strong> server that honors this hint would return the following response. Servers
+ implementing later versions of LDP might return substantively different responses.
</p>
<pre class="example">
@@ -2417,15 +2432,26 @@
</pre>
<p id="prefer-examples-direct-membershiponly">
- A server that honors a
- <code>Prefer: return=representation; include="http://www.w3.org/ns/ldp#PreferMembership http://www.w3.org/ns/ldp#PreferUnmanaged"</code> hint would return (at least) the following in response to a <code>GET</code> request, and perhaps only this (it might
+ Clients interested only in information about the container
+ (for example, which membership predicate it uses) and its membership might use this hint on a <code>GET</code> request:
+ <code>Prefer: return=representation; include="http://www.w3.org/ns/ldp#PreferMembership http://www.w3.org/ns/ldp#PreferEmptyContainer"</code>
+ </p>
+ <p>
+ A server that honors this hint would return
+ (at least) the following response, and perhaps only this (it might
well omit containment triples if they are not specifically requested).
- Clients interested only in information about the container
- (for example, which membership predicate it uses) and its membership might use such a hint.
+ In cases like this example, where a client can detect from the content that its hints were honored
+ (the presence of the predicates <code>dcterms:title</code> and <code>o:asset</code> demonstrate this in the representation below),
+ there is no need for the server to include a <code>Preference-Applied</code> response header
+ in many common cases like a <code>200 (OK)</code> response. In other cases, like status code <code>303</code>,
+ the header would still be required for the client to know that the <code>303</code> response entity
+ is a representation of the resource identified by the <code>Location</code> URI
+ instead of a short hypertext note (one with a hyperlink to
+ the same URI reference provided in the <code>Location</code> header field [[HTTPbis]]).
</p>
<pre class="example">
- # The following is the ordered representation of
+ # The following is the representation of
# http://example.org/netWorth/nw1/assetContainer/
<!-- @base is here only so it's easier to paste into validators for checking -->
# @base <http://example.org/netWorth/nw1/assetContainer/>.
@@ -2560,6 +2586,7 @@
<!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130930/">Candidate Recommendation Draft</a></em></blockquote> wah -->
<!-- <blockquote><em><a href="http://www.w3.org/TR/2013/WD-ldp-20130730/">Last Call Draft</a></em></blockquote> -->
<ul>
+ <li>2014-02-08 - ACTION-132: Use Prefer in place of non-member properties resource (JA)</li>
<li>2014-02-08 - Add Prefer header examples, define new URIs from -126 in ttl, tweak acks per Arnaud email (JA)</li>
<li>2014-02-07 - ACTION-126: Add Prefer header (JA)</li>
<li>2014-02-07 - LDP-BCs use ldp:contains not ldp:member (JA)</li>
--- a/ldp.ttl Sat Feb 08 13:11:14 2014 -0500
+++ b/ldp.ttl Sat Feb 08 14:43:27 2014 -0500
@@ -181,14 +181,6 @@
rdfs:isDefinedBy :;
rdfs:label "Page".
-:nonMemberResource
- a rdf:Description;
- 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 "nonMemberResource";
- rdfs:domain :Container;
- rdfs:range :Resource.
:member
a rdf:Property;
@@ -230,10 +222,10 @@
rdfs:isDefinedBy :;
rdfs:label "PreferMembership".
-:PreferUnmanaged
+:PreferEmptyContainer
a rdf:Description; # individual
- rdfs:comment "URI identifying a subset of a LDPC's triples that excludes triples managed by the LDPC, for example to allow clients to express interest in receiving them. Currently an LDPC manages only containment and membership triples, but in the future others might be added. This definition is written to automatically exclude those new classes of triples, as long as they are the responsibility of the LDPC to manage.";
+ rdfs:comment "URI identifying the subset of a LDPC's triples present in an empty LDPC, for example to allow clients to express interest in receiving them. Currently this excludes containment and membership triples, but in the future other exclusions might be added. This definition is written to automatically exclude those new classes of triples.";
vs:term_status "unstable";
rdfs:isDefinedBy :;
- rdfs:label "PreferUnmanaged".
+ rdfs:label "PreferEmptyContainer".
\ No newline at end of file