sspeiche@12: sspeiche@194: sspeiche@12: sspeiche@12: sspeiche@12: Linked Data Platform 1.0 sspeiche@12: sspeiche@12: sspeiche@435: sspeiche@435: sspeiche@12: sspeiche@12: johnarwe@33: sspeiche@12: sspeiche@12: sspeiche@12:
sspeiche@215: This document describes 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@333:
sspeiche@333:

Introduction

John@373:

This specification describes the use sspeiche@12: of HTTP for accessing, updating, creating and deleting resources from sspeiche@215: servers that expose their resources as Linked Data.  It provides clarifications John@373: and extensions of the rules of Linked Data [[LINKED-DATA]]:

John@373:
    John@373:
  1. Use URIs as names for things
  2. John@373:
  3. Use HTTP URIs so that people can look up those names
  4. John@373:
  5. When someone looks up a URI, provide useful information, using the standards John@373: (RDF*, SPARQL) John@373:
  6. John@373:
  7. Include links to other URIs, so that they can discover more things
  8. John@373:
John@415:

This specification discusses standard HTTP and RDF techniques John@415: used when constructing clients and servers that John@395: create, read, and write Linked Data Platform Resources. John@373: A companion document discusses best practices that you John@373: should use, and anti-patterns you should avoid, when constructing these clients and servers. John@373:

John@395:

This specification provides a widely re-usable pattern to deal with large resources. John@395: Depending on the server’s capabilities, a GET request on a resource can John@395: return a subset of the resource (one page), that provides access to subsequent pages John@415: (see ). John@415:

John@373:

This specification defines a special type of Linked Data Platform Resource: a John@373: Container. Containers are very useful John@373: in building application models involving collections of resources, often homogeneous ones. John@373: For example, universities offer a collection of classes John@373: and have a collection of faculty members, each faculty member teaches a collection of courses, and so on. John@373: This specification discusses how to work with containers. Resources can be added to containers John@373: using standard HTTP operations like John@373: POST (see ).

John@373:

The intention of this specification 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@333:
sspeiche@333:

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: sspeiche@331:
Linked Data Platform Resource (LDPR)
sspeiche@112:
HTTP resource whose state is represented in RDF that conforms to the simple lifecycle sspeiche@215: patterns and conventions in .

sspeiche@12: sspeiche@331:
Linked Data Platform Container (LDPC)
John@395:
An LDPR representing a collection of membership 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. John@373: A container's membership triples all have one of the following patterns: John@373: John@373: John@373: John@373: John@415: John@373: John@373: John@415: John@373: John@373: John@373: John@373:
membership-constant-URI membership-predicate member-derived-URI
member-derived-URI membership-predicate membership-constant-URI
John@415: The difference between the two is simply which position member-derived-URI occupies, which is usually John@373: driven by the choice of membership-predicate. Most predicates have a natural forward direction John@373: inherent in their name, and existing vocabularies contain useful examples that read naturally in John@373: each direction. rdfs:member and dcterms:isPartOf are representative examples. John@373:

John@415: Each container exposes properties (see ) John@415: that allow clients to determine which pattern it John@373: uses, what the actual membership-predicate and membership-constant-URI values are, John@373: and (for containers that allow the creation of new members) what value is used John@415: for the member-derived-URI based on the client's input to the John@373: creation process.

johnarwe@33:

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

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

John@412: John@395:
Paged resource
John@395:
A resource whose representation may be too large to fit in a single HTTP response, for which an John@395: LDP server offers a sequence of single-page resources. When the representations of the sequence's resources John@412: are combined by a client, the client has a (potentially incomplete or incoherent) copy of the paged resource's John@395: state. If a paged resource P is an LDPR and is broken into a sequence of pages John@395: (single-page resources) P1, P2, ...,Pn, John@395: the representation of each Pi contains John@395: a subset of the triples in P. John@395: LDP allows paging of resources other than LDPRs, but does not specify how clients combine John@412: their representations. See for additional details. For readers John@415: familiar with paged feeds [[RFC5005]], a paged resource is similar to a logical feed. John@413: Any resource could be considered to be a paged resource consisting of exactly one page, John@412: although there is no known advantage in doing so. John@395:

John@395: John@395:
Single-page resource
John@395:
One of a sequence of related resources P1, P2, ...,Pn, John@395: each of which contains a subset of the state John@395: of another resource P. P is called the paged resource. John@412: For readers John@415: familiar with paged feeds [[RFC5005]], a single-page resource is similar to a feed document and the same John@412: coherency/completeness considerations apply. John@413: LDP provides no guarantees that the sequence is stable. sspeiche@416:

John@395: Note: the choice of terms was designed to help authors and readers clearly differentiate between John@395: the resource being paged, and the John@395: individual page resources, John@395: in cases where both are mentioned in John@413: close proximity. sspeiche@225:

sspeiche@225: John@412:
first page link
John@412:
A link to the first single-page resource John@412: of a paged resource P. Syntactically, a John@412: HTTP Link <P1>; rel='first' John@412: header [[!RFC5988]]. John@412:

John@412: John@412:
next page link
John@412:
A link to the next single-page resource John@412: of a paged resource P. Syntactically, a John@412: HTTP Link <Pi>; rel='next' John@415: header [[!RFC5988]] where the target URI is Pi=2...n. John@412:

John@412: John@412:
last page link
John@412:
A link to the last single-page resource John@412: of a paged resource P. Syntactically, a John@412: HTTP Link <Pn>; rel='last' John@412: header [[!RFC5988]]. John@412:

John@412: John@412:
previous page link
John@412:
A link to the previous single-page resource John@412: of a paged resource P. Syntactically, a John@412: HTTP Link <Pi>; rel='prev' John@415: header [[!RFC5988]] where the target URI is Pi=1...n-1. johnarwe@33:

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

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: John@373:

LDP uses the term informative as a synonym for non-normative.

sspeiche@72:

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

sspeiche@71: sspeiche@71: John@372:
John@372:

(OLD) A conforming LDP server is an application program that processes HTTP requests John@372: and generates HTTP responses that conform to the rules defined in John@372: and . John@372:

sspeiche@71: John@372:

(OLD) A conforming LDP client is an application program that generates HTTP John@372: requests and processes HTTP responses that conform to the rules defined in John@372: and . John@372:

John@372:
John@372: John@372:
John@372:

(NEW) A conforming LDP client is a conforming HTTP client [[!HTTP11]] that follows the rules defined by LDP in John@372: . John@372:

John@372: John@372:

(NEW) A conforming LDP server is a conforming HTTP server [[!HTTP11]] that follows the rules defined by LDP in John@372: when it is serving LDPRs, and also John@372: when it is serving LDPCs. John@372: LDP does not constrain its behavior when serving other HTTP resources. John@372:

John@372: John@372: John@372:
sspeiche@71: sspeiche@71:
sspeiche@71: sspeiche@435:
sspeiche@435:

Linked Data Platform Clients

sspeiche@435:
sspeiche@435: sspeiche@435:

All of the following rules are just copied here, without change; still need to be removed from original section. sspeiche@435: Should consider making this section come before the server sections; doing so would cause mass-renumbering however. sspeiche@435:

sspeiche@435:
sspeiche@435:

General

sspeiche@435:

In the absence of special knowledge of the application or domain, sspeiche@435: LDP clients MUST assume that any LDPR can have multiple values for rdf:type. sspeiche@435:

sspeiche@435: sspeiche@435:

In the absence of special knowledge of the application or domain, sspeiche@435: LDP clients MUST assume that the rdf:type values sspeiche@435: of a given LDPR can change over time. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP clients SHOULD always assume that the set of predicates for a sspeiche@435: resource of a particular type at an arbitrary server is open, in the sspeiche@435: sense that different resources of the same type may not all have the sspeiche@435: same set of predicates in their triples, and the set of predicates that sspeiche@435: are used in the state of any one resource is not limited to any pre-defined sspeiche@435: set. sspeiche@435:

sspeiche@435: sspeiche@435:

A LDP client MUST preserve all triples retrieved using HTTP GET that sspeiche@435: it doesn’t change whether it understands the predicates or not, when sspeiche@435: its intent is to perform an update using HTTP PUT.  The use of HTTP sspeiche@435: PATCH instead of HTTP PUT for update avoids this burden for clients sspeiche@435: [[RFC5789]]. sspeiche@435:

sspeiche@435:
sspeiche@435:
sspeiche@12: sspeiche@333:
sspeiche@333:

Linked Data Platform Resources

sspeiche@222: sspeiche@333:
sspeiche@333:

Informative

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 John@372: and processed by LDP 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: John@373:

The following sections define the conformance rules for LDP servers when serving LDPRs. John@413: This document also explains how a server paginates an LDPR's representation if it gets too big. John@413: Companion informative documents describe additional guidelines for use when interacting with LDPRs. John@373:

sspeiche@222: sspeiche@222:
sspeiche@222: sspeiche@333:
sspeiche@333:

General

sspeiche@12: sspeiche@435:

LDP servers MUST at least be HTTP/1.1 conformant servers [[!HTTP11]]. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP 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@435:

sspeiche@435: sspeiche@435:

LDP servers MAY host a mixture of LDPRs and non-LDPRs. For example, it John@372: is common for LDP servers to need to host binary or text resources sspeiche@435: that do not have useful RDF representations.

sspeiche@69: sspeiche@435:

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. sspeiche@435:

sspeiche@435: sspeiche@435:

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@435:

sspeiche@435: sspeiche@435:

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@435:

sspeiche@435: sspeiche@435:

LDP server responses MUST use entity tags (either sspeiche@435: weak or strong ones) as response ETag header values. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers John@434: exposing LDPRs 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@402: a link relation type of type (that is, rel='type') John@149: in all responses to requests made John@434: to the LDPR's HTTP Request-URI. sspeiche@435:

John@434:
John@434:

John@434: Note: John@434: The HTTP Link header is the method by which servers assert their support for the LDP specification John@434: on a specific resource in a way that clients can inspect dynamically at run-time. John@434: This is not equivalent to the John@434: presence of a (subject-URI, rdf:type, ldp:Resource) triple in an RDF resource. John@434: The presence of this header asserts that the server complies with the LDP specification's constraints on John@434: HTTP interactions with LDPRs, that is sspeiche@435: it asserts that the resource has Etags, has an RDF representation, and so on, John@434: which is not true of all Web resources served as RDF media types. John@434:

John@434:

John@434: Note: sspeiche@435: A LDP 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@434: individually inspected, in the absence of outside information. John@434:

John@434:
sspeiche@435: sspeiche@435:

LDP servers John@152: MUST NOT require LDP clients to implement inferencing in order to recognize the subset sspeiche@215: 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. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers MUST assign the default sspeiche@435: base-URI for [[!RFC3987]] relative-URI resolution to be the HTTP sspeiche@224: Request-URI when the resource already exists, and to the URI of the created resource when the request results sspeiche@224: in the creation of a new resource. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers MUST John@393: publish any constraints on LDP clients’ ability to John@402: create or update LDPRs, by adding a Link header with rel='describedby' John@393: [[!POWDER-DR]] to all responses to requests which fail due to violation of John@393: those constraints. For example, a server that refuses resource creation John@393: requests via HTTP PUT, POST, or PATCH would return this Link header on its John@393: 4xx responses to such requests. John@393: The same Link header MAY be provided on other responses. LDP neither John@393: defines nor constrains the representation of the link's target resource; John@393: as stated in [[POWDER-DR]], the target might (or might not) be a POWDER John@393: document. Natural language constraint documents are therefore permitted, John@393: although machine-readable ones facilitate better client interactions. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers SHOULD allow clients to retrieve large LDPRs in John@395: pages. John@395: See for additional requirements associated with paged resources. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers MAY John@395: treat any resource (LDPR or not) as a paged resource. John@395: See for additional details. sspeiche@435:

John@152: sspeiche@12:
sspeiche@12: sspeiche@333:
sspeiche@333:

HTTP GET

sspeiche@435:

LDP servers MUST support the HTTP GET Method for LDPRs. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers MUST support the HTTP response headers defined in sspeiche@228: . sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers MUST provide a text/turtle johnarwe@33: representation of the requested LDPR [[!TURTLE]]. sspeiche@435:

sspeiche@435: sspeiche@435:

In the absence of special knowledge of the application or domain, John@372: LDP clients MUST assume that any LDPR can have multiple values for rdf:type. sspeiche@435:

sspeiche@435: sspeiche@435:

In the absence of special knowledge of the application or domain, John@372: LDP clients MUST assume that the rdf:type values johnarwe@33: of a given LDPR can change over time. sspeiche@435:

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

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 John@393: new requirement to support that method, and [[!HTTP11]] makes it optional. John@393:

John@393:

Clients can create LDPRs via POST () or sspeiche@215: PUT () to a LDPC, see those John@393: sections for more details. Any server-imposed constraints on LDPR creation or update sspeiche@435: must be advertised to clients. sspeiche@417: John@393:

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

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 John@393: new requirement to support that method, and [[!HTTP11]] makes it optional. John@393: Any server-imposed constraints on LDPR creation or update sspeiche@435: must be advertised to clients. John@393:

sspeiche@12: sspeiche@435:

If a HTTP PUT is accepted on an existing resource, John@389: LDP 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. John@372: LDP servers MAY ignore server managed properties such as dcterms:modified sspeiche@61: and dcterms:creator if they are not under John@372: client control. Any LDP 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@435:

sspeiche@12: sspeiche@435:

John@389: If an otherwise valid HTTP PUT request is received John@389: that attempts to change triples the server does not allow clients to modify, John@389: LDP servers MUST John@389: respond with a 4xx range status code (typically John@389: 409 Conflict). John@389: LDP servers SHOULD provide a corresponding response body containing John@389: information about which triples could not be John@389: persisted. John@389: The format of the 4xx response body is not constrained by LDP. sspeiche@435:

John@389:
John@389: Informative note: Clients might provide triples equivalent to those already in the resource's state, John@389: e.g. as part of a GET/update representation/PUT sequence, and those PUT requests are intended to work as long as the John@389: server-controlled triples are identical on the GET response and the subsequent PUT request. John@389:
John@389: sspeiche@435:

LDP 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 John@372: its representation. LDP servers SHOULD require the HTTP If-Match header and HTTP ETags John@372: to detect collisions. LDP servers MUST respond with status code 412 John@122: (Condition Failed) if ETags fail to match when there are no other John@372: errors with the request [[!HTTP11]]. LDP 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@435:

sspeiche@435: sspeiche@435:

LDP 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@416: sspeiche@435:

sspeiche@435: sspeiche@435:

John@389: If an otherwise valid HTTP PUT request is received that contains triples the server John@389: chooses not to persist, e.g. unknown content, John@389: LDP servers MUST respond with an appropriate 4xx range status code John@389: [[HTTP11]]. John@389: LDP servers SHOULD provide a corresponding response body containing John@389: information about which triples could not be John@389: persisted. John@389: The format of the 4xx response body is not constrained by LDP. sspeiche@416: sspeiche@435:

sspeiche@435: sspeiche@435:

An LDP 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@435:

sspeiche@435: sspeiche@435:

LDP servers MAY choose to allow the creation of new resources using HTTP PUT. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers SHOULD allow clients to update resources without johnarwe@33: requiring detailed knowledge of server-specific constraints.   sspeiche@416: This is a consequence of the requirement to enable simple creation and modification of LPDRs. sspeiche@435:

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

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@12:

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

HTTP HEAD

John@395:

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@333: Thus, implementers should also carefully read sections sspeiche@333: and .

sspeiche@435:

LDP servers MUST support the HTTP HEAD method. sspeiche@435:

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

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 John@393: new requirement to support that method, and [[!HTTP11]] makes it optional. John@393: Any server-imposed constraints on LDPR creation or update sspeiche@435: must be advertised to clients. John@393:

sspeiche@435: sspeiche@435:

LDP servers SHOULD NOT allow clients to create new resources using PATCH. John@393: POST (to an LDPC) and/or PUT should be used as the standard way to create new LDPRs. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP 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. sspeiche@435:

sspeiche@186: sspeiche@12:
sspeiche@12: sspeiche@333:
sspeiche@333:

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: sspeiche@435:

LDP servers MUST support the HTTP OPTIONS method. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP 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. sspeiche@435:

John@158: John@158:
John@158: sspeiche@333:
sspeiche@333:

Paging

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

Introduction

sspeiche@134:

It sometimes happens that a sspeiche@134: resource is too large to reasonably transmit its representation in a John@412: single HTTP response. John@413: To address this problem, servers should support a technique called Paging.   John@412: When a client retrieves such a resource, the server includes in its response John@412: a link to the next part of the resource's state, at a URL of the server's choosing. John@395: The triples in the representation of the each page of an LDPR John@412: are typically a subset of the triples in the resource. sspeiche@134:

John@372:

LDP servers may respond to requests for a John@412: resource by returning the first page of the resource John@412: with a Link <next-page-URL>;type='next' header containing the URL for the next page. John@413: Clients inspect each response for the link header to see if additional pages John@413: are available; paging does not affect the choice of HTTP status code. John@413: Note that paging is lossy, as described in [[RFC5005]], and so (as stated there) John@412: clients should not make any assumptions about a set of pages being a complete or John@412: coherent snapshot of a resource's state.

sspeiche@134:

sspeiche@198: Looking at an example resource representing Example Co.'s customer John@395: relationship data, identified by the URI http://example.org/customer-relations, John@395: we’ll split the response across two pages.   John@412: The client John@413: retrieves http://example.org/customer-relations, and John@413: the server responds with status code 200 (OK) and the following representation: sspeiche@134:

sspeiche@198: eric@419:
# The following is the representation of
John@412: #    http://example.org/customer-relations
John@413: #    Requests on the URI will result in responses that include the following HTTP header
John@402: #       Link: <http://example.org/customer-relations?p=2>; rel='next'
John@412: #    This Link header is how clients discover the URI of the next page in sequence,
John@412: #    and that the resource supports paging.
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/>.
John@413: @base <http://example.org/customer-relations>.
sspeiche@134: 
John@413: <>
sspeiche@198:    a o:CustomerRelations;
sspeiche@198:    dcterms:title "The customer information for Example Co.";
John@413:    o:client <#JohnZSmith>, <#BettyASmith>, <#JoanRSmith>. 
sspeiche@134: 
John@413: <#JohnZSmith>
sspeiche@198:    a foaf:Person;
sspeiche@198:    o:status o:ActiveCustomer;
sspeiche@198:    foaf:name "John Z. Smith".
John@413: <#BettyASmith>
sspeiche@198:    a foaf:Person;
sspeiche@198:    o:status o:PreviousCustomer;
sspeiche@198:    foaf:name "Betty A. Smith".
John@413:  <#JoanRSmith>
sspeiche@198:    a foaf:Person;
sspeiche@198:    o:status o:PotentialCustomer;
sspeiche@198:    foaf:name "Joan R. Smith".
sspeiche@134: sspeiche@134:

John@413: Because the server includes a Link: <http://example.org/customer-relations?p=2>; rel='next' John@413: response header, the client knows that more data exists and where to find it. sspeiche@232: The server determines the size of the pages using application specific methods not defined John@402: within this specificiation. The next page link's target URI is also sspeiche@232: defined by the server and not this specification. sspeiche@232:

sspeiche@232:

John@413: The following example is the result of retrieving John@413: the next page; John@413: the server responds with status code 200 (OK) and the following representation: sspeiche@134:

sspeiche@134: eric@419:
# The following is the representation of
sspeiche@198: #  http://example.org/customer-relations?p=2
John@395: #
John@395: #  There is no "next" Link in the server's response, so this is the final page.
John@395: #
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/>.
John@413: @base <http://example.org/customer-relations>.
sspeiche@134: 
John@413: <>
John@413:    o:client <#GlenWSmith>, <#AlfredESmith>. 
sspeiche@198:  
John@413: <#GlenWSmith>
sspeiche@198:    a foaf:Person;
sspeiche@198:    o:status o:ActiveCustomer, o:GoldCustomer;
sspeiche@198:    foaf:name "Glen W. Smith".
sspeiche@134: 
John@413: <#AlfredESmith>
sspeiche@198:    a foaf:Person;
sspeiche@198:    o:status o:ActiveCustomer, o:BronzeCustomer;
John@413:    foaf:name "Alfred E. Smith".
John@413:  
sspeiche@134:

sspeiche@215: In this example, there are only two customers provided in the sspeiche@435: final page.  To indicate this is the last page, the server omits the Link: rel='next' John@395: header in its response. sspeiche@134:

John@412:

John@412: As mentioned above, retrieving all the pages offered by a server gives no guarantee to a client John@412: that it knows the entire state of the server. For example, after the server constructs the John@412: the first page representation, another John@412: actor could delete client#BettyASmith from the server. John@412:

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

HTTP GET

John@395:

In addition to the requirements set forth in on HTTP GET, John@395: LDP servers that support paging must John@395: also follow the requirements in this section for all paged resources John@395: and their associated single-page resources. John@395:

sspeiche@134: sspeiche@435:

LDP servers MAY John@413: add single-page resources to a John@413: paged resource's sequence over time, John@413: but SHOULD only add pages to the end of a sequence. sspeiche@435:

John@413:
Informative note: John@414: As a result, clients retrieving any single-page resource several times can observe its place in the sequence John@413: change as the state of the paged resource changes. John@413: For example, a nominally last page's server might provide a John@413: next page link when the page is retrieved. Similar situations arise when the page sequence crosses server boundaries; John@413: server A might host the initial portion of a sequence that links to the last page server A is aware of, John@413: hosted on server B, and server B might extend the sequence of pages. John@413:
sspeiche@435: sspeiche@435:

sspeiche@435: LDP servers MAY provide sspeiche@435: a first page link when responding to sspeiche@435: requests with any single-page resource as the Request-URI. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers MAY sspeiche@435: provide a last page link sspeiche@435: in responses to GET requests with any single-page resource as the Request-URI. sspeiche@435:

sspeiche@435:
sspeiche@435: sspeiche@435:

LDP servers MUST John@412: provide a next page link John@395: in responses to GET requests with any single-page resource John@395: other than the final page John@395: as the Request-URI. John@395: This is the mechanism by which clients can discover the URL of the next page. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers MUST NOT sspeiche@435: provide a next page link sspeiche@435: in responses to GET requests with the final single-page resource sspeiche@435: as the Request-URI. sspeiche@435: This is the mechanism by which clients can discover the end of the page sequence sspeiche@435: as currently known by the server. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers MAY sspeiche@435: provide a previous page link sspeiche@435: in responses to GET requests with any single-page resource sspeiche@435: other than the first page sspeiche@435: as the Request-URI. sspeiche@435: This is one mechanism by which clients can discover the URL of the previous page. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers MUST NOT sspeiche@435: provide a previous page link sspeiche@435: in responses to GET requests with the first single-page resource sspeiche@435: as the Request-URI. sspeiche@435: This is one mechanism by which clients can discover the beginning of the page sequence sspeiche@435: as currently known by the server. sspeiche@435:

sspeiche@435:
sspeiche@435: sspeiche@435:

LDP servers MUST John@395: provide an HTTP Link John@395: header whose target URI is http://www.w3.org/ns/ldp#Page, and whose link relation type is type [[!RFC5988]] John@395: in responses to GET requests with any single-page resource John@395: as the Request-URI. John@395: This is one mechanism by which clients know that the resource is one of a sequence of pages. sspeiche@435:

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

HTTP OPTIONS

John@158: John@395:

In addition to the requirements set forth in John@395: on HTTP OPTIONS, John@395: LDP servers that support paging must also John@395: follow the requirements in this section for all paged resources. John@395: Note that LDP only requires enough from OPTIONS John@395: for discovery of paging support on a resource, which is considerably John@395: less than is required for HTTP GET. John@395: This lowers server implementation effort. John@395:

John@395: John@174:
John@174: John@174:
John@174: John@174:
John@174: sspeiche@333:
sspeiche@333:

Linked Data Platform Containers

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

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 John@373: the membership triples that follow a consistent pattern John@373: (see the linked-to definition for the possible patterns). John@373: The membership triples of a container all John@373: have the same predicate, called the membership predicate, John@373: and either the subject or the object is also a consistent value John@373: – the remaining position of the membership John@373: triples (the one that varies) define the members of the container. John@373: In the simplest cases, the John@373: consistent value will be the LDPC resource's URI, 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 John@415: creating new resources and adding them to the list of sspeiche@104: members of a container. It goes on to explain how to learn about a set of related John@415: resources, regardless of how they were created or added to the container's membership. John@415: It also defines behavior when resources created using a container are later deleted; John@415: deleting containers removes membership information and John@415: possibly performs some cleanup tasks on unreferenced member resources.

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: eric@419:
# The following is the representation of
sspeiche@74: #    http://example.org/container1/
John@309: 
John@309: # @base <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@415:    ldp:containerResource <> ;
John@415:    ldp:containsRelation rdfs:member;
John@415:    ldp:insertedContentRelation 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 John@373: membership predicate is rdfs:member and the other John@373: consistent membership value is the container's John@373: URI, occurring in the subject position of the triples. John@373: 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 John@373: other than the container itself as the consistent membership value, and/or 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@233:
# The following is a partial representation of
sspeiche@87: #   http://example.org/netWorth/nw1
John@309: 
John@309: # @base <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@231: #   http://example.org/netWorth/nw1/
John@309: 
John@309: # @base <http://example.org/netWorth/nw1/>
sspeiche@87: @prefix ldp: <http://www.w3.org/ns/ldp#>.
sspeiche@231: @prefix dcterms: <http://purl.org/dc/terms/>.
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";
John@415:    ldp:containerResource <>;
John@415:    ldp:containsRelation o:asset;
John@415:    ldp:insertedContentRelation ldp:MemberSubject.
sspeiche@87: 
sspeiche@87: <liabilityContainer/>
sspeiche@87:    a ldp:Container;
sspeiche@87:    dcterms:title "The liabilities of JohnZSmith";
John@415:    ldp:containerResource <>;
John@415:    ldp:containsRelation o:liability;
John@415:    ldp:insertedContentRelation ldp:MemberSubject.
sspeiche@87: 
sspeiche@87: sspeiche@87:

The essential structure of the container is John@373: the same, but in this example, the consistent membership value (still in the subject position) 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: sspeiche@231:
# The following is the representation of
sspeiche@74: #   http://example.org/netWorth/nw1/assetContainer/
John@309: 
John@309: # @base <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;
John@415:    ldp:containerResource <http://example.org/netWorth/nw1>;
John@415:    ldp:containsRelation o:asset;
John@415:    ldp:insertedContentRelation ldp:MemberSubject.
sspeiche@12: 
sspeiche@12: <http://example.org/netWorth/nw1>
sspeiche@12:    a o:NetWorth;
sspeiche@72:    o:asset <a1>, <a2>.
sspeiche@12: John@373:

In this example, clients cannot correctly guess John@373: at the membership triples, so the example includes this information in sspeiche@12: triples whose subject is the LDPC resource itself. sspeiche@12:

sspeiche@12: sspeiche@435:

Retrieving Only Non-member Properties sspeiche@435:

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:

eric@419:

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
John@434: Link: <http://www.w3.org/ns/ldp/Container>; rel="type"
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@415:    ldp:containerResource <http://example.org/container1/>;
John@415:    ldp:containsRelation rdfs:member;
John@415:    ldp:insertedContentRelation 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.

sspeiche@435: sspeiche@435:
John@120: sspeiche@435:

Ordering

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@372: Order becomes more important for LDP 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@311: sort order no lower than all members on the previous page and John@311: sort order no higher than all the members on the next page; John@311: that is, it proceeds from low to high, but keep in mind that several John@311: consecutive pages might have members whose sort criteria are equal. 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:

eric@419:
# The following is the ordered representation of
sspeiche@74: #   http://example.org/netWorth/nw1/assetContainer/
John@309: 
John@309: # @base <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";
John@415:    ldp:containerResource <http://example.org/netWorth/nw1>;
John@415:    ldp:containsRelation o:asset;
John@415:    ldp:insertedContentRelation ldp:MemberSubject.
sspeiche@12: 
sspeiche@72: <?firstPage>
sspeiche@12:    a ldp:Page;
sspeiche@72:    ldp:pageOf <>;
John@309:    ldp:containerSortCriteria (<#SortValueAscending>).
John@126: 
John@126: <#SortValueAscending>
John@126:    a ldp:ContainerSortCriterion;
sspeiche@226:    ldp:containerSortOrder ldp:Ascending;
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;
John@309:    o:value 100.00 .
sspeiche@72: <a2>
sspeiche@12:    a o:Cash;
John@309:    o:value 50.00 .
sspeiche@72: <a3>
sspeiche@12:    a o:RealEstateHolding;
John@309:    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@427: example to sort the data prior to presentation on a user interface. Also sspeiche@427: as it is possible for a container to have as its members other containers, sspeiche@427: the ordering approach doesn't change as containers themselves are LDPRs and the sspeiche@427: properties from the domain model can be leveraged for the sort criteria. sspeiche@12:

sspeiche@435:
sspeiche@12:
sspeiche@12: sspeiche@333:
sspeiche@333:

General

johnarwe@33:

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

johnarwe@33: sspeiche@435:

Each Linked Data Platform Container MUST also be sspeiche@435: a conforming Linked Data Platform Resource. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers John@415: SHOULD use the rdfs:member predicate as an LDPC's membership predicate John@415: if there is no obvious predicate from an application vocabulary to use. John@373: The state of an LDPC includes information about which John@373: resources are its members, in the form of membership triples that John@373: follow a consistent pattern. The LDPC's state contains enough information for clients to discern John@373: the membership predicate, the other consistent membership John@415: value used in the container's membership triples (membership-constant-URI), John@415: and the position (subject or object) where those URIs John@415: occurs in the membership triples. John@373: Member resources can be John@373: any kind of resource identified by a URI, LDPR or otherwise. sspeiche@435:

sspeiche@435: sspeiche@435:

An LDPC representation MUST contain exactly one triple John@130: whose subject is the LDPC URI, John@415: whose predicate is the ldp:containerResource, John@415: and whose object is the LDPC's membership-constant-URI. John@415: Commonly the LDPC's URI is the membership-constant-URI, but LDP does not require this. sspeiche@435:

sspeiche@435: sspeiche@435:

An LDPC representation MUST contain exactly one triple John@130: whose subject is the LDPC URI, John@415: and whose predicate is either ldp:containsRelation or ldp:containedByRelation. John@130: The object of the triple is constrained by other sections, such as sspeiche@435: ldp:containsRelation or sspeiche@435: ldp:containedByRelation, based on the John@415: membership triple John@415: pattern used by the container. sspeiche@435:

sspeiche@435: sspeiche@435:

LDPCs whose membership triple John@415: pattern is ( membership-constant-URI , membership-predicate , member-derived-URI ) MUST John@415: contain exactly one triple John@415: whose subject is the LDPC URI, John@415: whose predicate is either ldp:containsRelation, John@415: and whose object is the URI of membership-predicate. sspeiche@435:

sspeiche@435: sspeiche@435:

LDPCs whose membership triple John@415: pattern is ( member-derived-URI , membership-predicate , membership-constant-URI ) MUST John@415: contain exactly one triple John@415: whose subject is the LDPC URI, John@415: whose predicate is either ldp:containedByRelation, John@415: and whose object is the URI of membership-predicate. sspeiche@435:

sspeiche@435:
sspeiche@435: sspeiche@435:

The representation of a LDPC MUST have an rdf:type John@386: of ldp:Container. Informative note: LDPCs John@386: might have additional types, like any RDF resource. sspeiche@435:

sspeiche@435: sspeiche@435:

LDPC representations SHOULD NOT use RDF container types rdf:Bag, johnarwe@33: rdf:Seq or rdf:List. sspeiche@435:

sspeiche@435: sspeiche@435:

LDPCs MUST contain one triple whose John@415: subject is the LDPC URI, John@415: whose predicate is ldp:insertedContentRelation, and John@415: whose object ICR describes how the member-derived-URI in sspeiche@435: the container's membership triples is chosen.

John@415:
    John@415:
  • John@415: LDP defines the URI ldp:MemberSubject for the common case where John@415: member-derived-URI is simply the URI assigned by the server to a John@415: document it creates; for example, if the client POSTs RDF content to a container John@415: that causes the container to create a new LDPR, ldp:MemberSubject says John@415: that the member-derived-URI is the URI assigned to the newly created LDPR. John@415: LDPCs MUST use the URI ldp:MemberSubject when the member-derived-URI John@415: is chosen in this way. John@415:
  • John@415:
  • John@415: In other cases, the member-derived-URI is taken from some triple sspeiche@435: ( S, P, O ) in the document supplied by the client as input to the create request; John@415: if ICR's value is P, then the member-derived-URI is John@415: O. LDP does not define the behavior when more than one triple containing John@415: the predicate P is present in the client's input. John@415: For example, if the client POSTs RDF content to a container John@415: that causes the container to create a new LDPR, and that content contains the triple sspeiche@416: ( <> , foaf:primaryTopic , mypet#Zaza ) John@415: foaf:primaryTopic says John@415: that the member-derived-URI is mypet#Zaza. John@415:
  • John@415:
sspeiche@435:
sspeiche@179: sspeiche@179: sspeiche@435:

LDP servers John@434: exposing LDPCs John@434: MUST advertise their LDP support by exposing a HTTP Link header John@434: with a target URI of http://www.w3.org/ns/ldp/Container, and John@434: a link relation type of type (that is, rel='type') John@434: in all responses to requests made John@434: to the LDPC's HTTP Request-URI. sspeiche@435: The notes on the corresponding LDPR constraint apply John@434: equally to LDPCs. sspeiche@435:

sspeiche@176: sspeiche@12:
sspeiche@12: sspeiche@333:
sspeiche@333:

HTTP GET

John@120: sspeiche@435:

The representation of a LDPC MUST contain a set of sspeiche@416: membership triples following one of the consistent John@373: patterns from that definition. John@373: The membership-constant-URI of the triples MAY be the container itself johnarwe@33: or MAY be another resource (as in the example).  See also sspeiche@435: section on LDPC membership predicates. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers MAY John@373: represent the members of a paged LDPC in a sequential sspeiche@416: order.  If the server does so, it MUST 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@415: sspeiche@435: See section for John@126: an example. sspeiche@435:

sspeiche@435: sspeiche@435:

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). sspeiche@416: The only literal 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. sspeiche@435:

sspeiche@435: sspeiche@435:

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 sspeiche@435: and whose object describes the order used. sspeiche@435: LDP defines two values, sspeiche@226: 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. sspeiche@435:

sspeiche@435: sspeiche@435:

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 sspeiche@435: and whose object identifies the collation used. sspeiche@435: 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@385: The ldp:containerSortCollation triple MUST be omitted for comparisons John@129: involving page-ordering values for which [[!SPARQL-QUERY]] does not use collations. sspeiche@435:

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

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 John@393: new requirement to support that method, and [[!HTTP11]] makes it optional. John@393: Any server-imposed constraints on creation or update sspeiche@435: must be advertised to clients. John@393:

johnarwe@37: sspeiche@435:

LDPC clients SHOULD create member resources by submitting a representation as John@372: the entity body of the HTTP POST to a known LDPC. If the resource was created successfully, LDP 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@435:

sspeiche@94: sspeiche@435:

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@435:

sspeiche@43: sspeiche@435:

LDP servers MAY accept an HTTP POST of non-RDF representations for sspeiche@435: creation of any kind of resource, for example binary resources. See AcceptPost section for John@395: details on how clients can discover whether a LDPC supports this behavior. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers that successfully create a new resource from a John@434: RDF representation in the request entity body MUST honor the client's requested interaction model(s). John@434: If any model cannot be honored, the server MUST fail the request. sspeiche@435:

John@434:
    sspeiche@435:
  • If the request header specifies an LDPR interaction model, then the server MUST create an LDPR.
  • sspeiche@435:
  • If the request header specifies an LDPC interaction model, then the server MUST create an LDPC. John@434:
  • John@434:
  • This specification does not constrain the server's behavior in other cases.
  • John@434:

    Note: A consequence of this is that LDPCs can be used to create LDPCs, if the server supports doing so.

    John@434:
sspeiche@435:
sspeiche@43: sspeiche@435:

LDP servers MUST accept a request entity body with a request header sspeiche@18: of Content-Type with value of text/turtle [[!TURTLE]]. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers SHOULD use the Content-Type request header sspeiche@435: to determine the representation format when the request has an entity body. sspeiche@435:

sspeiche@435: sspeiche@435:

In RDF representations, LDP 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.   sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers SHOULD assign the URI for the resource to be sspeiche@435: created using server application specific rules in the absence of a client hint. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers SHOULD allow clients to create new resources without sspeiche@12: requiring detailed knowledge of application-specific constraints. sspeiche@416: This is a consequence of the requirement to enable simple creation and modification of LPDRs. sspeiche@416: sspeiche@435:

sspeiche@435: sspeiche@435:

LDP 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. sspeiche@435:

John@115: sspeiche@435:

LDP servers that allow member creation via POST sspeiche@416: SHOULD NOT re-use URIs. sspeiche@435:

sspeiche@170: sspeiche@435:

Upon successful creation of a non-RDF and therefore non-LDPR member (HTTP status code of John@372: 201-Created and URI indicated by Location response header), LDP 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 sspeiche@222: and href to be the URI of the meta-resource [[!RFC5988]]. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP 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, sspeiche@231: if any, will have the "create new resource" semantics. 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. sspeiche@435:

John@169: sspeiche@435:

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@433: An LDPC that tracks members created through the LDPC MUST add a triple to the container 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. sspeiche@435:

John@433: sspeiche@435:

LDPCs John@433: whose ldp:insertedContentRelation triple has an object John@433: other than ldp:MemberSubject John@433: and that create new resources John@433: MUST add a triple to the container John@433: whose subject is the container's URI, John@433: whose predicate is ldp:created, and John@433: whose object is the newly created resource's URI (which will be different from sspeiche@435: the member-derived URI in this case). John@433: This ldp:created triple can be the only link from the container to the newly created John@433: resource in certain cases. sspeiche@435:

John@169: sspeiche@12:
sspeiche@12: sspeiche@333:
sspeiche@333:

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 John@393: new requirement to support that method, and [[!HTTP11]] makes it optional. John@393: Any server-imposed constraints on creation or update sspeiche@435: must be advertised to clients. John@393:

johnarwe@37: sspeiche@435:

LDP servers SHOULD NOT allow HTTP PUT to update a LDPC’s membership triples; sspeiche@12: if the server receives such a request, it SHOULD respond with a 409 sspeiche@12: (Conflict) status code. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers MAY allow updating LDPC non-membership properties using sspeiche@192: HTTP PUT on a corresponding non-member resource, which John@415: MAY exclude server-managed properties such as ldp:containerResource, ldp:containsRelation John@415: and ldp:containedByRelation. sspeiche@222: The describes the process by which clients sspeiche@222: use HTTP OPTIONS to discover whether the server offers such a resource, and if so its URL. sspeiche@435:

sspeiche@113: sspeiche@435:

LDP servers that allow member creation via PUT sspeiche@416: SHOULD NOT re-use URIs. sspeiche@435:

John@116: sspeiche@12:
sspeiche@12: sspeiche@333:
sspeiche@333:

HTTP DELETE

sspeiche@229:

This specification imposes the following new requirements on HTTP DELETE for LDPRs and LDPCs 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@435:

When a LDPC member resource originally created by the LDPC (for example, one whose representation sspeiche@238: was HTTP POSTed 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. sspeiche@435:

sspeiche@435: sspeiche@435:

When a LDP server successfully completes a DELETE request John@388: on a LDPC member resource, it MUST remove any John@388: membership triples associated with the deleted member resource identified by the Request-URI. sspeiche@435:

John@388:
John@388: Informative note: The LDP server might perform additional removal John@388: of member resources, as described in the normative references like [[HTTP11]]. 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@388:
sspeiche@435:
sspeiche@435: sspeiche@435:

When the conditions in previous section 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. sspeiche@435:

sspeiche@170: sspeiche@435:

When a LDPC member resource originally created by the LDPC (for example, one whose eric@418: representation was HTTP POSTed to the LDPC and then referenced by a membership triple) is deleted, and the LDPC server sspeiche@435: created an associated LDPR (see LDPC POST section), the LDPC server MUST also remove the associated LDPR it created. sspeiche@435:

sspeiche@170: sspeiche@12:
sspeiche@12: sspeiche@333:
sspeiche@333:

HTTP HEAD

John@395:

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

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

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 John@393: new requirement to support that method, and [[!HTTP11]] makes it optional. John@393: Any server-imposed constraints on LDPR creation or update sspeiche@435: must be advertised to clients. John@393:

sspeiche@171: sspeiche@435:

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

sspeiche@171:
sspeiche@171: sspeiche@333:
sspeiche@333:

HTTP OPTIONS

sspeiche@192:

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

sspeiche@171: sspeiche@435:

John@372: LDP 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; sspeiche@435: see section for sspeiche@435: examples.

sspeiche@192: In responses to OPTIONS requests with an LDPC as the Request-URI, John@372: LDP 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 sspeiche@226: http://www.w3.org/ns/ldp#nonMemberResource [[!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@434: header is present, then 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@402: would be Link: <?nonMemberProperties>;rel='http://www.w3.org/ns/ldp#nonMemberResource' sspeiche@435:
John@120: sspeiche@435:

When a LDPC creates a non-LDPR (e.g. binary) member (for example, one whose sspeiche@238: representation was HTTP POSTed to the LDPC and then referenced by a membership triple) it might create an associated LDPR to contain data about the sspeiche@435: non-LDPR (see LDPC POST section). 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 sspeiche@416: meta [[!RFC5988]]. sspeiche@416: sspeiche@416: sspeiche@416: sspeiche@435:

sspeiche@334:
John@174: sspeiche@334:
sspeiche@12: John@167:
John@175:

HTTP Header Definitions

John@167: sspeiche@333:
sspeiche@333:

The Accept-Post Response Header

John@167: sspeiche@221:

Feature At Risk

sspeiche@221:

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

sspeiche@221:
    John@413:
  • The addition of Accept-Post in this specification is pending John@372: advancement of an IETF draft John@372: that would fully include it, based on the Accept-Patch header's design from [[!RFC5789]]. Once LDP is in sspeiche@221: Candidate Recommendation, the LDP WG will make an assessment based on the status at IETF sspeiche@221: working with the W3C Director.
  • sspeiche@221:
sspeiche@221:
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@372: It is modelled after the Accept-Patch header defined in [[!RFC5789]]. John@167:

John@167: sspeiche@435:

The syntax for Accept-Post, using sspeiche@435: 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:
sspeiche@435:
John@167: sspeiche@435:

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. sspeiche@435:

John@167: sspeiche@435:

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:
sspeiche@435:
John@167: John@167:
John@167:
John@167: John@413: John@384: John@374:
John@374:

Notable information from normative references

John@386: John@374:
John@374:

sspeiche@416: Given that it's from base specs => important to understand, should be moved up before John@374: most of the normative sections IMO - renumbering hit again. John@374:

John@386:
John@374: John@386:
John@374:

John@374: While readers, and especially implementers, of LDP are assumed to understand the information in its normative John@374: references, the working group has found that certain points are particularly important to understand. John@374: For those thoroughly familiar with the referenced specifications, these points might seem obvious, yet John@374: experience has shown that few non-experts find all of them obvious. This section enumerates these topics; John@374: it is simply re-stating (informatively) information locatable via the normative references. sspeiche@435:

John@374: John@374:
John@374:

Architecture of the World Wide Web

John@386: Reference: [[!WEBARCH]] John@374: sspeiche@435:

LDPC membership is not exclusive; this means that the same resource John@386: (LDPR or not) can be a member of more than one LDPC. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers should not re-use URIs, John@374: regardless of the mechanism by which members are created (POST, PUT, etc.). John@386: Certain specific cases exist where a LDPC server might delete a resource and then later re-use the John@386: URI when it identifies the same resource, but only when consistent with Web architecture. John@374: While it is difficult to provide absolute implementation guarantees of non-reuse in all failure John@374: scenarios, re-using URIs creates ambiguities for clients that are best avoided. sspeiche@435:

John@374: John@374:
John@374: John@374:
John@374:

HTTP 1.1

John@386: Reference: [[!HTTP11]] John@374: sspeiche@435:

LDP servers can support representations beyond those John@374: necessary to conform to this specification. These John@374: could be other RDF formats, like N3 or NTriples, but non-RDF formats John@386: like HTML [[HTML401]] and JSON [[RFC4627]] would likely be common. John@386: HTTP content negotiation ([[HTTP11]] Section 12 - Content Negotiation) is used to select the format. sspeiche@435:

sspeiche@435: sspeiche@435:

LDPRs can be created, updated and deleted using methods not defined in John@374: this document, for example through application-specific means, SPARQL John@386: UPDATE, etc. [[SPARQL-UPDATE]], as long as those methods do not conflict with this specification's John@374: normative requirements. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers John@386: remove the resource identified by the Request-URI in response to a successful HTTP DELETE request. John@386: After such a request, a subsequent HTTP GET on the same John@386: Request-URI usually results in a 404 (Not found) or 410 (Gone) status John@386: code, although HTTP allows others. sspeiche@435:

John@374: sspeiche@435:

LDP servers can alter the state of other resources John@386: as a result of any HTTP request, especially when non-safe methods are used ([[HTTP11]] section 9.1). John@386: For example, it is acceptable for the server to John@374: remove triples from other resources whose subject or object is the John@386: deleted resource as the result of a successful HTTP DELETE request. John@386: It is also acceptable and common for LDP servers to John@386: not do this – the server's behavior can vary, so LDP clients cannot depend on it. sspeiche@435:

sspeiche@435: sspeiche@435:

LDP servers can implement HTTP PATCH John@386: to allow modifications, John@386: especially partial replacement, of their resources. No John@386: minimal set of patch document formats is mandated by this document or by the definition of PATCH [[RFC5789]]. sspeiche@435:

sspeiche@435: sspeiche@435:

John@386: When the Content-Type request header is absent from a request, John@386: LDP servers might infer the content type by inspecting the entity body contents [[HTTP11]]. sspeiche@435:

John@374: John@374:
John@374: John@374:
John@374:

RDF

John@374: Reference: [[RDF-CONCEPTS]] John@374: sspeiche@435:

The state of an LDPR John@386: can have triples with any subject(s). The URL used to retrieve the John@386: representation of an LDPR need not be the subject of any of its triples. sspeiche@435:

sspeiche@435: sspeiche@435:

The representation of an LDPC John@386: can include an arbitrary number of John@374: additional triples whose subjects are the members of the container, John@374: or that are from the representations of the members (if they have RDF John@386: representations). This allows a LDP server to provide clients with John@374: information about the members without the client having to do a GET John@386: on each member individually. See Container John@374: Member Information for additional details. sspeiche@435:

sspeiche@435: sspeiche@435:

The state of an LDPR can have more than one John@386: triple with a rdf:type predicate. sspeiche@435:

John@374: John@374:
John@374: John@412:
John@412:

Feed paging and archiving

John@412: Reference: [[RFC5005]] John@412: sspeiche@435:

A LDP client John@412: SHOULD NOT present paged resources as coherent or John@412: complete, or make assumptions to that effect. John@412: [[RFC5005]]. sspeiche@435:

John@412: John@412:
John@374: John@374:
John@374: sspeiche@428:
sspeiche@428:

Security Considerations

sspeiche@428: As with any protocol that is implemented leveraging HTTP, implementations should take advantage of the many sspeiche@428: security-related facilities associated with it and are not required to carry out LDP operations sspeiche@428: that may be in contradistinction to a particular security policy in place. For example, when faced with an sspeiche@428: unauthenticated request to replace system critical RDF statements in a graph through the PUT method, applications may sspeiche@428: consider responding with the 401 status code (Unauthorized), indicating that the appropriate authorization sspeiche@428: is required. In cases where authentication is provided fails to meet the requirements of a particular access control sspeiche@428: policy, the 403 status code (Forbidden) can be sent back to the client to indicate this failure to meet the sspeiche@428: access control policy. sspeiche@428:
sspeiche@428: John@372: 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@234: 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@274:

sspeiche@274: John@393: John@433: sspeiche@274: sspeiche@274: sspeiche@274:
Last Call Draft
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
sspeiche@274:
sspeiche@12: sspeiche@12: sspeiche@12: