sspeiche@12: sspeiche@194: sspeiche@12: sspeiche@12: sspeiche@12: Linked Data Platform 1.0 sspeiche@12: sspeiche@12: sspeiche@39: sspeiche@12: sspeiche@12: johnarwe@33: sspeiche@12: sspeiche@12: sspeiche@12:
sspeiche@12: A set of best practices and simple approach for a read-write Linked Data architecture, based on sspeiche@78: HTTP access to web resources that describe their state using the RDF sspeiche@78: data model. sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

Introduction

sspeiche@12:

This document describes the use sspeiche@12: of HTTP for accessing, updating, creating and deleting resources from sspeiche@12: servers that expose their resources as Linked Data.  It provides some sspeiche@12: new rules as well as clarifications and extensions of the four rules johnarwe@33: of Linked Data [[LINKED-DATA]]:

sspeiche@12:

1. Use URIs as names for things

sspeiche@12:

2. Use HTTP URIs so that people can look up those sspeiche@12: names

sspeiche@12:

3. When someone looks up a URI, provide useful johnarwe@33: information, using the standards (RDF*, SPARQL)

sspeiche@12:

4. Include links to other URIs. so that they can sspeiche@12: discover more things

Ashok@204:

This specification discusses standard HTTP and RDF techniques and best practices that you Ashok@204: should use, and anti-patterns you should avoid, when constructing clients and servers that Ashok@204: read and write Linked Data.

sspeiche@208:

A special type of Linked Data Platform Resource is a Container. Containers are very useful sspeiche@208: in building application models. For example, universities offer a collection of classes sspeiche@208: and have a collection of faculty members. Each faculty member teaches a collection of courses, etc. sspeiche@208: This specification discusses how to work with containers. Resources can be added to containers in sspeiche@208: several ways. As a special case, members can both be created and added to a container by overloading sspeiche@208: the POST operation. See .

Ashok@204:

Another contribution of this specification is how to deal with large amounts of data. Ashok@204: Depending on the server’s capabilities, a GET request on a Linked Data Platform Resource sspeiche@208: returns a set of pages and uses a convention to access any subsequent page. See .

Ashok@204:

The intention of this document is to enable additional rules and layered groupings of rules as Ashok@204: additional specifications. The scope is intentionally narrow to provide a set of key rules for Ashok@204: reading and writing Linked Data that most, if not all, other specifications will depend upon and sspeiche@208: implementations will support.

sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

Terminology

sspeiche@12: johnarwe@33:

Terminology is based on W3C's Architecture of the World Wide Web [[WEBARCH]] and Hyper-text Transfer Protocol [[HTTP11]]. sspeiche@12:

sspeiche@12:
sspeiche@12:
Link
sspeiche@12:
A relationship between two resources when one resource (representation) refers to the other resource by means johnarwe@33: of a URI [[WEBARCH]]. johnarwe@33:

sspeiche@12: sspeiche@12:
Linked Data
johnarwe@33:
As defined by Tim Berners-Lee [[LINKED-DATA]].

sspeiche@12: johnarwe@33:
Linked Data Platform Resource (LDPR)
sspeiche@112:
HTTP resource whose state is represented in RDF that conforms to the simple lifecycle sspeiche@194: patterns and conventions in the .

sspeiche@12: johnarwe@33:
Linked Data Platform Container (LDPC)
sspeiche@112:
An LDPR representing a collection of same-subject, same-predicate triples which is uniquely identified by a URI sspeiche@86: that responds to client requests for creation, modification, and enumeration of its members. johnarwe@33:

sspeiche@12: sspeiche@12:
Client
johnarwe@33:
A program that establishes connections for the purpose of sending requests [[HTTP11]].

sspeiche@12: sspeiche@12:
Server
sspeiche@12:
An application sspeiche@12: program that accepts connections in order to service requests by johnarwe@33: sending back responses. johnarwe@33:

Any given program may be capable of being sspeiche@12: both a client and a server; our use of these terms refers only to sspeiche@12: the role being performed by the program for a particular sspeiche@12: connection, rather than to the program's capabilities in general. sspeiche@12: Likewise, any server may act as an origin server, proxy, gateway, johnarwe@33: or tunnel, switching behavior based on the nature of each request johnarwe@33: [[HTTP11]].

johnarwe@33: John@120:
Membership triples
johnarwe@33:
A set of triples in an LDPC's state that lists its members. johnarwe@33: The membership triples of a container all have the same johnarwe@33: subject and predicate, and the objects of the membership triples define johnarwe@33: the container's members. johnarwe@33:

johnarwe@33: John@120:
Membership subject
John@120:
The subject of all a LDPC's membership triples. johnarwe@33:

johnarwe@33: John@120:
Membership predicate
John@120:
The predicate of all a LDPC's membership triples. John@120:

John@120: John@120:
Non-member resource
John@120:
A resource associated with a LDPC by a server for the purpose of enabling clients to John@120: retrieve a subset of the LDPC's state, namely the subset that omits the LDPC's membership triples. John@120: In other words, the union of the non-member resource's state and the LDPC's membership triples John@120: exactly equals the LDPC's state. johnarwe@33:

John@175: John@175:
Resource inlining
John@175:
sspeiche@192: The practice of responding to a HTTP GET request made to a request URI R0 with sspeiche@192: a representation that includes the state of R0, the entire state of resources accessed through sspeiche@192: other request URI(s) R1...Rn, and assertions from the server John@178: identifying the additional resources whose John@175: entire state has been provided. sspeiche@192: R1...Rn identify the inlined resource(s). John@175: See for details. John@175:

John@175: John@175:
Member inlining
John@175:
A special case of resource inlining, where all members of a container on a given John@175: page are inlined. The response page may or may not include all of the container's members. John@175: See for details. John@175:

John@175: sspeiche@12:
johnarwe@33: sspeiche@12:
sspeiche@12:

Conventions Used in This Document

sspeiche@12: sspeiche@12:

Sample resource representations are provided in text/turtle sspeiche@12: format [[TURTLE]].

sspeiche@12:

Commonly used namespace prefixes:

sspeiche@93:
	@prefix dcterms: <http://purl.org/dc/terms/>.
sspeiche@12: 	@prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
sspeiche@12: 	@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#>.
sspeiche@42: 	@prefix ldp:     <http://www.w3.org/ns/ldp#>.
sspeiche@12: 	@prefix xsd:     <http://www.w3.org/2001/XMLSchema#>.
sspeiche@12:
sspeiche@12:
sspeiche@12: sspeiche@71:
sspeiche@71: sspeiche@72:

The status of the sections of Linked Data Platform 1.0 (this document) is as follows:

sspeiche@71: sspeiche@71: sspeiche@194:

A conforming LDP server is an application program that processes HTTP sspeiche@194: requests and generates HTTP responses that conform to the rules defined in sspeiche@194: and .

sspeiche@71: sspeiche@194:

A conforming LDP client is an application program that generates HTTP sspeiche@194: requests and processes HTTP responses that conform to the rules defined in sspeiche@194: and .

sspeiche@71: sspeiche@71:
sspeiche@71: sspeiche@12: sspeiche@12:
johnarwe@33:

Linked Data Platform Resources

johnarwe@33:

Linked Data Platform Resources (LDPRs) are HTTP resources sspeiche@12: that conform to the simple patterns and conventions in this section. sspeiche@12: HTTP requests to access, modify, create or delete LDPRs are accepted sspeiche@12: and processed by LDPR servers. Most LDPRs are domain-specific resources sspeiche@12: that contain data for an entity in some domain, which could be sspeiche@12: commercial, governmental, scientific, religious, or other.

sspeiche@12:

Some of the rules defined in this document provide johnarwe@33: clarification and refinement of the base Linked Data rules [[LINKED-DATA]]; sspeiche@12: others address additional needs.

sspeiche@12:

The rules for Linked Data Platform Resources address basic sspeiche@12: questions such as:

sspeiche@12: johnarwe@37:

Additional informative guidance is available on the working group's wiki that addresses deployment johnarwe@37: questions such as:

johnarwe@37: sspeiche@12:

The following sections define the rules and sspeiche@134: guidelines for use of LDPRs. This document also explains how to include sspeiche@134: information about each member in the resource’s own representation sspeiche@134: and how to paginate the resource representation if it gets too big.

sspeiche@13: sspeiche@12:
sspeiche@12:

General

sspeiche@12: sspeiche@12:
4.1.1 LDPR servers MUST at least be HTTP/1.1 conformant servers [[!HTTP11]].
johnarwe@37:
4.1.2 LDPR servers MUST provide an RDF representation for LDPRs. sspeiche@192: The HTTP Request-URI of the LDPR is typically the subject of most triples in the response. sspeiche@12:
sspeiche@12:
4.1.3 LDPR servers MAY host a mixture of LDPRs and non-LDPRs. For example, it sspeiche@12: is common for LDPR servers to need to host binary or text resources sspeiche@12: that do not have useful RDF representations. sspeiche@12:
sspeiche@69: sspeiche@107:
4.1.4 LDPRs SHOULD reuse existing vocabularies instead of creating johnarwe@33: their own duplicate vocabulary terms. In addition to this general rule, some specific cases are johnarwe@33: covered by other conformance rules. johnarwe@33:
sspeiche@107:
4.1.4.1 LDPR predicates SHOULD use standard vocabularies such as Dublin Core sspeiche@188: [[!DC-TERMS]], RDF [[!RDF-CONCEPTS]] and RDF Schema [[!RDF-SCHEMA]], whenever johnarwe@33: possible. sspeiche@12:
sspeiche@192:
4.1.5 LDPR representations SHOULD have at least one rdf:type sspeiche@12: set explicitly.  This makes the representations much more useful to sspeiche@12: client applications that don’t support inferencing. sspeiche@12:
sspeiche@192:
4.1.6 LDPR servers MAY support standard representations beyond those johnarwe@33: necessary to conform to this specification. These sspeiche@12: could be other RDF formats, like N3 or NTriples, but non-RDF formats sspeiche@182: like HTML [[!HTML401]] and JSON [[!RFC4627]] would likely be common. sspeiche@72:
sspeiche@12: sspeiche@192:
4.1.7 LDPRs MAY be created, updated and deleted using methods not defined in sspeiche@12: this document, for example through application-specific means, SPARQL johnarwe@33: UPDATE, etc. [[!SPARQL-UPDATE]], as long as those methods do not conflict with this specification's johnarwe@33: normative requirements. sspeiche@12:
sspeiche@192:
4.1.8 LDPR server responses MUST use entity tags (either weak or strong sspeiche@60: ones) as response ETag header values. sspeiche@12:
sspeiche@12: John@152:
sspeiche@43: sspeiche@43: How can clients discover that a resource is an LDPR or LDPC, and what features are supported? sspeiche@43:
johnarwe@33: sspeiche@192:
4.1.9 LDPR johnarwe@33: servers SHOULD enable simple creation and modification of LDPRs. johnarwe@33: It is johnarwe@33: common for LDPR servers to put restrictions on representations – for johnarwe@33: example, the range of rdf:type predicates, datatypes of johnarwe@33: the objects of predicates, and the number of occurrences of predicates in an LDPR, but johnarwe@33: servers SHOULD minimize those restrictions.  Enforcement of johnarwe@33: more complex constraints will greatly restrict the set of clients johnarwe@33: that can modify resources. For some server applications, excessive johnarwe@33: constraints on modification of resources may be required. johnarwe@33:
John@149: John@149:
John@149: John@149: How can a client determine that it is in communication with an LDP server? John@149:
John@149: sspeiche@192:
4.1.10 LDPR servers John@149: MUST advertise their LDP support by exposing a HTTP Link header John@149: with a target URI of http://www.w3.org/ns/ldp/Resource, and John@149: a link relation type of type (that is, rel="type") John@149: in all responses to requests made sspeiche@192: to the resource's HTTP Request-URI. This is notionally equivalent to the sspeiche@192: presence of a (subject-URI, rdf:type, ldp:Resource) triple in the resource. John@200: The HTTP Link header is the method by which servers assert their support for the LDP specification in a way John@149: that clients can introspect dynamically at run-time. Conservative clients should note that John@200: a server can host a mixture of LDPRs and other resources, and therefore there is no implication sspeiche@192: that LDP support advertised on one HTTP Request-URI means that other sspeiche@192: resources on the same server are also LDPRs. Each HTTP Request-URI needs to be John@149: individually introspected by a conservative client, in the absence of outside information. John@149:
John@152:
John@152: John@152: inferencing levels John@152:
John@152: sspeiche@192:
4.1.11 LDPR servers John@152: MUST NOT require LDP clients to implement inferencing in order to recognize the subset John@152: of content defined by LDP. Other specifications built on top of LDP MAY require clients sspeiche@188: to implement inferencing [[!RDF-CONCEPTS]]. The practical implication is that all content defined by LDP John@152: must be explicitly represented. John@152:
John@152: sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

HTTP GET

sspeiche@192:
4.2.1 LDPR servers MUST support the HTTP GET Method for LDPRs. sspeiche@12:
johnarwe@33:
4.2.2 LDPR servers MUST provide a text/turtle johnarwe@33: representation of the requested LDPR [[!TURTLE]]. sspeiche@12:
johnarwe@33:
4.2.3 LDPR servers MAY provide johnarwe@33: representations of the requested LDPR beyond those johnarwe@33: necessary to conform to this specification, using standard HTTP content negotiation. sspeiche@14: If the client does not indicate a preference, text/turtle MUST be returned. sspeiche@69:
sspeiche@12:
4.2.4 In the absence of special knowledge of the application or domain, LDPR johnarwe@33: clients MUST assume that any LDPR can have multiple values for rdf:type. sspeiche@12:
sspeiche@12:
4.2.5 In the absence of special knowledge of the application or domain, LDPR sspeiche@12: clients MUST assume that the rdf:type values johnarwe@33: of a given LDPR can change over time. sspeiche@12:
sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

HTTP POST

sspeiche@192:

This specification adds no new requirements on HTTP POST for LDPRs John@200: even when the LDPR supports that method. This specification does not impose any sspeiche@93: new requirement to support that method, and [[!HTTP11]] makes it optional

John@200:

Creation of LDPRs can be done via or sspeiche@202: to a LDPC, see those John@200: sections for more details.

sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

HTTP PUT

sspeiche@192:

This specification imposes the following new requirements on HTTP PUT for LDPRs johnarwe@37: only when the LDPR supports that method. This specification does not impose any johnarwe@37: new requirement to support that method, and [[!HTTP11]] makes it optional.

sspeiche@12: sspeiche@192:
4.4.1 If HTTP PUT is performed on an existing resource, LDPR servers MUST sspeiche@12: replace the entire persistent state of the identified resource with sspeiche@61: the entity representation in the body of the request. sspeiche@92: LDPR servers MAY ignore server managed properties such as dcterms:modified sspeiche@61: and dcterms:creator if they are not under sspeiche@61: client control. Any LDPR servers that wish sspeiche@12: to support a more sophisticated merge of data provided by the client sspeiche@12: with existing state stored on the server for a resource MUST use HTTP sspeiche@192: PATCH, not HTTP PUT. sspeiche@61:
sspeiche@12: sspeiche@12:
4.4.2 LDPR clients SHOULD use the HTTP If-Match sspeiche@12: header and HTTP ETags to ensure it isn’t sspeiche@12: modifying a resource that has changed since the client last retrieved sspeiche@12: its representation. LDPR servers SHOULD require the HTTP If-Match header and HTTP ETags sspeiche@12: to detect collisions. LDPR servers MUST respond with status code 412 John@122: (Condition Failed) if ETags fail to match when there are no other John@122: errors with the request [[!HTTP11]]. LDPR servers that require conditional requests MUST respond with status code 428 John@122: (Precondition Required) when the absence of a precondition is the only reason for rejecting the request [[!RFC6585]]. sspeiche@12:
sspeiche@12:
4.4.3 LDPR clients SHOULD always assume that the set of predicates for a johnarwe@33: resource of a particular type at an arbitrary server is open, in the sspeiche@12: sense that different resources of the same type may not all have the johnarwe@33: same set of predicates in their triples, and the set of predicates that johnarwe@33: are used in the state of any one resource is not limited to any pre-defined sspeiche@12: set. sspeiche@12:
sspeiche@80:
4.4.4 LDPR clients SHOULD assume that an LDPR server could discard triples sspeiche@12: whose predicates the server does not recognize or otherwise chooses sspeiche@12: not to persist. In other words, LDPR servers MAY restrict themselves sspeiche@12: to a known set of predicates, but LDPR clients MUST NOT restrict themselves to a known set of predicates sspeiche@192: when their intent is to perform a later HTTP PUT to update the resource. sspeiche@12:
sspeiche@192:
4.4.5 An LDPR client MUST preserve all triples retrieved using HTTP GET that sspeiche@12: it doesn’t change whether it understands the predicates or not, when sspeiche@192: its intent is to perform an update using HTTP PUT.  The use of HTTP sspeiche@192: PATCH instead of HTTP PUT for update avoids this burden for clients sspeiche@12: [[RFC5789]]. sspeiche@12:
sspeiche@192:
4.4.6 LDPR servers MAY choose to allow the creation of new resources using HTTP PUT. sspeiche@12:
sspeiche@12:
4.4.7 LDPR servers SHOULD allow clients to update resources without johnarwe@33: requiring detailed knowledge of server-specific constraints.   sspeiche@192: This is a consequence of the requirement to enable simple creation and modification of LPDRs. sspeiche@12:
sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

HTTP DELETE

sspeiche@192:

This specification imposes the following new requirements on HTTP DELETE for LDPRs johnarwe@37: only when the LDPR supports that method. This specification does not impose any johnarwe@37: new requirement to support that method, and [[!HTTP11]] makes it optional.

sspeiche@192:

Additional requirements on HTTP DELETE of LDPRs within containers can be found in sspeiche@171: section 5.6.

johnarwe@37: sspeiche@192:
4.5.1 LDPR servers MUST remove the resource identified by the Request-URI. sspeiche@192: After a successful HTTP DELETE, a subsequent HTTP GET on the same sspeiche@192: Request-URI MUST result in a 404 (Not found) or 410 (Gone) status johnarwe@33: code. Clients SHOULD note that servers MAY reuse a URI under some circumstances. sspeiche@12:
sspeiche@19: sspeiche@12:
4.5.2 LDPR servers MAY alter the state of other resources as a result of an sspeiche@192: HTTP DELETE request. For example, it is acceptable for the server to sspeiche@12: remove triples from other resources whose subject or object is the sspeiche@12: deleted resource. It is also acceptable and common for LDPR servers to sspeiche@12: not do this – behavior is server application specific. sspeiche@12:
sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

HTTP HEAD

John@114:

Note that certain LDP mechanisms, such as paging, rely on HTTP headers, and HTTP generally requires that sspeiche@192: HEAD responses include the same headers as GET responses. sspeiche@194: Thus, implementers should also carefully read sspeiche@194: .

sspeiche@192:
4.6.1 LDPR servers MUST support the HTTP HEAD method.
sspeiche@194:
4.6.2 LDPR servers MUST support the HTTP response headers defined in . sspeiche@12:
sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

HTTP PATCH

sspeiche@192:

This specification imposes the following new requirements on HTTP PATCH for LDPRs johnarwe@37: only when the LDPR supports that method. This specification does not impose any johnarwe@37: new requirement to support that method, and [[!HTTP11]] makes it optional.

johnarwe@37: sspeiche@192:
4.7.1 LDPR servers MAY implement HTTP PATCH to allow modifications, johnarwe@37: especially partial replacement, of their resources [[!RFC5789]]. No sspeiche@12: minimal set of patch document formats is mandated by this document. sspeiche@12:
John@158: sspeiche@12:
4.7.2 LDPR servers SHOULD allow clients to update resources without johnarwe@33: requiring detailed knowledge of server-specific constraints.   sspeiche@192: This is a consequence of the requirement to enable simple creation and modification of LPDRs. johnarwe@33:
John@158: sspeiche@192:
4.7.3 LDPR servers SHOULD NOT allow clients to create new resources using PATCH. sspeiche@192: POST (to an LDPC) and/or PUT should be used as the standard way to create new LDPRs. sspeiche@12:
sspeiche@12: lehors@124:
John@158: John@158: How can clients discover that a resource is an LDPR or LDPC, and what features are supported? John@158:
John@158: sspeiche@192:
4.7.4 LDPR servers that support PATCH MUST John@158: include an Accept-Patch HTTP response header [[!RFC5789]] on HTTP OPTIONS John@158: requests, listing patch document media type(s) supported by the server. John@158:
sspeiche@186: sspeiche@12:
sspeiche@12: sspeiche@134:
John@158:

HTTP OPTIONS

John@158:

This specification imposes the following new requirements on HTTP OPTIONS for LDPRs John@158: beyond those in [[!HTTP11]]. Other sections of this specification, for example John@167: PATCH, John@167: Accept-Post John@167: and Paging, John@158: add other requirements on OPTIONS responses. John@158:

John@158: John@158:
John@158: John@158: How can clients discover that a resource is an LDPR or LDPC, and what features are supported? John@158:
John@158: John@158:
4.8.1 LDPR servers MUST support the HTTP OPTIONS method.
John@158: John@158:
4.8.2 LDPR servers MUST indicate their support for HTTP Methods by John@158: responding to a HTTP OPTIONS request on the LDPR’s URL with the HTTP sspeiche@192: Method tokens in the HTTP response header Allow. John@158:
John@158: John@158:
John@158: John@158:
sspeiche@134:

Paging

sspeiche@134: sspeiche@191:
sspeiche@134:

Introduction

sspeiche@134:

It sometimes happens that a sspeiche@134: resource is too large to reasonably transmit its representation in a sspeiche@134: single HTTP response. This will be especially true if the resource sspeiche@134: representation includes many triples both from its own representation and sspeiche@134: from the representations of any of its members. A client could anticipate that a resource will be too large - sspeiche@134: for example, a client tool that accesses defects may assume that an sspeiche@134: individual defect will usually be of sufficiently constrained size sspeiche@134: that it makes sense to request all of it at once, but that the sspeiche@134: container of all the defects ever created will typically be too big. sspeiche@134: Alternatively, a server could recognize that a resource that has been sspeiche@134: requested is too big to return in a single message.

sspeiche@134:

sspeiche@134: To address this problem, LDPRs should support a technique called Paging.  Paging can be achieved with a sspeiche@134: simple RDF pattern. For each resource, <resourceURL>, we define a new sspeiche@198: 'first page' resource. In this example, its URL will be <resourceURL>?firstPage, sspeiche@134: but servers are free to construct the URL as they see fit. sspeiche@134: The triples in the representation of the each page sspeiche@198: are typically a subset of the triples in the resource sspeiche@134: - same subject, predicate and object. sspeiche@134:

sspeiche@134:

LDPR servers may respond to requests for a sspeiche@134: resource by redirecting the client to the first page resource – sspeiche@134: using a 303 “See Other” redirect to the actual URL for the page John@200: resource. Alternatively, clients may introspect the resource for a paged representation John@200: and use it preferentially when available.

sspeiche@134:

sspeiche@198: Looking at an example resource representing Example Co.'s customer sspeiche@198: relationship data, we’ll split the response across two pages.   sspeiche@134: To find the URL of the first page, the client makes a OPTIONS request sspeiche@134: to the resource's URL, and in the response looks for a HTTP Link sspeiche@134: header with rel="first"; the target URI in the header is the URL sspeiche@134: of the first page resource. sspeiche@134: The client then sspeiche@198: requests the first page as ttp://example.org/customer-relations?firstPage: sspeiche@134:

sspeiche@198: sspeiche@134:
# The following is the representation of
sspeiche@198: #    http://example.org/customer-relations?firstPage
sspeiche@134: @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
sspeiche@134: @prefix dcterms: <http://purl.org/dc/terms/>.
sspeiche@198: @prefix foaf: <http://xmlns.com/foaf/0.1/>.
sspeiche@134: @prefix ldp: <http://www.w3.org/ns/ldp#>.
sspeiche@134: @prefix o: <http://example.org/ontology/>.
sspeiche@134: 
sspeiche@198: <http://example.org/customer-relations>
sspeiche@198:    a o:CustomerRelations;
sspeiche@198:    dcterms:title "The customer information for Example Co.";
sspeiche@198:    o:client <client#JohnZSmith>, <client#BettyASmith>, <client#JoanRSmith>. 
sspeiche@134: 
sspeiche@198: <http://example.org/customer-relations?firstPage>
sspeiche@134:    a ldp:Page;
sspeiche@198:    ldp:pageOf <http://example.org/customer-relations>;
sspeiche@198:    ldp:nextPage <http://example.org/customer-relations?p=2>.
sspeiche@134: 
sspeiche@198: <client#JohnZSmith>
sspeiche@198:    a foaf:Person;
sspeiche@198:    o:status o:ActiveCustomer;
sspeiche@198:    foaf:name "John Z. Smith".
sspeiche@198: <client#BettyASmith>
sspeiche@198:    a foaf:Person;
sspeiche@198:    o:status o:PreviousCustomer;
sspeiche@198:    foaf:name "Betty A. Smith".
sspeiche@198:  <client#BettyASmith>
sspeiche@198:    a foaf:Person;
sspeiche@198:    o:status o:PotentialCustomer;
sspeiche@198:    foaf:name "Joan R. Smith".
sspeiche@134: sspeiche@134:

sspeiche@134: The following example is the result of retrieving the representation sspeiche@134: for the next page: sspeiche@134:

sspeiche@134: sspeiche@134:
# The following is the representation of
sspeiche@198: #  http://example.org/customer-relations?p=2
sspeiche@134: @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
sspeiche@134: @prefix dcterms: <http://purl.org/dc/terms/>.
sspeiche@198: @prefix foaf: <http://xmlns.com/foaf/0.1/>.
sspeiche@134: @prefix ldp: <http://www.w3.org/ns/ldp#>.
sspeiche@134: @prefix o: <http://example.org/ontology/>.
sspeiche@134: 
sspeiche@198: <http://example.org/customer-relations>
sspeiche@198:    o:client <client#GlenWSmith>, <client#AlfredESmith>. 
sspeiche@198:  
sspeiche@198: <http://example.org/customer-relations?p=2>
sspeiche@134:    a ldp:Page;
sspeiche@198:    ldp:pageOf <http://example.org/customer-relations>;
sspeiche@134:    ldp:nextPage rdf:nil.
sspeiche@134: 
sspeiche@198: <client#GlenWSmith>
sspeiche@198:    a foaf:Person;
sspeiche@198:    o:status o:ActiveCustomer, o:GoldCustomer;
sspeiche@198:    foaf:name "Glen W. Smith".
sspeiche@134: 
sspeiche@198: <client#AlfredESmith>
sspeiche@198:    a foaf:Person;
sspeiche@198:    o:status o:ActiveCustomer, o:BronzeCustomer;
sspeiche@198:    foaf:name "Alfred E. Smith".
sspeiche@134:

sspeiche@198: In this example, there is only two customers provided in the sspeiche@134: final page.  To indicate this is the last page, a value of rdf:nil is used for the ldp:nextPage sspeiche@134: predicate of the page resource. sspeiche@134:

sspeiche@134:
sspeiche@134: sspeiche@134:
sspeiche@134:

HTTP GET

sspeiche@194:

In addition to the requirements set forth in section (HTTP GET), LDPR servers that support paging must also follow the requirements in this section

sspeiche@134: sspeiche@190:
4.9.2.1 LDPR servers SHOULD allow clients to retrieve large LDPRs in sspeiche@192: pages. In responses to GET requests with an LDPR as the Request-URI, sspeiche@134: LDPR servers that support paging SHOULD provide an HTTP Link sspeiche@134: header whose target URI is the first page resource, and whose link relation type is first [[!RFC5988]]. sspeiche@134: This is the mechanism by which clients discover the URL of the first page. If no such Link sspeiche@134: header is present, then conservative clients will assume that the LDPR does not support paging. sspeiche@134: For example, if there is a LDPR with URL <resourceURL> that supports paging and whose sspeiche@134: first page URL is <resourceURL>?theFirstPage, then the corresponding link header sspeiche@134: would be Link: <?theFirstPage>;rel="first". sspeiche@134: The representation for any page, including the first, will include John@201: the URL for the next page. See for additional details. sspeiche@134:
sspeiche@190:
4.9.2.2 LDPR servers MAY split the response representation of any LDPR. sspeiche@134: This is known as John@201: server-initiated paging. See for sspeiche@134: additional details. sspeiche@134:
sspeiche@190:
4.9.2.3 LDPR servers that initiate paging SHOULD respond to requests for a LDPR sspeiche@134: by redirecting the client to the first page resource using a 303 See sspeiche@134: Other response with an HTTP Location header providing the first page resource URL. sspeiche@134:
sspeiche@190:
4.9.2.4 LDPR servers that support paging MUST include in the page sspeiche@213: representation a representation for the LDPR. sspeiche@134:
sspeiche@190:
4.9.2.5 The page resource representation SHOULD have one triple to indicate its sspeiche@134: type, whose subject is the URL of the page, whose predicate is rdf:type and object is ldp:Page. sspeiche@134: It also SHOULD have 1 triple to indicate the resource it is paging, sspeiche@134: whose  subject is the URL of the page, predicate is ldp:pageOf, John@206: and object is the URL of the LDPR. sspeiche@134:
sspeiche@190:
4.9.2.6 The page resource representation MUST have one triple with the subject sspeiche@134: of the page, predicate of ldp:nextPage and sspeiche@134: object being the URL for the subsequent page. sspeiche@134:
sspeiche@190:
4.9.2.7 The last page resource representation MUST have one triple with the subject of the sspeiche@134: last page, predicate of ldp:nextPage and object being rdf:nil. sspeiche@134:
sspeiche@134:
sspeiche@134: sspeiche@134:
sspeiche@134:

HTTP OPTIONS

John@158: John@158:
John@158: John@158: How can clients discover that a resource is an LDPR or LDPC, and what features are supported? John@158:
John@158: John@158:
4.9.3.1 LDPR servers MUST indicate their support for client-initiated paging by John@158: responding to a HTTP OPTIONS request on the LDPR’s URL with the HTTP John@158: response header for link relations using the header name of Link and link relation type first [[!RFC5988]]. sspeiche@134:
sspeiche@134:
sspeiche@134: sspeiche@134:
sspeiche@134: John@174:
John@175:

Resource Inlining: Representing Multiple Resources in a Response

John@175: John@184:

Feature At Risk

John@184:

The LDP Working Group proposes incorporation of the features described in this section.

John@184:
    John@184:
  • The addition of resource inlining to save application latency John@184: and server/network load in controlled environments.
  • John@184:
John@184:

Feedback, both positive and negative, is invited by sending email to the mailing list John@184: in Status of This Document.

John@175:
John@174: sspeiche@191:
John@174:

Introduction

John@174:

Servers whose resources are relatively granular may wish to optimistically provide more information John@175: in a response than what the client actually requested, in order to reduce the average number of client John@175: application HTTP flows. LDP provides some basic building blocks to enable John@175: this, that implementations can re-use to build complete solutions, and they may serve as John@175: complete solutions in applications with sufficient controls on resource content. John@175: These building blocks are resource inlining and member inlining. John@174:

John@174: John@174:

LDP does not provide clients with any way to detect whether or not the server is capable of John@175: inlining (all its resources or any specific resource), nor does it provide clients John@174: with any way to influence which (if any) resources are inlined in any given response. John@174:

John@175: John@175:

John@175: Servers can return extra triples on any response, but fail to meet the definition of resource inlining, John@175: by either returning a subset of the other resource(s) triples or by failing to assert that John@175: all triples were included (even through they were). Clients might still find the extra John@175: information useful, but the only way for clients to be sure they had all available John@175: information would be to make a HTTP GET request against all the other resource(s). John@175: In some applications, knowing that these requests are unnecessary saves significant latency John@175: and server/network load. John@175:

John@174:
John@174: sspeiche@191:
John@174:

Use with Care

John@175:
John@174: John@174: Action 87: Add an informative section on the possible dangers of inlining resources John@174:
John@174: John@175:

The building blocks LDP provides can only be safely used if certain assumptions hold. John@175: Said another way, resource inlining solves a subset of scenarios, not all scenarios in the general case — John@175: so if you care about any of the following in a given application, your server should avoid returning sspeiche@192: any triples beyond those found at the HTTP Request-URI. John@174:

John@175:
    John@175:
  • John@175: Provenance is lost: because RDF graphs from multiple HTTP resources are merged in the John@178: response without attributing each statement to its originating graph (i.e. without quotation), John@178: it is impossible for a client to reliably know which John@175: triples came from which HTTP resource(s). A general solution allowing quotation is John@175: RDF Datasets; that is expected to be standardized independently, and can be used in these cases John@175: once it is available. John@175:

  • John@175:
  • John@175: The response may contain contradictions that are trivially obvious (or subtle), and those may or John@175: may not be a problem at the application level. For a trivial example, two triples may have John@175: identical subjects and predicates but different objects: "75F is too hot"; "75F is too cold". John@175: Again, quotation via RDF Datasets (or any equivalent mechanism) is believed to provide a John@175: long term solution once standardized. John@175:

  • John@175:
John@174:
John@174: John@174:
John@174:

HTTP GET

John@174:

In addition to the requirements set forth in other sections, sspeiche@194: LDPR servers that support resource inlining John@174: must also follow the requirements in this section.

John@174: John@174:
John@174: John@174: Action 89: Add a predicate ldp:inlinedResource the object of which is a URI of a linked resource that is fully inlined, John@174: marked as AT RISK. John@174:
John@174: sspeiche@194:
4.10.3.1 LDPR servers that support resource inlining MUST John@174: include a ldp:Page resource in the representation describing the set of inlined resources, John@174: whether or not the representation contains subsequent pages. The ldp:Page resource conceptually contains John@174: metadata about the representation; it is usually not part of the HTTP resource's state, and its presence does not indicate that John@174: the LDPR server supports paging in general. John@174: LDPR servers that include the ldp:Page resource for inlining and also support John@174: paging MUST use the same ldp:Page resource for the triples required by both, John@174: in order to minimize client code complexity. John@174: The ldp:Page resource's triples are the LDP-defined means by which the servers communicate to LDP clients John@174: the set of HTTP resources whose state is included in a representation, allowing clients to avoid HTTP GET John@175: requests for them. John@174:
John@174: sspeiche@194:
4.10.3.2 LDPR servers that support resource inlining MUST sspeiche@194: include the ldp:Page resource described in section 4.10.3.1 John@175: one triple for each inlined resource, John@174: whose subject is the ldp:Page resource URI, John@174: whose predicate is ldp:inlinedResource, and sspeiche@192: whose object is the HTTP Request-URI of an inlined resource [[!HTTP11]]. John@174:
John@174: sspeiche@194:
4.10.3.3 LDPR clients SHOULD avoid making HTTP GET requests sspeiche@192: against any resource whose HTTP Request-URI is the object of a triple of the form sspeiche@194: described in section 4.10.3.2, unless there are application-specific John@174: reasons for doing so. Clients should note that by the time the representation is received, the actual state John@174: of any inlined resource(s) may have changed due to subsequent requests. John@174:
John@174: sspeiche@194:
4.10.3.4 LDPR clients MUST NOT assume that LDPR representations John@174: lacking a ldp:Page resource or lacking the triple sspeiche@194: described in section 4.10.3.2 contain all the triples for any resource(s) sspeiche@192: listed in the representation whose HTTP Request-URI differs from sspeiche@192: the HTTP Request-URI used by the client. John@174: The representation might in fact contain all such triples, or some John@175: subset of them, and that might or might not be completely adequate for the client's intended usage, but John@175: an LDP client has no way to discern from such a representation which interpretation is accurate. John@174:
John@174: sspeiche@12:
sspeiche@12: John@174:
John@174: John@174:
John@174: sspeiche@12:
johnarwe@33:

Linked Data Platform Containers

sspeiche@12: sspeiche@12:
sspeiche@12:

Informative

sspeiche@12:

Many HTTP applications and sites have organizing sspeiche@12: concepts that partition the overall space of resources into smaller sspeiche@12: containers. Blog posts are grouped into blogs, wiki pages are grouped sspeiche@12: into wikis, and products are grouped into catalogs. Each resource sspeiche@12: created in the application or site is created within an instance of sspeiche@12: one of these container-like entities, and users can list the existing sspeiche@12: artifacts within one. Containers answer some basic questions, which sspeiche@12: are:

sspeiche@12:
    sspeiche@12:
  1. To which URLs can I POST to create new resources?
  2. sspeiche@12:
  3. Where can I GET a list of existing resources?
  4. sspeiche@12:
  5. How is the order of the container entries expressed?
  6. sspeiche@12:
  7. How do I get information about the members along with the container?
  8. sspeiche@12:
  9. How can I ensure the resource data is easy to query?
  10. sspeiche@12:
sspeiche@12:

sspeiche@12: This document defines the representation and behavior of containers sspeiche@12: that address these issues. The set of members of a container is sspeiche@12: defined by a set of triples in its representation (and state) called sspeiche@12: the membership triples. The membership triples of a container all sspeiche@12: have the same subject and predicate – the objects of the membership sspeiche@12: triples define the members of the container. The subject of the sspeiche@12: membership triples is called the membership subject and the predicate sspeiche@12: is called the membership predicate. In the simplest cases, the sspeiche@12: membership subject will be the LDPC resource itself, but it does not sspeiche@12: have to be. The membership predicate is also variable and will often sspeiche@12: be a predicate from the server application vocabulary or the rdfs:member predicate. sspeiche@12:

sspeiche@12:

This document includes a set of guidelines for sspeiche@12: using POST to create new resources and add them to the list of sspeiche@104: members of a container. It goes on to explain how to learn about a set of related sspeiche@104: resources, they may have been created using POST or through other means. sspeiche@104: It also defines behavior when POST created resources are deleted, to clean up sspeiche@104: container membership, and deleting containers removes membership information and sspeiche@104: possibly perform some cleanup tasks on unreferenced member resoruces.

sspeiche@104: sspeiche@12:

The following illustrates a very simple sspeiche@12: container with only three members and some information about the sspeiche@12: container (the fact that it is a container and a brief title):

sspeiche@12: sspeiche@12:
# The following is the representation of
sspeiche@74: #    http://example.org/container1/
sspeiche@12: @prefix dcterms: <http://purl.org/dc/terms/>.
sspeiche@12: @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
sspeiche@12: @prefix ldp: <http://www.w3.org/ns/ldp#>.
sspeiche@12: 
sspeiche@72: <>
sspeiche@12:    a ldp:Container;
John@130:    ldp:membershipSubject <>
John@130:    ldp:membershipPredicate rdfs:member;
sspeiche@210:    ldp:membershipObject ldp:MemberSubject;
sspeiche@12:    dcterms:title "A very simple container";
sspeiche@72:    rdfs:member <member1>, <member2>, <member3>.
sspeiche@12: sspeiche@12:

This example is very straightforward - the sspeiche@12: membership predicate is rdfs:member and the membership subject is the container sspeiche@12: itself. A POST to this container will create a new resource sspeiche@12: and add it to the list of members by adding a new membership triple sspeiche@12: to the container.

sspeiche@12: sspeiche@12:

Sometimes it is useful to use a subject sspeiche@87: other than the container itself as the membership subject and to use sspeiche@87: a predicate other than rdfs:member as the membership predicate. Let's sspeiche@88: start with a domain resource for a person's net worth, as illustrated below:

sspeiche@87: sspeiche@87:
# The following is a partial representation of
sspeiche@87: #   http://example.org/netWorth/nw1
sspeiche@87: @prefix ldp: <http://www.w3.org/ns/ldp#>.
sspeiche@87: @prefix o: <http://example.org/ontology/>.
sspeiche@87: <>
sspeiche@87:    a o:NetWorth;
sspeiche@87:    o:netWorthOf <http://example.org/users/JohnZSmith>;
sspeiche@87:    o:asset 
sspeiche@87:       <assetContainer/a1>,
sspeiche@87:       <assetContainer/a2>;
sspeiche@87:    o:liability 
sspeiche@87:       <liabilityContainer/l1>,
sspeiche@87:       <liabilityContainer/l2>,
sspeiche@87:       <liabilityContainer/l3>.
sspeiche@87: 
sspeiche@87:

From this example, there is a rdf:type of o:NetWorth indicating the sspeiche@87: resource represents an instance of a person's net worth and o:netWorthOf predicate indicating sspeiche@87: the associated person. There are two sets of same-subject, same-predicate pairings; one for assets and sspeiche@87: one for liabilities. It would be helpful to be able to associate these multi-valued sets using a URL sspeiche@87: for them to assist with managing these, this is done by associating containers with them as sspeiche@87: illustrated below: sspeiche@87:

sspeiche@87: sspeiche@87:
# The following is an elaborated representation of
sspeiche@87: #   http://example.org/netWorth/nw1
sspeiche@87: @prefix ldp: <http://www.w3.org/ns/ldp#>.
sspeiche@87: @prefix o: <http://example.org/ontology/>.
sspeiche@87: <>
sspeiche@87:    a o:NetWorth;
sspeiche@87:    o:netWorthOf <http://example.org/users/JohnZSmith>;
sspeiche@87:    o:asset 
sspeiche@87:       <assetContainer/a1>,
sspeiche@87:       <assetContainer/a2>;
sspeiche@87:    o:liability 
sspeiche@87:       <liabilityContainer/l1>,
sspeiche@87:       <liabilityContainer/l2>,
sspeiche@87:       <liabilityContainer/l3>.
sspeiche@87: 
sspeiche@87: <assetContainer/>
sspeiche@87:    a ldp:Container;
sspeiche@87:    dcterms:title "The assets of JohnZSmith";
sspeiche@87:    ldp:membershipSubject <.>;
sspeiche@210:    ldp:membershipPredicate o:asset;
sspeiche@210:    ldp:membershipObject ldp:MemberSubject.
sspeiche@87: 
sspeiche@87: <liabilityContainer/>
sspeiche@87:    a ldp:Container;
sspeiche@87:    dcterms:title "The liabilities of JohnZSmith";
sspeiche@87:    ldp:membershipSubject <.>;
sspeiche@210:    ldp:membershipPredicate o:liability;
sspeiche@210:    ldp:membershipObject ldp:MemberSubject.
sspeiche@87: 
sspeiche@87: sspeiche@87:

The essential structure of the container is sspeiche@87: the same, but in this example, the membership subject is not the sspeiche@87: container itself – it is a separate net worth resource. The sspeiche@87: membership predicates are o:asset and o:liability – predicates sspeiche@87: from the domain model. A POST of an asset representation to the asset container will create a new sspeiche@87: asset and add it to the list of members by adding a new membership triple sspeiche@87: to the container. You might wonder why sspeiche@87: http://example.org/netWorth/nw1 isn't made a container itself and POST sspeiche@87: the new asset directly there. That would be a fine design if http://example.org/netWorth/nw1 sspeiche@87: had only assets, but if it has separate predicates for assets and liabilities, sspeiche@87: that design will not work because it is unspecified to which predicate the POST sspeiche@87: should add a membership triple. Having separate http://example.org/netWorth/nw1/assetContainer/ sspeiche@87: and http://example.org/netWorth/nw1/liabilityContainer/ container sspeiche@87: resources allows both assets and liabilities to be created. sspeiche@87:

sspeiche@12: johnarwe@33:
sspeiche@12: # The following is the representation of
sspeiche@74: #   http://example.org/netWorth/nw1/assetContainer/
sspeiche@12: @prefix ldp: <http://www.w3.org/ns/ldp#>.
sspeiche@12: @prefix o: <http://example.org/ontology/>.
sspeiche@12: 
sspeiche@72: <>
sspeiche@12:    a ldp:Container;
sspeiche@12:    ldp:membershipSubject <http://example.org/netWorth/nw1>;
sspeiche@210:    ldp:membershipPredicate o:asset;
sspeiche@210:    ldp:membershipObject ldp:MemberSubject.
sspeiche@12: 
sspeiche@12: <http://example.org/netWorth/nw1>
sspeiche@12:    a o:NetWorth;
sspeiche@72:    o:asset <a1>, <a2>.
sspeiche@12: sspeiche@12:

In this example, clients cannot simply guess sspeiche@12: which resource is the membership subject and which predicate is the sspeiche@12: membership predicate, so the example includes this information in sspeiche@12: triples whose subject is the LDPC resource itself. sspeiche@12:

sspeiche@12: sspeiche@191:
5.1.1 Container Member Information
sspeiche@12:

In many – perhaps most – applications sspeiche@12: involving containers, it is desirable for the client to be able to sspeiche@12: get information about each container member without having to do a sspeiche@12: GET on each one. LDPC allows servers to include this information sspeiche@12: directly in the representation of the container. The server decides sspeiche@12: the amount of data about each member that is provided. Some common sspeiche@12: strategies include providing a fixed number of standard properties, sspeiche@12: or providing the entire RDF representation of each member resource, sspeiche@12: or providing nothing. The server application domain and its use-cases sspeiche@12: will determine how much information is required.

sspeiche@12: sspeiche@12:

Continuing on from the net worth sspeiche@12: example, there will be additional triples for the member resources sspeiche@12: (assets) in the representation:

sspeiche@12: sspeiche@12:
# The following is the representation of
sspeiche@74: #	 http://example.org/netWorth/nw1/assetContainer/
sspeiche@12: @prefix dcterms: <http://purl.org/dc/terms/>.
sspeiche@12: @prefix ldp:      <http://www.w3.org/ns/ldp#>.
sspeiche@12: @prefix o:       <http://example.org/ontology/>.
sspeiche@12: 
sspeiche@72: <>
sspeiche@12:    a ldp:Container;
sspeiche@12:    dcterms:title "The assets of JohnZSmith";
sspeiche@12:    ldp:membershipSubject <http://example.org/netWorth/nw1>;
sspeiche@210:    ldp:membershipPredicate o:asset;
sspeiche@210:    ldp:membershipObject ldp:MemberSubject.
sspeiche@12: 
sspeiche@12: <http://example.org/netWorth/nw1>
sspeiche@12:    a o:NetWorth;
sspeiche@72:    o:asset <a1>, <a3>, <a2>.
sspeiche@12: 
sspeiche@72: <a1>
sspeiche@12:    a o:Stock;
sspeiche@12:    o:value 10000.
sspeiche@72: <a2>
sspeiche@12:    a o:Bond;
sspeiche@12:    o:value 20000.
sspeiche@72: <a3>
sspeiche@12:    a o:RealEstateHolding;
sspeiche@12:    o:value 300000.
sspeiche@185:

In a similar manner, when the representation for the resource of asset .../<a1> is returned a sspeiche@185: server may include the membership triple of the form (.../assetContainer/, o:asset, .../a1).

Ashok@102: sspeiche@12:
5.1.2 Retrieving Only Non-member Properties sspeiche@12:
sspeiche@12: This section is non-normative sspeiche@12:

The representation of a container sspeiche@12: that has many members will be large. There are several important sspeiche@12: cases where clients need to access only the non-member properties of sspeiche@12: the container. Since retrieving the whole container representation to sspeiche@12: get this information may be onerous for clients and cause unnecessary sspeiche@12: overhead on servers, it is desired to define a way to retrieve only sspeiche@12: the non-member property values. Defining for each LDPC a corresponding John@120: resource, called the “non-member resource”, whose state is a subset sspeiche@12: of the state of the container, does this.

sspeiche@12:

The example listed here only show sspeiche@12: a simple case where only a few simple non-member properties are sspeiche@12: retrieved. In real world situations more complex cases are likely, such as those that add other predicates to sspeiche@12: containers, for example providing validation information and sspeiche@12: associating SPARQL endpoints. [[SPARQL-QUERY]]

sspeiche@12:

sspeiche@12: Here is an example requesting the non-member properties of a John@120: container identified by the URL http://example.org/container1/. John@120: In this case, the non-member resource is identified by the URL John@120: http://example.org/container1?non-member-properties: sspeiche@12:

sspeiche@12:

Request:

sspeiche@12:
GET /container1?non-member-properties HTTP/1.1
sspeiche@12: Host: example.org
sspeiche@12: Accept: text/turtle; charset=UTF-8
sspeiche@12: 
sspeiche@12:

Response:

sspeiche@12:
HTTP/1.1 200 OK
sspeiche@13: Content-Type: text/turtle; charset=UTF-8
sspeiche@12: ETag: "_87e52ce291112"
sspeiche@12: Content-Length: 325
sspeiche@12: 
sspeiche@12: @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.
sspeiche@12: @prefix dcterms: <http://purl.org/dc/terms/>.
sspeiche@12: @prefix ldp: <http://www.w3.org/ns/ldp#>.
sspeiche@12: 
sspeiche@74: <http://example.org/container1/>
sspeiche@12:    a ldp:Container;
sspeiche@12:    dcterms:title "A Linked Data Platform Container of Acme Resources";
John@130:    ldp:membershipSubject http://example.org/container1/;
sspeiche@12:    ldp:membershipPredicate rdfs:member;
sspeiche@210:    ldp:membershipObject ldp:MemberSubject;
sspeiche@12:    dcterms:publisher <http://acme.com/>.
John@120: John@120:

While the same non-member resource could be used to update the non-member properties via PUT, John@120: LDP recommends using PATCH for this purpose.

John@120: sspeiche@12:
5.1.4 Ordering
sspeiche@12: This section is non-normative sspeiche@12:

sspeiche@12: There are many cases where an ordering of the members of the sspeiche@12: container is important. LDPC does not provide any particular support sspeiche@12: for server ordering of members in containers, because any client can sspeiche@12: order the members in any way it chooses based on the value of any sspeiche@12: available property of the members. In the example below, the value of sspeiche@12: the o:value predicate is present for each sspeiche@12: member, so the client can easily order the members according to the sspeiche@12: value of that property. In this way, LDPC avoids the use of RDF sspeiche@12: constructs like Seq and List for expressing order. sspeiche@12:

sspeiche@12:

John@126: Order becomes more important for LDPC servers when containers are sspeiche@12: paginated. If the server does not respect ordering when constructing John@126: pages, the client would be forced to retrieve all pages before John@126: sorting the members, which would defeat the purpose of pagination. John@126: In cases where ordering is important, an LDPC server exposes all the John@126: members on a page with the proper sort order with relation to all John@126: members on the next and previous pages. John@126: When the sort is ascending, all the members on a current page have a John@126: higher sort order than all members on the previous page and John@126: lower sort order than all the members on the next page. John@126: When the sort is descending, the opposite order is used. John@126: Since more than one value may be used to sort members, John@126: the LDPC specification allows servers to assert the ordered list John@126: of sort criteria used to sort the members, using the John@126: ldp:containerSortCriteria relation. John@126: Each member of the ordered list exposes one ldp:containerSortCriterion, sspeiche@212: consisting of a ldp:containerSortOrder, John@126: ldp:containerSortPredicate, and John@126: optionally a ldp:containerSortCollation. sspeiche@12:

sspeiche@12:

Here is an example container described sspeiche@12: previously, with representation for ordering of the assets:

sspeiche@12:
# The following is the ordered representation of
sspeiche@74: #   http://example.org/netWorth/nw1/assetContainer/
sspeiche@12: @prefix dcterms: <http://purl.org/dc/terms/>.
sspeiche@12: @prefix ldp: <http://www.w3.org/ns/ldp#>.
sspeiche@12: @prefix o: <http://example.org/ontology/>.
sspeiche@12: 
sspeiche@72: <>
sspeiche@12:    a ldp:Container;
sspeiche@12:    dcterms:title "The assets of JohnZSmith";
sspeiche@12:    ldp:membershipSubject <http://example.org/netWorth/nw1>;
sspeiche@210:    ldp:membershipPredicate o:asset;
sspeiche@210:    ldp:membershipObject ldp:MemberSubject.
sspeiche@12: 
sspeiche@72: <?firstPage>
sspeiche@12:    a ldp:Page;
sspeiche@72:    ldp:pageOf <>;
sspeiche@212:    ldp:containerSortCriteria (#SortValueAscending).
John@126: 
John@126: <#SortValueAscending>
John@126:    a ldp:ContainerSortCriterion;
John@126:    ldp:containerSortOrder ldp:ascendingOrder;
John@126:    ldp:containerSortPredicate o:value.
sspeiche@12: 
sspeiche@12: <http://example.org/netWorth/nw1>
sspeiche@12:    a o:NetWorth;
sspeiche@72:    o:asset <a1>, <a3>, <a2>.
sspeiche@12: 
sspeiche@72: <a1>
sspeiche@12:    a o:Stock;
sspeiche@12:    o:value 100.00.
sspeiche@72: <a2>
sspeiche@12:    a o:Cash;
sspeiche@12:    o:value 50.00.
sspeiche@72: <a3>
sspeiche@12:    a o:RealEstateHolding;
sspeiche@12:    o:value 300000.
sspeiche@12:

John@126: As you can see by the addition of the ldp:ContainerSortCriteria sspeiche@12: predicate, the o:value predicate is used John@126: to order the page members in ascending order.  It is up to the domain model sspeiche@12: and server to determine the appropriate predicate to indicate the sspeiche@12: resource’s order within a page, and up to the client receiving this sspeiche@12: representation to use that order in whatever way is appropriate, for sspeiche@12: example to sort the data prior to presentation on a user interface. sspeiche@12:

sspeiche@12:
sspeiche@12: johnarwe@33:
sspeiche@12:

General

johnarwe@33:

The Linked Data Platform does not define how clients johnarwe@33: discover LDPCs.

johnarwe@33: sspeiche@12:
5.2.1 LDPC servers MUST also be conformant LDPR servers. A Linked Data Platform johnarwe@37: Container MUST also be a conformant Linked Data Platform Resource. sspeiche@12:
sspeiche@108:
5.2.2 For an LDPC, sspeiche@188: the same resource (LDPR or not) which is identified by its canonical URI, MAY be a member of sspeiche@108: more than one LDPC. sspeiche@85:
sspeiche@80:
5.2.3 The state of an LDPC includes information about which johnarwe@33: resources are its members. In the simplest cases, the membership subject sspeiche@12: will be the LDPC resource itself, but it does not have to be. The sspeiche@12: membership predicate is also variable and will often be a predicate sspeiche@12: from the server application vocabulary. If there is no obvious sspeiche@12: predicate from the server application vocabulary to use, LDPC servers sspeiche@113: SHOULD use the rdfs:member predicate. Member resources can be sspeiche@113: any kind of resource identified by its URI, LDPR or otherwise. sspeiche@12:
sspeiche@95: John@130:
5.2.4 An LDPC MUST contain one triple John@130: whose subject is the LDPC URI, John@130: whose predicate is the ldp:membershipSubject, John@130: and whose object is the LDPC's membership subject URI. sspeiche@12:
sspeiche@95: John@130:
5.2.5 An LDPC MUST contain one triple John@130: whose subject is the LDPC URI, John@130: and whose predicate is either ldp:membershipPredicate or ldp:membershipPredicateInverse. John@130: The object of the triple is constrained by other sections, such as John@130: 5.2.5.1 or 5.2.5.2. John@130:
John@130: John@130:
John@130: John@130: non-monotonic ldp:membershipXXX relations. Drafted per 2013-06-18 F2F resolution. sspeiche@12:
sspeiche@95: sspeiche@97:
5.2.5.1 For a given triple T with a subject C sspeiche@95: of the LDPC and predicate of sspeiche@97: ldp:membershipPredicate, the object MUST be the URI of the membership predicate P used to sspeiche@97: indicate membership to the linked to LDPC, or simply: T = ( C, ldp:membershipPredicate, P). sspeiche@98: For the membership predicate URI object used in the triple T, it would be found in a resource's sspeiche@97: same subject R and same predicate P membership triples of the form: sspeiche@97: (R, P, MR), where MR represents URI of sspeiche@98: a member resource. sspeiche@95:
sspeiche@95: sspeiche@97:
5.2.5.2 For a given triple T with a subject C sspeiche@95: of the LDPC and predicate of sspeiche@97: ldp:membershipPredicateInverse, the object MUST be the URI of the membership predicate P used to sspeiche@97: indicate membership to the linked to LDPC, or simply: T = ( C, ldp:membershipPredicateInverse, P). sspeiche@98: For the membership predicate URI object used in the triple T, it would be found in a resource's sspeiche@97: object subject R and same predicate P membership triples of the form: sspeiche@97: (MR, P, R), where MR represents URI of sspeiche@98: a member resource. sspeiche@95:
sspeiche@95: sspeiche@12:
5.2.6 The representation of a LDPC MAY include an arbitrary number of sspeiche@12: additional triples whose subjects are the members of the container, sspeiche@12: or that are from the representations of the members (if they have RDF sspeiche@12: representations). This allows a LDPC server to provide clients with sspeiche@192: information about the members without the client having to do a GET John@200: on each member individually. See sections 5.1.1 Container John@200: Member Information, , and John@200: for additional details. sspeiche@113:
sspeiche@12: sspeiche@12:
5.2.7 The representation of a LDPC MUST have rdf:type sspeiche@12: of ldp:Container, but it MAY have additional sspeiche@12: rdf:types. sspeiche@12:
sspeiche@12:
5.2.8 LDPCs SHOULD NOT use RDF container types rdf:Bag, johnarwe@33: rdf:Seq or rdf:List. sspeiche@12:
John@116: John@116:
5.2.9 LDPC servers SHOULD NOT re-use URIs, sspeiche@192: regardless of the mechanism by which members are created (POST, PUT, etc.). John@116: Certain specific cases exist where a LDPC server MAY delete a resource and then later re-use the John@116: URI when it identifies the same resource, but only when consistent with Web architecture [[WEBARCH]]. John@116: While it is difficult to provide absolute implementation guarantees of non-reuse in all failure John@116: scenarios, re-using URIs creates ambiguities for clients that are best avoided. John@116:
John@116: sspeiche@179: sspeiche@179:
5.2.10 Some LDPC's have membership object's that are not directly sspeiche@181: URIs minted upon LDPC member creation, for example URIs with non-empty fragment identifier [[RFC3986]]. John@200: To determine which object URI to use for the membership triple, LDPC's MUST contain one triple whose sspeiche@181: subject is the LDPC URI, predicate is ldp:membershipObject, with an object MO. sspeiche@192: Where MO and the HTTP URI R from POST create (as found in HTTP response Location header) can be sspeiche@181: used to locate a triple of the form: (R, MO, N) and sspeiche@179: where N can be used to construct the membership triple of the form: (membership subject, membership predicate, N). sspeiche@179: When ldp:membershipPredicateInverse is used instead of ldp:membershipPredicate, the membership triple MUST be sspeiche@181: of the form: (N, membership predicate, membership subject). To indicate that the member resource URI is the membership object sspeiche@181: (the default or typical case), the object MUST be set to predefined URI ldp:MemberSubject such that it forms the triple: sspeiche@181: (LDPC URI, ldp:membershipObject, ldp:MemberSubject). sspeiche@179:
sspeiche@179:
sspeiche@179: sspeiche@179: edited in ldp:membershipObject in new previous section sspeiche@179:
sspeiche@179: sspeiche@179: sspeiche@179: sspeiche@176: sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

HTTP GET

John@120: sspeiche@12:
5.3.1 The representation of a LDPC MUST contain a set of triples with a sspeiche@12: consistent subject and predicate whose objects indicate members of sspeiche@12: the container. The subject of the triples MAY be the container itself johnarwe@33: or MAY be another resource (as in the example).  See also sspeiche@12: 5.2.3. sspeiche@12:
sspeiche@134: sspeiche@190:
5.3.2 LDPC servers MAY represent the members of a paged LDPC in a sequential John@126: order.  If the server does so, it MUST be specify the order using a triple John@126: whose subject is the page URI, John@126: whose predicate is ldp:containerSortCriteria, John@126: and whose object is a rdf:List of John@126: ldp:containerSortCriterion resources. sspeiche@192: The resulting order MUST be as defined by SPARQL SELECT’s ORDER BY clause John@126: [[!SPARQL-QUERY]]. John@126: Sorting criteria MUST be the same for all pages of a representation; if John@126: the criteria were allowed to vary, the ordering among members of a container John@126: across pages would be undefined. John@126: The first list entry provides the primary John@126: sorting criterion, any second entry provides a secondary criterion used to order members considered John@126: equal according to the primary criterion, and so on. John@126: See section 5.1.4 Ordering for John@126: an example. John@126:
John@126: sspeiche@190:
5.3.3 LDPC page representations John@126: ordered using ldp:containerSortCriteria MUST contain, John@126: in every ldp:containerSortCriterion list entry, John@126: a triple John@126: whose subject is the sort criterion identifier, John@126: whose predicate is ldp:containerSortPredicate John@126: and whose object is John@129: the predicate whose value is used to order members between pages (the page-ordering values). John@126: The only predicate data types whose behavior LDP constrains are those defined sspeiche@192: by SPARQL SELECT’s ORDER BY clause [[!SPARQL-QUERY]]. Other data types John@126: can be used, but LDP John@126: assigns no meaning to them and interoperability will be limited. John@126:
John@126: sspeiche@190:
5.3.4 LDPC page representations John@126: ordered using ldp:containerSortCriteria MUST contain, John@126: in every ldp:containerSortCriterion list entry, John@126: a triple John@126: whose subject is the sort criterion identifier, John@126: whose predicate is ldp:containerSortOrder John@126: and whose object describes the order used. LDP defines two values, John@126: ldp:ascending and ldp:descending, for use John@126: as the object of this triple. Other values can be used, but LDP John@126: assigns no meaning to them and interoperability will be limited. John@126:
John@126: John@129:
John@129: John@129: Include clarifications about ordering in LDPC representations. John@129: The ReSpec SPARQL QUERY link is http://www.w3.org/TR/rdf-sparql-query/ , which has highlighted text John@129: referring readers to SPARQL 1.1. Which normative reference do we want? John@129:
John@129: sspeiche@190:
5.3.5 LDPC page representations John@126: ordered using ldp:containerSortCriteria MAY contain, John@126: in any ldp:containerSortCriterion list entry, John@126: a triple John@126: whose subject is the sort criterion identifier, John@126: whose predicate is ldp:containerSortCollation John@126: and whose object identifies the collation used. LDP defines no values for use John@129: as the object of this triple. While it is better for interoperability to use John@129: open standardized values, any value can be used. John@126: When the ldp:containerSortCollation triple is absent and the John@129: page-ordering values are strings or simple literals [[!SPARQL-QUERY]], the John@126: resulting order is as defined by SPARQL SELECT’s ORDER BY clause John@129: [[!SPARQL-QUERY]] using two-argument fn:compare, that is, John@129: it behaves as if http://www.w3.org/2005/xpath-functions/collation/codepoint John@129: was the specified collation. John@126: When the ldp:containerSortCollation triple is present and the John@129: page-ordering values are strings or simple literals John@129: [[!SPARQL-QUERY]], the John@126: resulting order is as defined by SPARQL SELECT’s ORDER BY clause John@126: [[!SPARQL-QUERY]] using three-argument fn:compare, that is, the John@126: specified collation. John@200: The ldp:containerSortCollation triple SHOULD be omitted for comparisons John@129: involving page-ordering values for which [[!SPARQL-QUERY]] does not use collations. John@126:
John@126: John@126:
John@129: John@129: Need to be able to specify collation with container ordering. Drafted per 2013-06-18 F2F resolution. sspeiche@12:
sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

HTTP POST

sspeiche@192:

This specification imposes the following new requirements on HTTP POST for LDPCs johnarwe@37: only when an LDPC supports that method. This specification does not impose any johnarwe@37: new requirement to support that method, and [[!HTTP11]] makes it optional.

johnarwe@37: johnarwe@33:
5.4.1 LDPC clients SHOULD create member resources by submitting a representation as sspeiche@192: the entity body of the HTTP POST to a known LDPC. If the resource was created successfully, LDPC servers MUST sspeiche@12: respond with status code 201 (Created) and the Location sspeiche@94: header set to the new resource’s URL. Clients shall not expect any representation in the response sspeiche@94: entity body on a 201 (Created) response. sspeiche@12:
sspeiche@94: sspeiche@192:
5.4.2 After a successful HTTP POST request to a LDPC, the new resource MUST sspeiche@12: appear as a member of the LDPC until the new resource is deleted or sspeiche@80: removed by other methods. An LDPC MAY also contain resources that were sspeiche@12: added through other means - for example through the user interface of sspeiche@12: the site that implements the LDPC. sspeiche@12:
sspeiche@43: sspeiche@192:
5.4.3 LDPC servers MAY accept an HTTP POST of non-RDF representations for John@200: creation of any kind of resource, for example binary resources. See 5.4.13 for introspection John@200: details. sspeiche@12:
sspeiche@80:
5.4.4 For servers that support create, LDPC servers MUST create an LDPR from a John@169: RDF representation in the request entity body. The newly created LDPR could also be a LDPC, therefore servers may sspeiche@77: allow the creations of LDPCs within a LDPC. sspeiche@12:
sspeiche@43: sspeiche@94:
5.4.5 LDPC servers MUST accept a request entity body with a request header sspeiche@18: of Content-Type with value of text/turtle [[!TURTLE]]. sspeiche@12:
sspeiche@94:
5.4.6 LDPC servers SHOULD use the Content-Type request header johnarwe@33: to determine the representation format when the request has an entity body. When the header is absent, johnarwe@33: LDPC servers MAY infer the content type by inspecting the entity body contents [[!HTTP11]]. sspeiche@12:
sspeiche@94:
5.4.7 In RDF representations, LDPC servers MUST interpret the null relative sspeiche@12: URI for the subject of triples in the LDPR representation in the sspeiche@12: request entity body as referring to the entity in the request body. sspeiche@12: Commonly, that entity is the model for the “to be created” LDPR, so sspeiche@12: triples whose subject is the null relative URI will usually result in sspeiche@12: triples in the created resource whose subject is the created sspeiche@12: resource.   John@174:
sspeiche@94:
5.4.8 LDPC servers SHOULD assign the subject URI for the resource to be John@115: created using server application specific rules in the absence of a client hint. sspeiche@12:
sspeiche@125:
5.4.8.1 For RDF representations, LDPC servers MUST assign the base-URI for sspeiche@125: [[!RFC3987]] relative-URI resolution to be the URI of the created subject resource. sspeiche@125:
sspeiche@94:
5.4.9 LDPC servers SHOULD allow clients to create new resources without sspeiche@12: requiring detailed knowledge of application-specific constraints. johnarwe@33: This is a consequence of the requirement to sspeiche@192: enable simple creation and modification of LPDRs. sspeiche@12:
John@115:
5.4.10 LDPC servers MAY allow clients to suggest the URI for a resource sspeiche@192: created through POST, using the HTTP Slug header as defined in [[!RFC5023]]. LDP adds John@115: no new requirements to this usage, so its presence functions as a client hint to the server John@115: providing a desired string to be incorporated into the server's final choice of resource URI. John@115:
John@115: sspeiche@192:
5.4.11 LDPC servers that allow member creation via POST John@116: SHOULD NOT re-use URIs, per the John@120: general requirements on LDPCs. John@116:
sspeiche@170: sspeiche@170:
5.4.12 Upon successful creation of a non-RDF and therefore non-LDPR member (HTTP status code of John@173: 201-Created and URI indicated by Location response header), LDPC servers MAY create an associated LDPR sspeiche@194: to contain data about the created resource. If an LDPC server creates this associated LDPR it MUST indicate sspeiche@170: its location on the HTTP response using the HTTP response header Link and relationship type meta John@173: and href to be the URI of the meta-resource [[!RFC5988]].
John@167: John@167:
John@167: sspeiche@192: How does a client know which POST requests create new resources. John@167:

John@167: Note from editor: the MUST here keeps this aligned with what we decided for OPTIONS on PATCH; in both John@167: cases the header registration says SHOULD, and the LDP spec says MUST. What makes that look a bit odd is John@167: that in the Accept-Post case, the registration and LDP are the same document. Thus I added informative John@167: text here explicitly talking to the apparent discrepancy. John@174:

John@167:
John@167: John@167:
5.4.13 LDPR servers that support POST MUST John@167: include an Accept-Post response header on HTTP OPTIONS John@167: responses, listing post document media type(s) supported by the server. John@167: LDP only specifies the use of POST for the purpose of creating new resources, but a server John@167: can accept POST requests with other semantics. John@167: While "POST to create" is a common interaction pattern, LDP clients are not guaranteed, even when John@167: making requests to an LDP server, that every successful POST request will result in the John@167: creation of a new resource; they must rely on out of band information for knowledge of which POST requests, John@167: if any, will have the "create new resource" semantic. John@167: This requirement on LDP servers is intentionally stronger than the one levied in the John@167: header registration; it is unrealistic to expect all existing resources John@167: that support POST to suddenly return a new header or for all new specifications constraining John@167: POST to be aware of its existence and require it, but it is a reasonable requirement for new John@167: specifications such as LDP. John@167:
John@167: John@169:
John@169: John@199: ldp:contains => created John@169:
John@169: John@169:
5.4.14 LDPCs that create new member resources MAY add triples to the container John@169: as part of member creation to reflect its factory role. John@199: LDP defines the ldp:created predicate for this purpose. John@169: An LDPC that tracks members created through the LDPC MUST add a triple John@169: whose subject is the container's URI, John@199: whose predicate is ldp:created, and John@169: whose object is the newly created member resource's URI; John@169: it MAY add other triples as well. John@169:
John@169: sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

HTTP PUT

sspeiche@192:

This specification imposes the following new requirements on HTTP PUT for LDPCs johnarwe@37: only when an LDPC supports that method. This specification does not impose any johnarwe@37: new requirement to support that method, and [[!HTTP11]] makes it optional.

johnarwe@37: sspeiche@192:
5.5.1 LDPC servers SHOULD NOT allow HTTP PUT to update a LDPC’s members; sspeiche@12: if the server receives such a request, it SHOULD respond with a 409 sspeiche@12: (Conflict) status code. sspeiche@12:
sspeiche@12:
5.5.2 LDPC servers MAY allow updating LDPC non-membership properties using sspeiche@192: HTTP PUT on a corresponding non-member resource, which sspeiche@95: MAY exclude server-managed properties such as ldp:membershipSubject, ldp:membershipPredicate sspeiche@95: and ldp:membershipPredicateInverse. John@120: Section 5.7.1 HTTP HEAD describes the process by which clients John@120: discover whether the server offers such a resource, and if so its URL. John@120: sspeiche@12:
sspeiche@113: sspeiche@192:
5.5.3 LDPC servers SHOULD NOT allow HTTP PUT requests sspeiche@113: with member information in the request representation. sspeiche@113: See section 5.1.1 Container sspeiche@113: Member Information for additional details. sspeiche@113:
John@116: sspeiche@192:
5.5.4 LDPC servers that allow member creation via PUT John@116: SHOULD NOT re-use URIs, per the John@120: general requirements on LDPCs. John@116:
John@116: sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

HTTP DELETE

sspeiche@192:

This specification imposes the following new requirements on HTTP DELETE for LDPRs johnarwe@37: only when a LDPC supports that method. This specification does not impose any johnarwe@37: new requirement to support that method, and [[!HTTP11]] makes it optional.

johnarwe@37: sspeiche@104:
5.6.1 When a LDPC member resource originally created by the LDPC (for example, one whose representation sspeiche@192: was HTTP POST'd to the LDPC and then referenced by a membership triple) is deleted, and the LDPC server is aware of the member's deletion John@65: (for example, the member is managed by the same server), the LDPC server MUST also remove it from John@65: the LDPC by removing the corresponding membership triple. John@65:
sspeiche@192:
5.6.2 When the LDPC server successfully completes the DELETE request on a LDPC, it MUST remove any sspeiche@192: membership triples associated with the LDPC as indicated by the canonical Request-URI. The LDPC server MAY perform additional removal John@169: of member resources. John@169: For example, the server could perform additional cleanup tasks for resources it knows are no longer referenced or have not sspeiche@104: been accessed for some period of time. John@68:
John@169: John@169:
John@169: John@199: ldp:contains => created John@169:
John@169: John@169:
5.6.3 When the conditions in 5.6.1 hold, and the LDPC tracks member John@199: resources that it created using the ldp:created predicate, the LDPC server MUST also remove John@199: the deleted member's ldp:created triple. John@169:
sspeiche@170: sspeiche@170:
5.6.4 When a LDPC member resource originally created by the LDPC (for example, one whose sspeiche@192: representation was HTTP POST'd to the LDPC and then referenced by a membership triple) is deleted, and the LDPC server sspeiche@171: created an associated LDPR (see 5.4.12), the LDPC server must also remove the associated LDPR it created. sspeiche@170:
sspeiche@170: sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

HTTP HEAD

John@114:

Note that certain LDP mechanisms, such as paging, rely on HTTP headers, and HTTP generally requires that sspeiche@192: HEAD responses include the same headers as GET responses. Also LDPR servers must also include HTTP headers sspeiche@192: on response to OPTIONS, see 4.6.2. sspeiche@192: Thus, implementers supporting HEAD should also carefully read the sspeiche@194: and .

sspeiche@171:
John@120: sspeiche@171:
sspeiche@171:

HTTP PATCH

sspeiche@192:

This specification imposes the following new requirements on HTTP PATCH for LDPCs sspeiche@171: only when a LDPC supports that method. This specification does not impose any sspeiche@171: new requirement to support that method, and [[!HTTP11]] makes it optional.

sspeiche@171: sspeiche@192:
5.8.1 LDPC servers are RECOMMENDED to support HTTP PATCH as the preferred sspeiche@171: method for updating LDPC non-membership properties. sspeiche@171:
sspeiche@171:
sspeiche@171: sspeiche@171:
sspeiche@171:

HTTP OPTIONS

sspeiche@192:

This specification imposes the following new requirements on HTTP OPTIONS for LDPCs. John@174:

sspeiche@171: sspeiche@171:
5.9.1 John@120: LDPC servers SHOULD define a corresponding John@120: non-member resource John@120: to support requests for information about a LDPC John@120: without retrieving a full representation including all of its members; John@120: see section 5.1.2 Retrieving Only Non-member Properties for John@120: examples. sspeiche@192: In responses to OPTIONS requests with an LDPC as the Request-URI, John@120: LDPC servers that define a non-member resource SHOULD provide an HTTP Link John@120: header whose target URI is the non-member resource, and whose link relation type is John@120: http://www.w3.org/ns/ldp#non-member-resource [[!RFC5988]]. John@120: This is the mechanism by which clients discover the URL of the non-member resource. John@120: If no such Link John@120: header is present, then conservative clients will assume that the LDPC does not have a corresponding John@120: non-member resource. John@120: For example, if there is a LDPC with URL <containerURL> whose corresponding John@120: non-member resource John@120: URL is <containerURL>?nonMemberProperties, then the corresponding link header John@120: would be Link: <?nonMemberProperties>;rel="http://www.w3.org/ns/ldp#non-member-resource" John@120:
John@120: John@173:
5.9.2 When a LDPC creates a non-LDPR (e.g. binary) member (for example, one whose sspeiche@192: representation was HTTP POST'd to the LDPC and then referenced by a membership triple) it might create an associated LDPR to contain data about the John@173: non-LDPR (see 5.4.12). For non-LDPRs that have this associated LDPR, an LDPC server MUST provide an HTTP Link John@173: header whose target URI is the associated LDPR, and whose link relation type is John@173: meta [[!RFC5988]].
sspeiche@12:
John@174: John@174:
John@175:

Member Inlining: Returning All of a Container Page's Members in a Response

John@175: John@184:

Feature At Risk

John@184:

The LDP Working Group proposes incorporation of the features described in this section.

John@184:
    John@184:
  • The addition of resource inlining to save application latency John@184: and server/network load in controlled environments.
  • John@184:
John@184:

Feedback, both positive and negative, is invited by sending email to the mailing list John@184: in Status of This Document.

John@175:
John@174: sspeiche@191:
John@174:

Introduction

John@174:

One of the most commonly cited scenarios for resource inlining is to save clients enumerating a container of John@174: m members from having to perform m+1 HTTP requests (or m+p, if the container John@174: is paged into p pages). The desire is to allow the server to reduce the number of HTTP John@174: round-trips by returning some (perhaps all) members' content as part of the container's representation. John@175: In addition to the general resource inlining mechanism useful John@175: in cases where only a subset of the members' content is inlined, LDP also provides John@174: a predicate for the special case where all of a container's or page's members are inlined. John@174: Rather than forcing the server to add a triple for each inlined member, forcing clients to John@174: compare the list of inlined members against the set of members in the representation, John@174: and enlarging the representation needlessly, John@175: a single triple can be used. This is called member inlining. John@174:

John@174: John@174:

LDP does not provide clients with any way to detect whether or not the server is capable of John@174: resource inlining (all its resources or any specific resource), nor does it provide clients John@174: with any way to influence which (if any) resources are inlined in any given response. John@174:

John@174: John@175:
John@174: John@174: Action 87: Add an informative section on the possible dangers of inlining resources John@174:
John@174: John@175:

The inlining building blocks LDP provides can only be safely used if certain assumptions hold. John@174: This is no less true for containers than for LDPRs in general. John@174: See the general cautions on resource inlining. John@174:

John@174:
John@174: John@174:
John@174:

HTTP GET

John@174:

In addition to the requirements set forth in other sections, sspeiche@194: LDPC servers that support member inlining, sspeiche@194: and LDP clients aware of the same facility, John@174: must also follow the requirements in this section. John@174:

John@174: John@174:
John@174: John@174: Action 88: Add a property ldp:membersInlined true/false. The default (if not specified) is false. John@174: If true, it means that a complete description of all members [on the current page] are inlined with the container document [or page], sspeiche@192: and therefore clients SHOULD NOT do GET on the member URIs to retrieve additional triples. John@174: marked as AT RISK. John@174:
John@174: John@175:
5.10.2.1 LDPC representations that are member inlined MUST John@174: include a ldp:Page resource in the representation, whether or not the representation contains sspeiche@194: multiple pages, as described in section 4.10.3.1. In addition to satisfying John@174: those requirements, the representation MUST contain a triple John@174: whose subject is the ldp:Page resource URI, John@174: whose predicate is ldp:membersInlined, and John@174: whose object is true. John@174: This is means by which the server communicates to LDP clients that they can avoid HTTP GET John@175: requests for the members listed on the page. John@174:
John@174: John@174:
5.10.2.2 LDPC clients SHOULD avoid making HTTP GET requests John@174: against any members in a LDPC representation containing a ldp:Page resource with the triple John@174: described in section 5.10.2.1, unless there are application-specific John@174: reasons for doing so. Clients should note that by the time the representation is received, the actual state John@175: of inlined members may have changed due to subsequent requests. John@174:
John@174: John@174:
5.10.2.3 LDPC clients MUST NOT assume that LDPC representations John@174: lacking a ldp:Page resource or lacking the triple John@174: described in section 5.10.2.1 contain all the triples for all members John@174: listed in the representation. The representation might in fact contain all those triples, or some John@174: subset of them, that might or might not be completely adequate for the client's intended usage, but John@175: an LDP client has no way to discern from such a representation which interpretation is accurate. John@174:
John@174: John@174:
John@174: John@174:
sspeiche@12:
sspeiche@12: John@167:
John@175:

HTTP Header Definitions

John@167: John@167:
John@175:

The Accept-Post Response Header

John@167: John@167:
John@167: John@167: How does a client know which POST requests create new resources John@167:
John@167: John@167:

This specification introduces a new HTTP response header Accept-Post used John@167: to specify the document formats accepted by the server on HTTP POST requests. John@167: It is modeled after the Accept-Patch header defined in [[!RFC5789]]. John@167:

John@167: John@167:
6.1.1 The syntax for Accept-Post, using John@167: the ABNF syntax defined in Section 2.1 of [[!HTTP11]], is: John@167:
Accept-Post = "Accept-Post" ":" 1#media-type John@167:

John@167: The Accept-Post header specifies a comma-separated list of media- John@167: types (with optional parameters) as defined by [[!HTTP11]], Section 3.7. John@167:

John@167:
John@167:
John@167: John@167:
6.1.2 John@167: The Accept-Post HTTP header SHOULD appear in the OPTIONS response for any resource John@167: that supports the use of the POST method. The presence of the John@167: Accept-Post header in response to any method is an implicit John@167: indication that POST is allowed on the resource identified by the John@167: Request-URI. The presence of a specific document format in John@167: this header indicates that that specific format is allowed on POST requests to the John@167: resource identified by the Request-URI. John@167:
John@167: sspeiche@190:
6.1.3 IANA Registration Template
sspeiche@190:
John@167:
John@167:

John@167: The Accept-Post response header must be added to the permanent registry (see [[!RFC3864]]). John@167:

John@167:

John@167: Header field name: Accept-Post John@167:

John@167:

John@167: Applicable Protocol: HTTP John@167:

John@167:

John@167: Author/Change controller: W3C John@167:

John@167:

John@167: Specification document: this specification John@167:

John@167:
sspeiche@190:
John@167: John@167:
John@167:
John@167: sspeiche@12:
sspeiche@12:

Acknowledgements

sspeiche@12: sspeiche@12:

The following people have been instrumental in providing thoughts, feedback, sspeiche@73: reviews, content, criticism and input in the creation of this specification:

sspeiche@12: sspeiche@187:

Tim Berners-Lee, Steve Battle, sspeiche@187: Olivier Berger, Alexandre Bertails, Reza B'Far, Cody Burleson, Richard Cyganiak, Raúl García Castro, sspeiche@187: Miguel Esteban Gutiérrez, sspeiche@187: Sandro Hawke, Kingsley Idehen, Yves Lafon, Arnaud Le Hors, Antonis Loizou, Ashok Malhota, Roger Menday, sspeiche@187: Nandana Mihindukulasooriya, Kevin Page, Eric Prud'hommeaux, Andy Seaborne, Steve Speicher, sspeiche@187: Henry Story, Ted Thibodeau, Bart van Leeuwen, Miel Vander Sande, Ruben Verborgh, Serena Villata, Erik Wilde, David Wood, Martin P. Nally

sspeiche@73: sspeiche@12:
sspeiche@12: sspeiche@12:
sspeiche@12:

Change History

sspeiche@83:

The change history is up to the editors to insert a brief summary of sspeiche@83: changes, ordered by most recent changes first and with heading from which sspeiche@83: public draft it has been changed from. sspeiche@83:

John@122: sspeiche@83: sspeiche@83: John@122:
Second Public Working Draft
sspeiche@12: John@122: John@122:
First Public Working Draft
John@65: John@122:
Submission
John@65:
sspeiche@12: sspeiche@12: sspeiche@12: