Copyright © 2014 W3C® (MIT, ERCIM, Keio, Beihang), All Rights Reserved. W3C liability, trademark and document use rules apply.
This document describes a set of best practices and simple approach for a read-write Linked Data architecture, based on HTTP access to web resources that describe their state using the RDF data model.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This is the 2nd Last Call for Comments where the Working Group has addressed all raised issues and as a result some significant changes have been made, see section B. Change History. Most notably the Working Group has decided to handle paging as an extension to LDP in a separate REC-track specification. [LDP-PAGING]
This document was published by the Linked Data Platform Working Group as a Last Call Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-ldp-comments@w3.org (subscribe, archives). The Last Call period ends 02 April 2014. All comments are welcome.
Publication as a Last Call Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
This is a Last Call Working Draft and thus the Working Group has determined that this document has satisfied the relevant technical requirements and is sufficiently stable to advance through the Technical Recommendation process.
This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
This section is non-normative.
This specification describes the use of HTTP for accessing, updating, creating and deleting resources from servers that expose their resources as Linked Data. It provides clarifications and extensions of the rules of Linked Data [LINKED-DATA]:
This specification discusses standard HTTP and RDF techniques used when constructing clients and servers that create, read, and write Linked Data Platform Resources. A companion document discusses best practices that you should use, and anti-patterns you should avoid, when constructing these clients and servers.
This specification defines a special type of Linked Data Platform Resource: a Container. Containers are very useful in building application models involving collections of resources, often homogeneous ones. For example, universities offer a collection of classes and have a collection of faculty members, each faculty member teaches a collection of courses, and so on. This specification discusses how to work with containers. Resources can be added to containers using standard HTTP operations like POST (see section 5.2.3 HTTP POST).
The intention of this specification is to enable additional rules and layered groupings of rules as additional specifications. The scope is intentionally narrow to provide a set of key rules for reading and writing Linked Data that most, if not all, other specifications will depend upon and implementations will support.
This specification provides some approaches to deal with large resources. An extension to this specification provides the ability to break large resource representations into multiple paged responses [LDP-PAGING].
For context and background, it could be useful to read Linked Data Platform Use Case and Requirements [LDP-UCR] and section 6. Notable information from normative references.
Terminology is based on W3C's Architecture of the World Wide Web [WEBARCH] and Hyper-text Transfer Protocol [HTTP11].
Any given program may be capable of being both a client and a server; our use of these terms refers only to the role being performed by the program for a particular connection, rather than to the program's capabilities in general. Likewise, any server may act as an origin server, proxy, gateway, or tunnel, switching behavior based on the nature of each request [HTTP11].
| membership-constant-URI | membership-predicate | member-derived-URI |
| member-derived-URI | membership-predicate | membership-constant-URI |
ldp:member and dcterms:isPartOf are representative examples.
Each linked container exposes properties (see section 5.2.1 General) that allow clients to determine which pattern it uses, what the actual membership-predicate and membership-constant-URI values are, and (for containers that allow the creation of new members) what value is used for the member-derived-URI based on the client's input to the creation process.
The namespace for LDP is http://www.w3.org/ns/ldp#.
Sample resource representations are provided in text/turtle
format [turtle].
Commonly used namespace prefixes:
@prefix dcterms: <http://purl.org/dc/terms/>. @prefix foaf: <http://xmlns.com/foaf/0.1/>. @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>. @prefix ldp: <http://www.w3.org/ns/ldp#>. @prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].
The status of the sections of Linked Data Platform 1.0 (this document) is as follows:
A conforming LDP client is a conforming HTTP client [HTTP11] that follows the rules defined by LDP in section 4. Linked Data Platform Resources and also section 5. Linked Data Platform Containers.
A conforming LDP server is a conforming HTTP server [HTTP11] that follows the rules defined by LDP in section 4. Linked Data Platform Resources when it is serving LDPRs, and also section 5. Linked Data Platform Containers when it is serving LDPCs. LDP does not constrain its behavior when serving other HTTP resources.
This section is non-normative.
Linked Data Platform Resources (LDPRs) are HTTP resources that conform to the simple patterns and conventions in this section. HTTP requests to access, modify, create or delete LDPRs are accepted and processed by LDP servers. Most LDPRs are domain-specific resources that contain data for an entity in some domain, which could be commercial, governmental, scientific, religious, or other.
Some of the rules defined in this document provide clarification and refinement of the base Linked Data rules [LINKED-DATA]; others address additional needs.
The rules for Linked Data Platform Resources address basic questions such as:
Additional non-normative guidance is available in the LDP Best Practices and Guidelines editor's draft that addresses questions such as:
The following sections define the conformance rules for LDP servers when serving LDPRs. Companion non-normative documents describe additional guidelines for use when interacting with LDPRs.
LDP-RS's representations may be too big, one strategy is to break up the response representation into client consumable chunks called pages. A separate LDP specification outlines the conformance rules around pagination [LDP-PAGING].
An LDP server manages two kinds of LDPRs, those resources who whose state is represented using RDF (LDP-RS) and those using other formats (LDP-NR). LDP-RSs have the unique quality that their representation is based on RDF, which addresses a number of use cases from web metadata, open data models, machine processable information, and automated processing by software agents [rdf11-concepts]. LDP-NRs are almost anything on the Web today: images, HTML pages, word processing documents, spreadsheets, etc. and LDP-RSs hold metadata associated with LDP-NRs in some cases.
The LDP-NRs and LDP-RSs are simply sub-types of LDPRs, as illustrated in Fig. 2 Class relationship of types of Linked Data Platform Resources.
Link header
with a target URI of http://www.w3.org/ns/ldp#Resource, and
a link relation type of type (that is, rel='type')
in all responses to requests made
to the LDPR's HTTP Request-URI.
Note: The HTTP
Linkheader is the method by which servers assert their support for the LDP specification on a specific resource in a way that clients can inspect dynamically at run-time. This is not equivalent to the presence of a (subject-URI,rdf:type,ldp:Resource) triple in an LDP-RS. The presence of this header asserts that the server complies with the LDP specification's constraints on HTTP interactions with LDPRs, that is it asserts that the resource has Etags, has an RDF representation, and so on, which is not true of all Web resources served as RDF media types.Note: An LDP server can host a mixture of LDPRs and other resources, and therefore there is no implication that LDP support advertised on one HTTP
Request-URImeans that other resources on the same server are also LDPRs. Each HTTPRequest-URIneeds to be individually inspected, in the absence of outside information.
Request-URI when the resource already exists, and to the URI of the created resource when the request results
in the creation of a new resource.
rel='describedby'
[RFC5988] to all responses to requests which fail due to violation of
those constraints. For example, a server that refuses resource creation
requests via HTTP PUT, POST, or PATCH would return this Link header on its
4xx responses to such requests.
The same Link header MAY be provided on other responses. LDP neither
defines nor constrains the representation of the link's target resource. Natural language
constraint documents are therefore permitted,
although machine-readable ones facilitate better client interactions.
GET Method for LDPRs.
Per [HTTP11], this HTTP method is optional and this specification does not require LDP servers to support it. When an LDP server supports this method, this specification imposes no new requirements for LDPRs.
Clients can create LDPRs via POST (section 5.2.3 HTTP POST) to an LDPC,
via PUT (section 4.2.4 HTTP PUT), or any other methods allowed
for HTTP resources. Any server-imposed constraints on LDPR creation or update
must be advertised to clients.
Per [HTTP11], this HTTP method is optional and this specification does not require LDP servers to support it. When an LDP server supports this method, this specification imposes the following new requirements for LDPRs.
Any server-imposed constraints on LDPR creation or update must be advertised to clients.
PUT is accepted on an existing resource,
LDP servers MUST
replace the entire persistent state of the identified resource with
the entity representation in the body of the request.
LDP servers MAY ignore server managed properties such as dcterms:modified
and dcterms:creator if they are not under
client control. Any LDP servers that wish
to support a more sophisticated merge of data provided by the client
with existing state stored on the server for a resource MUST use HTTP
PATCH, not HTTP PUT.
PUT request is received
that attempts to change properties the server does not allow clients to modify,
LDP servers MUST
respond with a 4xx range status code (typically
409 Conflict).
LDP servers SHOULD provide a corresponding response body containing
information about which properties could not be
persisted.
The format of the 4xx response body is not constrained by LDP.
Non-normative note: Clients might provide properties equivalent to those already in the resource's state, e.g. as part of a GET/update representation/PUT sequence, and those PUT requests are intended to work as long as the server-controlled properties are identical on the GET response and the subsequent PUT request.
PUT request is received that contains properties the server
chooses not to persist, e.g. unknown content,
LDP servers MUST respond with an appropriate 4xx range status code
[HTTP11].
LDP servers SHOULD provide a corresponding response body containing
information about which properties could not be
persisted.
The format of the 4xx response body is not constrained by LDP. LDP servers
expose these application-specific constraints as described in section 4.2.1 General.
If-Match
header and HTTP ETags to ensure it isn’t
modifying a resource that has changed since the client last retrieved
its representation. LDP servers SHOULD require the HTTP If-Match header and HTTP ETags
to detect collisions. LDP servers MUST respond with status code 412
(Condition Failed) if ETags fail to match when there are no other
errors with the request [HTTP11]. LDP servers that require conditional requests MUST respond with status code 428
(Precondition Required) when the absence of a precondition is the only reason for rejecting the request [RFC6585].
PUT.
Per [HTTP11], this HTTP method is optional and this specification does not require LDP servers to support it. When an LDP server supports this method, this specification imposes the following new requirements for LDPRs.
Additional requirements on HTTP DELETE of LDPRs within containers can be found in
section 5.2.5 HTTP DELETE.
Note that certain LDP mechanisms rely on HTTP headers, and HTTP generally requires that
HEAD responses include the same headers as GET responses.
Thus, implementers should also carefully read sections 4.2.2 HTTP GET
and 4.2.8 HTTP OPTIONS.
HEAD method.
Per [RFC5789], this HTTP method is optional and this specification does not require LDP servers to support it. When an LDP server supports this method, this specification imposes the following new requirements for LDPRs.
Any server-imposed constraints on LDPR creation or update must be advertised to clients.
PATCH MUST
include an Accept-Patch HTTP response header [RFC5789] on HTTP OPTIONS
requests, listing patch document media type(s) supported by the server.
This specification imposes the following new requirements on HTTP OPTIONS for LDPRs
beyond those in [HTTP11]. Other sections of this specification, for example
PATCH,
Accept-Post,
add other requirements on OPTIONS responses.
OPTIONS method.
OPTIONS request on the LDPR’s URL with the HTTP
Method tokens in the HTTP response header Allow.
The following section contains normative clauses for Linked Data Platform RDF Source.
ldp:RDFSource,
whose predicate is rdfs:subClassOf,
and whose object is ldp:Resource,
but there is no requirement to materialize this triple in the LDP-RS representation.
rdf:type
set explicitly. This makes the representations much more useful to
client applications that don’t support inferencing.
rdf:type
of only one of ldp:RDFSource for Linked Data Platform RDF Source.
Request-URI of the LDP-RS is typically the subject of most triples in the response.
rdf:type.
rdf:type values
of a given LDP-RS can change over time.
GET that
it doesn’t change whether it understands the predicates or not, when
its intent is to perform an update using HTTP PUT. The use of HTTP
PATCH instead of HTTP PUT for update avoids this burden for clients
[RFC5789].
Feature At Risk
The LDP Working Group proposes incorporation of the following clause to make LDP clients paging aware:
GET responses formed by an LDP server
that independently initiated paging, returning a page of representation instead of full resource
representation [LDP-PAGING].
text/turtle
representation of the requested LDP-RS [turtle].
The following section contains normative clauses for Linked Data Platform Non-RDF Source.
This section is non-normative.
Many HTTP applications and sites have organizing concepts that partition the overall space of resources into smaller containers. Blog posts are grouped into blogs, wiki pages are grouped into wikis, and products are grouped into catalogs. Each resource created in the application or site is created within an instance of one of these container-like entities, and users can list the existing artifacts within one. Containers answer some basic questions, which are:
This document defines the representation and behavior of containers
that address these issues. There are multiple types of containers defined
to support a variety of use cases, all that support a base set of capabilities.
The contents of a container is
defined by a set of triples in its representation (and state) called
the containment triples that follow a fixed pattern.
Additional types of containers allow for the set of members of a container to be
defined by a set of triples in its representation called
the membership triples that follow a consistent pattern
(see the linked-to definition for the possible patterns).
The membership triples of a container all
have the same predicate, called the membership predicate,
and either the subject or the object is also a consistent value
– the remaining position of the membership
triples (the one that varies) define the members of the container.
In the simplest cases, the
consistent value will be the LDPC resource's URI, but it does not
have to be. The membership predicate is also variable and will often
be a predicate from the server application vocabulary or the ldp:member predicate.
This document includes a set of guidelines for creating new resources and adding them to the list of resources linked to a container. It goes on to explain how to learn about a set of related resources, regardless of how they were created or added to the container's membership. It also defines behavior when resources created using a container are later deleted; deleting containers removes membership information and possibly performs some cleanup tasks on unreferenced member resources.
The following illustrates a very simple container with only three members and some information about the container (the fact that it is a container and a brief title):
# The following is the representation of # http://example.org/c1/ # @base <http://example.org/c1/> @prefix dcterms: <http://purl.org/dc/terms/>. @prefix ldp: <http://www.w3.org/ns/ldp#>. <> a ldp:BasicContainer; dcterms:title "A very simple container"; ldp:contains <r1>, <r2>, <r3>.
This example is very straightforward - there is the containment triple
with subject of the container, predicate of
ldp:contains and objects indicating the URIs of the contained resources.
A POST to this container will create a new resource
and add it to the list of contained resources by adding a new containment triple
to the container. This type of container is also referred to as
Linked Data Platform Basic Container.
Sometimes it is useful to use a subject other than the container itself as the consistent membership value, and/or to use a predicate from an application's domain model as the membership predicate. Let's start with a domain resource for a person's net worth, as illustrated below:
# The following is a partial representation of
# http://example.org/netWorth/nw1
# @base <http://example.org/netWorth/nw1/>
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix o: <http://example.org/ontology/>.
<>
a o:NetWorth;
o:netWorthOf <http://example.org/users/JohnZSmith>;
o:asset
<assetContainer/a1>,
<assetContainer/a2>;
o:liability
<liabilityContainer/l1>,
<liabilityContainer/l2>,
<liabilityContainer/l3>.From this example, there is a rdf:type of o:NetWorth indicating the
resource represents an instance of a person's net worth and o:netWorthOf predicate indicating
the associated person. There are two sets of same-subject, same-predicate pairings; one for assets and
one for liabilities. It would be helpful to be able to associate these multi-valued sets using a URL
for them to assist with managing these, this is done by associating containers with them as
illustrated in the set of related examples (one example per HTTP resource) below:
# The following is an elaborated representation of LDPR
# http://example.org/netWorth/nw1
# @base <http://example.org/netWorth/nw1/>.
@prefix ldp: <http://www.w3.org/ns/ldp#>.
@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix o: <http://example.org/ontology/>.
<>
a o:NetWorth;
o:netWorthOf <http://example.org/users/JohnZSmith>;
o:asset
<assetContainer/a1>,
<assetContainer/a2>;
o:liability
<liabilityContainer/l1>,
<liabilityContainer/l2>,
<liabilityContainer/l3>.# The following is an elaborated representation of LDPC # http://example.org/netWorth/nw1/assetContainer/ # @base <http://example.org/netWorth/nw1/assetContainer/>. @prefix ldp: <http://www.w3.org/ns/ldp#>. @prefix dcterms: <http://purl.org/dc/terms/>. @prefix o: <http://example.org/ontology/>. <> a ldp:DirectContainer; dcterms:title "The assets of JohnZSmith"; ldp:membershipResource <http://example.org/netWorth/nw1/>; ldp:hasMemberRelation o:asset; ldp:contains <a1>, <a2>.
# The following is an elaborated representation of LDPC # http://example.org/netWorth/nw1/liabilityContainer/ # @base <http://example.org/netWorth/nw1/liabilityContainer/>. @prefix ldp: <http://www.w3.org/ns/ldp#>. @prefix dcterms: <http://purl.org/dc/terms/>. @prefix o: <http://example.org/ontology/>. <> a ldp:DirectContainer; dcterms:title "The liabilities of JohnZSmith"; ldp:membershipResource <http://example.org/netWorth/nw1/>; ldp:hasMemberRelation o:liability; ldp:contains <l1>, <l2>, <l3>.
The essential structure of the container is
the same, but in this example, the consistent membership value
(membership-constant-URI, still in the subject position) is not the
container itself – it is a separate net worth resource. The
membership predicates are o:asset and o:liability – predicates
from the domain model. A POST of an asset representation to the asset container will create a new
asset and add it to the list of members by adding a new membership triple
to the resource and containment triple to the container. You might wonder why
http://example.org/netWorth/nw1 isn't made a container itself and POST
the new asset directly there. That would be a fine design if http://example.org/netWorth/nw1
had only assets, but if it has separate predicates for assets and liabilities,
that design will not work because it is unspecified to which predicate the POST
should add a membership triple. Having separate http://example.org/netWorth/nw1/assetContainer/
and http://example.org/netWorth/nw1/liabilityContainer/ container
resources allows both assets and liabilities to be created.
This type of container is referred to as an LDP Direct Container. LDP Direct Container adds the concept of membership and flexibilty on how to specify the membership triples.
As seen in the assetContainer/ example,
clients cannot correctly guess
at the membership triples, so the example includes this information in
triples whose subject is the LDPC resource itself.
Alternatively, servers may provide the net worth resource and supporting containers in a single response representations. When doing this, a preference would be for RDF formats that support multiple named graphs, one named graph for the net worth resource and then two others for asset and liability containers. This allows for the membership triples to be represented with the named graph for the net worth resource, while the containment triples would be represented within the liability and asset containers [rdf11-concepts]. Generally, the membership triples belong to the representation of an LDP-RS and the containment triples belong to the representation of the LDPC.
Additionally, we could extend our net worth example to include a container for advisors (people) that have managed the assets and liabilities. We have decided to identify these advisors with URLs that contain a fragment (hash) to represent these real-world resources, not the documents that describe them.
# The following is an elaborated representation of # http://example.org/netWorth/nw1 # Adding o:advisor but eaving off o:asset and o:liability for brevity. # @base <http://example.org/netWorth/nw1/> @prefix ldp: <http://www.w3.org/ns/ldp#>. @prefix dcterms: <http://purl.org/dc/terms/>. @prefix foaf: <http://xmlns.com/foaf/0.1/>. @prefix o: <http://example.org/ontology/>. <> a o:NetWorth; o:netWorthOf <http://example.org/users/JohnZSmith>; o:advisor <advisorContainer/bob#me>, <advisorContainer/marsha#me>. <advisorContainer/> a ldp:IndirectContainer; dcterms:title "The asset advisors of JohnZSmith"; ldp:membershipResource <>; ldp:hasMemberRelation o:advisor; ldp:insertedContentRelation foaf:primaryTopic; ldp:contains <advisorContainer/bob>, <advisorContainer/marsha>.
To handle this type of indirection, the triple with predicate of ldp:insertedContentRelation and object of
foaf:primaryTopic informs clients that when POSTing to this container, they need to include a triple of the
form (<>, foaf:primaryTopic, topic-URI) to inform the server which URI to use
(topic-URI) in the new membership triple.
This type of container is also referred to as a LDP Indirect Container. It is similar to an LDP Direct Container but it provides an indirection to add (via a create request) as member any resource, such as a URI representing a real-world object, that is different from the document that is created.
Fig. 3 Class relationship of types of Linked Data Platform Containers illustrates the 3 types: Container, Basic Container and Direct Container, along with their class relationship to types of LDPRs.
The following table illustrates some differences between membership and containment triples. For details on the normative behavior, see appropriate sections below.
| Completed Request | Effects | |
|---|---|---|
| Membership | Containment | |
| LDPR created in LDP-BC | New triple: (LDPC, ldp:contains, LDPR) | Same |
| LDPR created in LDP-DC | New triple links LDP-RS to created LDPR. LDP-RS URI may be same as LDP-DC | New triple: (LDPC, ldp:contains, LDPR) |
| LDPR created in LDP-IC | New triple links LDP-RS to content indicated URI | New triple: (LDPC, ldp:contains, LDPR) |
| LDPR is deleted | Membership triple may be removed | (LDPC, ldp:contains, LDPR) triple is removed |
| LDPC is deleted | Triples and member resources may be removed | Triples of form (LDPC, ldp:contains, LDPR) and contained LDPRs may be removed |
The representation of a container
that has many members will be large. There are several important
cases where clients need to access only the subset of the container's properties
that are unrelated to member resources and unrelated to contained documents, for
example to determine the membership triple pattern and membership predicate of an
LDP-DC. LDP calls these empty-container triples,
because they are what remains when the container has zero members and zero contained resources.
Since retrieving the whole container representation to
get this information may be onerous for clients and cause unnecessary
overhead on servers, we define a way to retrieve only
these property values (and more generally, a way to retrieve only the
subset of properties used to address other major clusters of use cases).
LDP adds parameters to the HTTP Prefer header's
return=representation preference for this
(see section 7.2 Preferences on the Prefer Request Header for details).
The example listed here only shows a simple case where few empty-container triples are retrieved. In real world situations more complex cases are likely, such as those that add other predicates to containers, for example providing validation information and associating SPARQL endpoints. [sparql11-query]
Here is an example requesting the empty-container triples of a
container identified by the URL http://example.org/container1/.
Request:
GET /container1 HTTP/1.1 Host: example.org Accept: text/turtle; charset=UTF-8 Prefer: return=representation; include="http://www.w3.org/ns/ldp#PreferEmptyContainer"
Response:
HTTP/1.1 200 OK Content-Type: text/turtle; charset=UTF-8 ETag: "_87e52ce291112" Content-Length: 325 Link: <http://www.w3.org/ns/ldp#Container>; rel="type" Preference-Applied: return=representation @prefix dcterms: <http://purl.org/dc/terms/>. @prefix ldp: <http://www.w3.org/ns/ldp#>. <http://example.org/container1/> a ldp:DirectContainer; dcterms:title "A Linked Data Platform Container of Acme Resources"; ldp:membershipResource <http://example.org/container1/>; ldp:hasMemberRelation ldp:member; ldp:insertedContentRelation ldp:MemberSubject; dcterms:publisher <http://acme.com/>.
LDP recommends using PATCH to update these properties, if necessary. It provides no facility for updating them via PUT without replacing the entire container's state.
The following section contains normative clauses for Linked Data Platform Container.
The Linked Data Platform does not define how clients discover LDPCs.
ldp:Container,
whose predicate is rdfs:subClassOf,
and whose object is ldp:RDFSource,
but there is no requirement to materialize this triple in the LDPC representation.
rdf:type
of only one of ldp:Container for Linked Data Platform Container.
Non-normative note: LDPCs
might have additional types, like any LDP-RS.
rdf:Bag,
rdf:Seq or rdf:List.
Link header
with a target URI matching the type of container (see below) the
server supports, and
a link relation type of type (that is, rel='type')
in all responses to requests made
to the LDPC's HTTP Request-URI.
LDP servers MAY provide additional HTTP Link: rel='type' headers.
The notes on the corresponding LDPR constraint apply
equally to LDPCs.
Valid container type URIs for rel='type' defined by this document are:
http://www.w3.org/ns/ldp#BasicContainer - for LDP Basic Containershttp://www.w3.org/ns/ldp#DirectContainer - for LDP Direct Containershttp://www.w3.org/ns/ldp#IndirectContainer - for LDP Indirect ContainersPer section 4.2.2 HTTP GET the HTTP GET method is required and additional requirements can be found in section 5.2.1 General.
Per [HTTP11], this HTTP method is optional and this specification does not require LDP servers to support it. When an LDP server supports this method, this specification imposes the following new requirements for LDPCs.
Any server-imposed constraints on creation or update must be advertised to clients.
POST to a known LDPC. If the resource was created successfully, LDP servers MUST
respond with status code 201 (Created) and the Location
header set to the new resource’s URL. Clients shall not expect any representation in the response
entity body on a 201 (Created) response.
POST request to an LDPC results in the creation of an LDPR, a
containment triple MUST be added to the state of LDPC. The
containment triple whose subject is the LDPC URI,
whose predicate is ldp:contains and whose object is the URI for the newly created document (LDPR).
The newly created LDPR appears as a contained resource of the LDPC until the
newly created document is deleted or removed by other methods. Other triples may be added as well.
POST of non-RDF representations
(LDP-NRs) for
creation of any kind of resource, for example binary resources. See the Accept-Post section for
details on how clients can discover whether an LDPC supports this behavior.
rdf:type triple indicating a type of LDPC).Note: A consequence of this is that LDPCs can be used to create LDPCs, if the server supports doing so.
Content-Type with value of text/turtle [turtle].
Content-Type request header
to determine the representation format when the request has an entity body.
POST, using the HTTP Slug header as defined in [RFC5023]. LDP adds
no new requirements to this usage, so its presence functions as a client hint to the server
providing a desired string to be incorporated into the server's final choice of resource URI.
POST
SHOULD NOT re-use URIs.
Location response header), LDP servers MAY create an associated
LDP-RS
to contain data about the newly created LDP-NR. If an LDPC server creates this associated LDP-RS it MUST indicate
its location on the HTTP response using the HTTP Link response header with link relation describedby
and href to be the URI of the associated LDP-RS resource [RFC5988].
POST MUST
include an Accept-Post response header on HTTP OPTIONS
responses, listing post document media type(s) supported by the server.
LDP only specifies the use of POST for the purpose of creating new resources, but a server
can accept POST requests with other semantics.
While "POST to create" is a common interaction pattern, LDP clients are not guaranteed, even when
making requests to an LDP server, that every successful POST request will result in the
creation of a new resource; they must rely on out of band information for knowledge of which POST requests,
if any, will have the "create new resource" semantics.
This requirement on LDP servers is intentionally stronger than the one levied in the
header registration; it is unrealistic to expect all existing resources
that support POST to suddenly return a new header or for all new specifications constraining
POST to be aware of its existence and require it, but it is a reasonable requirement for new
specifications such as LDP.
Per [HTTP11], this HTTP method is optional and this specification does not require LDP servers to support it. When an LDP server supports this method, this specification imposes the following new requirements for LDPCs.
Any server-imposed constraints on creation or update must be advertised to clients.
PUT to update an LDPC’s containment triples;
if the server receives such a request, it SHOULD respond with a 409
(Conflict) status code.
PUT
SHOULD NOT re-use URIs. For RDF representations (LDP-RSs),the created resource
can be thought of as an RDF named graph [rdf11-concepts].
Per [HTTP11], this HTTP method is optional and this specification does not require LDP servers to support it. When an LDP server supports this method, this specification imposes the following new requirements for LDPCs.
Non-normative note: The LDP server might perform additional actions, as described in the normative references like [HTTP11]. For example, the server could perform additional cleanup tasks for resources it knows are no longer referenced or have not been accessed for some period of time.
Note that certain LDP mechanisms
rely on HTTP headers, and HTTP generally requires that
HEAD responses include the same headers as GET responses. Also LDP servers must also include HTTP headers
on response to OPTIONS, see section 4.2.8 HTTP OPTIONS.
Thus, implementers supporting HEAD should also carefully read the
section 5.2.2 HTTP GET and section 5.2.8 HTTP OPTIONS.
Per [HTTP11], this HTTP method is optional and this specification does not require LDP servers to support it. When an LDP server supports this method, this specification imposes the following new requirements for LDPCs.
Any server-imposed constraints on LDPR creation or update must be advertised to clients.
PATCH as the preferred method for
updating an LDPC's empty-container triples.
This specification imposes the following new requirements on HTTP OPTIONS for LDPCs.
POSTed to the LDPC)
the LDP server might create an associated LDP-RS
to contain data about the non-LDPR (see LDPC POST section).
For LDP-NRs that have this associated LDP-RS, an LDPC server MUST provide an HTTP Link
header whose target URI is the associated LDP-RS, and whose link relation type is
describedby [RFC5988].
The following section contains normative clauses for Linked Data Platform Basic Container.
ldp:BasicContainer,
whose predicate is rdfs:subClassOf,
and whose object is ldp:Container,
but there is no requirement to materialize this triple in the LDP-BC representation.
The following section contains normative clauses for Linked Data Platform Direct Container.
ldp:BasicContainer,
whose predicate is rdfs:subClassOf,
and whose object is ldp:Container,
but there is no requirement to materialize this triple in the LDP-DC representation.
ldp:member predicate as an LDPC's membership predicate
if there is no obvious predicate from an application vocabulary to use..
The state of an LDPC includes information about which
resources are its members, in the form of membership triples that
follow a consistent pattern. The LDPC's state contains enough information for clients to discern
the membership predicate, the other consistent membership
value used in the container's membership triples (membership-constant-URI),
and the position (subject or object) where those URIs
occurs in the membership triples.
Member resources can be
any kind of resource identified by a URI, LDPR or otherwise.
ldp:membershipResource,
and whose object is the LDPC's membership-constant-URI.
Commonly the LDPC's URI is the membership-constant-URI, but LDP does not require this.
ldp:hasMemberRelation or ldp:isMemberOfRelation.
The object of the triple is constrained by other sections, such as
ldp:hasMemberRelation or
ldp:isMemberOfRelation, based on the
membership triple
pattern used by the container.
ldp:hasMemberRelation,
and whose object is the URI of membership-predicate.
ldp:isMemberOfRelation,
and whose object is the URI of membership-predicate.
ldp:insertedContentRelation , ldp:MemberSubject )
triple, but LDP imposes no requirement to materialize such a triple in the LDP-DC representation.
The value ldp:MemberSubject means that the
member-derived-URI is the URI assigned by the server to a
document it creates; for example, if the client POSTs content to a container
that causes the container to create a new LDPR, ldp:MemberSubject says
that the member-derived-URI is the URI assigned to the newly created LDPR.
POST request to an LDPC results in the creation of an LDPR,
the LDPC MUST update its membership triples to reflect that addition, and the resulting
membership triple MUST be consistent with any LDP-defined predicates it exposes.
A LDP Direct Container's membership triples MAY also be modified via
through other means.
The following section contains normative clauses for Linked Data Platform Indirect Container.
ldp:IndirectContainer,
whose predicate is rdfs:subClassOf,
and whose object is ldp:Container,
but there is no requirement to materialize this triple in the LDP-IC representation.
ldp:insertedContentRelation, and
whose object ICR describes how the member-derived-URI in
the container's membership triples is chosen.
The member-derived-URI is taken from some triple
( S, P, O ) in the document supplied by the client as input to the create request;
if ICR's value is P, then the member-derived-URI is
O. LDP does not define the behavior when more than one triple containing
the predicate P is present in the client's input.
For example, if the client POSTs RDF content to a container
that causes the container to create a new LDP-RS, and that content contains the triple
( <> , foaf:primaryTopic , bob#me )
foaf:primaryTopic says
that the member-derived-URI is bob#me.
ldp:insertedContentRelation triple has an object
other than ldp:MemberSubject
and that create new resources
MUST add a triple to the container
whose subject is the container's URI,
whose predicate is ldp:contains, and
whose object is the newly created resource's URI (which will be different from
the member-derived URI in this case).
This ldp:contains triple can be the only link from the container to the newly created
resource in certain cases.
This section is non-normative.
While readers, and especially implementers, of LDP are assumed to understand the information in its normative references, the working group has found that certain points are particularly important to understand. For those thoroughly familiar with the referenced specifications, these points might seem obvious, yet experience has shown that few non-experts find all of them obvious. This section enumerates these topics; it is simply re-stating (non-normatively) information locatable via the normative references.
This section is non-normative.
Reference: [WEBARCH]POST, PUT, etc.).
Certain specific cases exist where an LDPC server might delete a resource and then later re-use the
URI when it identifies the same resource, but only when consistent with Web architecture.
While it is difficult to provide absolute implementation guarantees of non-reuse in all failure
scenarios, re-using URIs creates ambiguities for clients that are best avoided.
This section is non-normative.
Reference: [HTTP11]Request-URI in response to a successful HTTP DELETE request.
After such a request, a subsequent HTTP GET on the same
Request-URI usually results in a 404 (Not found) or 410 (Gone) status
code, although HTTP allows others.
DELETE request.
It is also acceptable and common for LDP servers to
not do this – the server's behavior can vary, so LDP clients cannot depend on it.
PATCH
to allow modifications,
especially partial replacement, of their resources. No
minimal set of patch document formats is mandated by this document or by the definition of PATCH [RFC5789].
Content-Type request header is absent from a request,
LDP servers might infer the content type by inspecting the entity body contents [HTTP11].
This section is non-normative.
Reference: [rdf11-concepts]GET
on each member individually.
rdf:type predicate.
Feature At Risk
The LDP Working Group proposes incorporation of the features described in this section.
Accept-Post in this specification is pending
advancement of an IETF draft
that would fully include it, based on the Accept-Patch header's design from [RFC5789]. Once LDP is in
Candidate Recommendation, the LDP WG will make an assessment based on the status at IETF
working with the W3C Director.This specification introduces a new HTTP response header Accept-Post used
to specify the document formats accepted by the server on HTTP POST requests.
It is modelled after the Accept-Patch header defined in [RFC5789].
Accept-Post, using
the ABNF syntax defined in Section 2.1 of [HTTP11], is:Accept-Post = "Accept-Post" ":" 1#media-typeThe
Accept-Postheader specifies a comma-separated list of media- types (with optional parameters) as defined by [HTTP11], Section 3.7.
Accept-Post HTTP header SHOULD appear in the OPTIONS response for any resource
that supports the use of the POST method. The presence of the
Accept-Post header in response to any method is an implicit
indication that POST is allowed on the resource identified by the
Request-URI. The presence of a specific document format in
this header indicates that that specific format is allowed on POST requests to the
resource identified by the Request-URI.
The Accept-Post response header must be added to the permanent registry (see [RFC3864]).
Header field name: Accept-Post
Applicable Protocol: HTTP
Author/Change controller: W3C
Specification document: this specification
This specification introduces new parameters on the HTTP Prefer request header's
return=representation preference [Prefer], used optionally by clients to
supply a hint to help the server form a response that is most appropriate to
the client's needs. The LDP-defined parameters suggest the portion(s) of a resource's state that the
client application is interested in and, if received, is likely to be
processed. LDP Containers with large numbers of associated documents
and/or members will have large representations, and many client
applications may be interested in processing only a subset of the LDPC's
information (for example, only membership triples or only containment triples),
resulting in a potentially large savings in server, client,
and network processing.
Non-normative note: LDP server implementers should carefully consider the effects of these preferences on caching, as described in section 2 of [Prefer].
Non-normative note: [Prefer] recommends that server implementers include a
Preference-Applied response header when the client cannot otherwise determine the server's
behavior with respect to honoring hints from the response content.
Examples illustrates some cases where the header is unnecessary.
include hint defines a subset of an LDPR's content that a client
would like included in a representation.
The syntax for the include parameter of the
HTTP Prefer request header's
return=representation preference [Prefer] is:include-parameter = "include" *WSP "=" *WSP ldp-uri-listWhere
WSPis whitespace [RFC5234], andldp-uri-listis a double-quoted blank-delimited unordered set of URIs whose ABNF is given below. The generic preference BNF [Prefer] allows either a quoted string or a token as the value of a preference parameter; LDP assigns a meaning to the value only when it is a quoted string of the form:ldp-uri-list = DQUOTE *WSP URI *[ 1*WSP URI ] *WSP DQUOTEwhere
DQUOTEis a double quote [RFC5234], andURIis an absolute URI with an optional fragment component [RFC3986].
omit hint defines a subset of an LDPR's content that a client
would like omitted from a representation.
The syntax for the omit parameter of the
HTTP Prefer request header's
return=representation preference [Prefer] is:omit-parameter = "omit" *WSP "=" *WSP ldp-uri-listWhere
WSPandldp-uri-listare defined as above for include.
include
and omit parameters. It assigns no meaning to other URIs, although
other specifications MAY do so.| Containment triples | http://www.w3.org/ns/ldp#PreferContainment |
| Membership triples | http://www.w3.org/ns/ldp#PreferMembership |
| Empty-container triples | http://www.w3.org/ns/ldp#PreferEmptyContainer |
Non-normative note: all currently defined URIs are only coherent for LDP-RSs, and in fact only for LDPCs, however in the future it is possible that additional URIs with other scopes of applicability could be defined.
This section is non-normative.
If we assume a container like the one below:
# The following is the representation of # http://example.org/netWorth/nw1/assetContainer/ # @base <http://example.org/netWorth/nw1/assetContainer/>. @prefix dcterms: <http://purl.org/dc/terms/>. @prefix ldp: <http://www.w3.org/ns/ldp#>. @prefix o: <http://example.org/ontology/>. <> a ldp:DirectContainer; dcterms:title "The assets of JohnZSmith"; ldp:membershipResource <http://example.org/netWorth/nw1>; ldp:hasMemberRelation o:asset; ldp:insertedContentRelation ldp:MemberSubject. <http://example.org/netWorth/nw1> a o:NetWorth; o:asset <a1>, <a3>, <a2>. <a1> a o:Stock; o:value 100.00 . <a2> a o:Cash; o:value 50.00 . <a3> a o:RealEstateHolding; o:value 300000 .
Clients interested only in information about the container
(for example, which membership predicate it uses) might use this hint on a GET request:
Prefer: return=representation; include="http://www.w3.org/ns/ldp#PreferEmptyContainer"
A server that honors this hint would return a following response containing the HTTP header
Preference-Applied: return=representation
and this representation:
# The following is the ordered representation of # http://example.org/netWorth/nw1/assetContainer/ # @base <http://example.org/netWorth/nw1/assetContainer/>. @prefix dcterms: <http://purl.org/dc/terms/>. @prefix ldp: <http://www.w3.org/ns/ldp#>. @prefix o: <http://example.org/ontology/>. <> a ldp:DirectContainer; dcterms:title "The assets of JohnZSmith"; ldp:membershipResource <http://example.org/netWorth/nw1>; ldp:hasMemberRelation o:asset; ldp:insertedContentRelation ldp:MemberSubject.
Clients interested only in information about the container
(same as before) might use this hint instead:
Prefer: return=representation; omit="http://www.w3.org/ns/ldp#PreferMembership http://www.w3.org/ns/ldp#PreferContainment". Note: Treating the two as equivalent is not recommended. While today this
omit parameter value is equivalent to the preceding include parameter value,
they may not be equivalent in the future
due to the definition of empty-container triples.
Clients should preferentially use the include parameter, as it more precisely communicates their needs.
A LDP 1.0 server that honors this hint would return the following response. Servers implementing later versions of LDP might return substantively different responses.
# The following is the ordered representation of # http://example.org/netWorth/nw1/assetContainer/ # @base <http://example.org/netWorth/nw1/assetContainer/>. @prefix dcterms: <http://purl.org/dc/terms/>. @prefix ldp: <http://www.w3.org/ns/ldp#>. @prefix o: <http://example.org/ontology/>. <> a ldp:DirectContainer; dcterms:title "The assets of JohnZSmith"; ldp:membershipResource <http://example.org/netWorth/nw1>; ldp:hasMemberRelation o:asset; ldp:insertedContentRelation ldp:MemberSubject.
Clients interested only in information about the container
(for example, which membership predicate it uses) and its membership might use this hint on a GET request:
Prefer: return=representation; include="http://www.w3.org/ns/ldp#PreferMembership http://www.w3.org/ns/ldp#PreferEmptyContainer"
A server that honors this hint would return
(at least) the following response, and perhaps only this (it might
well omit containment triples if they are not specifically requested).
In cases like this example, where a client can detect from the content that its hints were honored
(the presence of the predicates dcterms:title and o:asset demonstrate this in the representation below),
there is no need for the server to include a Preference-Applied response header
in many common cases like a 200 (OK) response. In other cases, like status code 303,
the header would still be required for the client to know that the 303 response entity
is a representation of the resource identified by the Location URI
instead of a short hypertext note (one with a hyperlink to
the same URI reference provided in the Location header field [HTTPBIS-SEMANTICS]).
# The following is the representation of # http://example.org/netWorth/nw1/assetContainer/ # @base <http://example.org/netWorth/nw1/assetContainer/>. @prefix dcterms: <http://purl.org/dc/terms/>. @prefix ldp: <http://www.w3.org/ns/ldp#>. @prefix o: <http://example.org/ontology/>. <> a ldp:DirectContainer; dcterms:title "The assets of JohnZSmith"; ldp:membershipResource <http://example.org/netWorth/nw1>; ldp:hasMemberRelation o:asset; ldp:insertedContentRelation ldp:MemberSubject. <http://example.org/netWorth/nw1> a o:NetWorth; o:asset <a1>, <a3>, <a2>.
This section is non-normative.
As with any protocol that is implemented leveraging HTTP, implementations should take advantage of the many security-related facilities associated with it and are not required to carry out LDP operations that may be in contradistinction to a particular security policy in place. For example, when faced with an unauthenticated request to replace system critical RDF statements in a graph through the PUT method, applications may consider responding with the 401 status code (Unauthorized), indicating that the appropriate authorization is required. In cases where authentication is provided fails to meet the requirements of a particular access control policy, the 403 status code (Forbidden) can be sent back to the client to indicate this failure to meet the access control policy.
This section is non-normative.
The following people have been instrumental in providing thoughts, feedback, reviews, content, criticism and input in the creation of this specification:
Alexandre Bertails, Andrei Sambra, Andy Seaborne, Antonis Loizou, Arnaud Le Hors, Ashok Malhota, Bart van Leeuwen, Cody Burleson, David Wood, Eric Prud'hommeaux, Erik Wilde, Henry Story, John Arwe, Kevin Page, Kingsley Idehen, Mark Baker, Martin P. Nally, Miel Vander Sande, Miguel Esteban Gutiérrez, Nandana Mihindukulasooriya, Olivier Berger, Pierre-Antoine Champin, Raúl García Castro, Reza B'Far, Richard Cyganiak, Roger Menday, Ruben Verborgh, Sandro Hawke, Serena Villata, Sergio Fernandez, Steve Battle, Steve Speicher, Ted Thibodeau, Tim Berners-Lee, Yves Lafon
This section is non-normative.
Summary of notable changes from previous public working draft.