--- 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 <member1>, <member2>, <member3>.</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 <a1>, <a2>.</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>