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 theW3C technical reports index at http://www.w3.org/TR/.
This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.
This specification describes the useof HTTP for accessing, updating, creating and deleting resources fromservers that expose their resources as Linked Data. It provides clarificationsand extensions of the rules of Linked Data [LINKED-DATA]:
Use URIs as names for things
Use HTTP URIs so that people can look up those names
When someone looks up a URI, provide useful information, using the standards(RDF*,SPARQL)
Include links to other URIs, so that they can discover more things
This specification defines a special type ofLinked Data Platform Resource: aContainer. Containers are very useful in building application models involving collections of resources, often homogeneous ones. For example, universities offer a collection of classes and 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 (seesection5.2.3HTTP 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 specificationprovides the ability to break large resource representations into multiple paged responses [LDP-PAGING].
A program that establishes connections for the purpose of sending one or more HTTP requests [RFC7230].
Server
A program that accepts connections in order to service HTTP requests by sending HTTP responses.
The terms "client" and "server" refer only to the roles that these programs perform for a particular connection. The same program might act as a client on some connections and a server on others.
HTTP enables the use of intermediaries to satisfy requests through achain of connections. There are three common forms of HTTPintermediary: proxy, gateway, and tunnel. In some cases, a singleintermediary might act as an origin server, proxy, gateway, ortunnel, switching behavior based on the nature of each request.[RFC7230].
A HTTP resource whose state is represented in any way that conforms to the simple lifecyclepatterns and conventions insection4.Linked Data Platform Resources.
AnLDPC that adds the concept ofmembership, allowing the flexibility of choosing what form itsmembership triples take, and allowsmembers to be any resources [WEBARCH], not only documents.
AnLDPC similar to aLDP-DCthat is also capable of havingmembers whose URIs are basedon the content of itscontained documents rather than the URIs assigned to those documents.
The difference between the two is simply which position member-derived-URI occupies, which is usuallydriven by the choice ofmembership-predicate. Most predicates have a natural forward directioninherent in their name, and existing vocabularies contain useful examples that read naturally ineach direction.ldp:member anddcterms:isPartOf are representative examples.
Each linked container exposes properties (seesection5.2.1General)that allow clients to determine which pattern ituses, what the actualmembership-predicate andmembership-constant-URI values are, and (for containers that allow the creation of new members) what value is usedfor themember-derived-URI based on the client's input to the creation process.
The portion of an LDP's triples whose behavior is constrained directly by this specification; for example,membership triples and containment triples. This portion of resources' content doesnotinclude constraints imposed outside of LDP, for example by other specifications that the server happens to support, or byserver implementation decisions.
2.1Conventions Used in This Document
The namespace for LDP ishttp://www.w3.org/ns/ldp#.
Sample resource representations are provided intext/turtleformat [turtle].
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 wordsMAY,MUST,MUST NOT,RECOMMENDED,SHOULD, andSHOULD NOT are to be interpreted as described in [RFC2119].
The status of the sections of Linked Data Platform 1.0 (this document) is as follows:
1. Introduction:non-normative
2. Terminology:normative
3. Conformance:normative
4. Linked Data Platform Resources:normative
5. Linked Data Platform Containers:normative
6. Notable information from normative references:non-normative
Some of the rules defined in this document provideclarification and refinement of the base Linked Data rules [LINKED-DATA];others address additional needs.
The rules for Linked Data Platform Resources address basicquestions such as:
What resource representations should be used?
How is optimistic collision detection handled for updates?
What should client expectations be for changes to linked-to resources,such as type changes?
How can the server make it easy for the client to create resources?
Howdo I GET the representation of a large resource broken up into pages?
4.2.1.3LDP server responsesMUST use entity tags (either weak or strong ones) as responseETag header values, for responses that contain resource representations orsuccessful responses to HTTPHEAD requests.
4.2.1.5LDP serversMUST assign the default base-URI for [RFC3987] relative-URI resolution to be the HTTPRequest-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.
4.2.1.6LDP serversMUST publish any constraints onLDP clients’ ability to create or updateLDPRs, by adding a Link header withan appropriate context URI,a link relation ofhttp://www.w3.org/ns/ldp#constrainedBy,and a target URI identifying a set of constraints[RFC5988], to all responses to requests that fail due to violation of those constraints. For example, a server that refuses resource creation requests via HTTP PUT, POST, or PATCH would return thisLink header on its 4xx responses to such requests.The sameLink headerMAY 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.The appropriate context URI can vary based on the request's semantics and method;unless the response is otherwiseconstrained, the default (the effective request URI)SHOULD be used.
Per [RFC7231], this HTTP method is optional and this specification does not requireLDP servers to support it.When a LDP server supports this method, this specification imposes no new requirements forLDPRs.
Per [RFC7231], this HTTP method is optional and this specification does not requireLDP servers to support it.When a LDP server supports this method, this specification imposes the following new requirements forLDPRs.
4.2.4.1If a HTTPPUT is accepted on an existing resource,LDP serversMUSTreplace the entire persistent state of the identified resource withthe entity representation in the body of the request.LDP serversMAY ignoreLDP-server-managed properties,andMAY ignore other properties such asdcterms:modified anddcterms:creator if they arehandled specially by the server(for example, if the server overrides the value or supplies a default value).AnyLDP servers that wishto support a more sophisticated merge of data provided by the clientwith existing state stored on the server for a resourceMUST use HTTPPATCH, not HTTPPUT.
4.2.4.2LDP serversSHOULD allow clients to update resources withoutrequiring detailed knowledge ofserver-specific constraints. This is a consequence of the requirement to enable simple creation and modification ofLDPRs.
4.2.4.3If an otherwise valid HTTPPUT request is received that attempts to change propertiesthe server does not allow clients to modify,LDP serversMUST fail the request by responding with a 4xx range status code (typically409 Conflict).LDP serversSHOULD provide a corresponding response body containinginformation about which properties could not bepersisted.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 theLDP-server-managed propertiesare identical on the GET response and the subsequent PUT request.This is in contrast to other cases likewrite-once properties that the server does not allow clients to modify once set; properties like this are under client and/or server control but are not constrained by LDP, so they are notLDP-server-managed triples.
4.2.4.4If an otherwise valid HTTPPUT request is received that contains properties the server chooses not to persist, e.g. unknown content,LDP serversMUST respond with an appropriate 4xx range status code[RFC7231].LDP serversSHOULD provide a corresponding response body containinginformation about which properties could not bepersisted.The format of the 4xx response body is not constrained by LDP. LDP serversexpose these application-specific constraints as described insection4.2.1General.
4.2.4.5LDP clientsSHOULD use the HTTPIf-Matchheader and HTTPETags to ensure it isn’tmodifying a resource that has changed since the client last retrievedits representation.LDP serversSHOULD require the HTTPIf-Match header and HTTPETagsto detect collisions.LDP serversMUST respond with status code 412(Condition Failed) ifETags fail to match when there are no othererrors with the request [RFC7232].LDP servers that require conditional requestsMUST respond with status code 428(Precondition Required) when the absence of a precondition is the only reason for rejecting the request [RFC6585].
4.2.4.6LDP serversMAY choose to allow the creation of new resources using HTTPPUT.
4.2.5HTTP DELETE
Per [RFC7231], this HTTP method is optional and this specification does not requireLDP servers to support it.When a LDP server supports this method, this specification imposes no new blanket requirements forLDPRs.
Note that certain LDP mechanisms rely on HTTP headers, and HTTP generally requires thatHEAD responses include the same headers asGET responses. Thus, implementers should also carefully read sections4.2.2HTTP GET and4.2.8HTTP OPTIONS.
4.2.6.1LDP serversMUST support the HTTPHEAD method.
4.2.7HTTP PATCH
Per [RFC5789], this HTTP method is optional and this specification does not requireLDP servers to support it.When a LDP server supports this method, this specification imposes the following new requirements forLDPRs.
4.2.7.1LDP servers that supportPATCHMUSTinclude anAccept-Patch HTTP response header [RFC5789] on HTTPOPTIONSrequests, listing patch document media type(s) supported by the server.
4.2.8HTTP OPTIONS
This specification imposes the following new requirements on HTTPOPTIONS forLDPRs beyond those in [RFC7231]. Other sections of this specification, for examplePATCH,Accept-Post,add other requirements onOPTIONS responses.
4.2.8.1LDP serversMUST support the HTTPOPTIONS method.
4.3.1.1EachLDPRDF SourceMUST also be a conformingLDP Resource as defined insection4.2Resource, along with therestrictions in this section.LDP clientsMAY infer the following triple: onewhose subject is theLDP-RS, whose predicate isrdf:type, and whose object isldp:Resource, but there is no requirement to materialize this triple in theLDP-RS representation.
4.3.1.2LDP-RSs representationsSHOULD have at least onerdf:typeset explicitly. This makes the representations much more useful toclient applications that don’t support inferencing.
4.3.1.5LDP-RSsSHOULD reuse existing vocabularies instead of creatingtheir own duplicate vocabulary terms. In addition to this general rule, some specific cases arecovered by other conformance rules.
4.3.1.8In the absence of special knowledge of the application or domain,LDP clientsMUST assume that therdf:type valuesof a givenLDP-RS can change over time.
4.3.1.10LDP serversMUST NOT require LDP clients to implement inferencing in order to recognize the subsetof content defined by LDP. Other specifications built on top of LDP may require clientsto implement inferencing [rdf11-concepts]. The practical implication is that all content defined by LDPmust be explicitly represented, unless noted otherwise within this document.
4.3.1.13LDP clientsMUST be capable of processing responses formed by a LDP server that ignores hints,including LDP-defined hints.
4.3.2HTTP GET
4.3.2.1LDP serversMUST respond with a Turtlerepresentation of the requestedLDP-RS whenthe request includes anAccept header specifyingtext/turtle, unless HTTP content negotiationrequires a different outcome [turtle].
Non-normative note:In other words, Turtle must be returned byLDP servers in the usual case clients would expect (client requests it) as well as cases where the client requests Turtle or other media type(s), content negotiation results in a tie,and Turtle is one of the tying media types.For example, if theAccept header liststext/turtle as one of several media types with thehighest relative qualityfactor (q= value),LDP servers must respond with Turtle.HTTP servers in general are not required to resolve ties in this way, or to support Turtle at all, butLDP servers are.On the other hand, if Turtle is one of several requested media types,but another media type the server supports has a higher relative quality factor,standard HTTP content negotiation rules apply and the server (LDP or not) would not respond with Turtle.
4.3.2.2LDP serversSHOULDrespond with atext/turtlerepresentation of the requestedLDP-RS whenever theAccept request header is absent [turtle].
4.3.2.3LDP serversMUST respond with aapplication/ld+jsonrepresentation of the requestedLDP-RSwhen the request includes anAccept header, unless content negotiation orTurtle supportrequires a different outcome [JSON-LD].
4.4.1.2LDP servers exposing anLDP Non-RDF SourceMAY advertise this by exposing a HTTPLink headerwith a target URI ofhttp://www.w3.org/ns/ldp#NonRDFSource, anda link relation type oftype (that is,rel="type")in responses to requests made to theLDP-NR's HTTPRequest-URI [RFC5988].
5.Linked Data Platform Containers
5.1Introduction
This section is non-normative.
Many HTTP applications and sites have organizingconcepts that partition the overall space of resources into smallercontainers. Blog posts are grouped into blogs, wiki pages are groupedinto wikis, and products are grouped into catalogs. Each resourcecreated in the application or site is created within an instance ofone of these container-like entities, and users can list the existingartifacts within one. Containers answer some basic questions, whichare:
To which URLs can I POST to create new resources?
Where can I GET a list of existing resources?
How do I get information about the members along with the container?
Howcan I ensure the resource data is easy to query?
Howis the order of the container entries expressed? [LDP-PAGING]
This document defines the representation and behavior of containersthat address these issues. There are multiple types of containers definedto support a variety of use cases, all that support a base set of capabilities.The contents of a container isdefined by a set of triples in its representation (and state) calledthecontainment triples that follow a fixed pattern.Additional types of containers allow for the set of members of a container to bedefined by a set of triples in its representation calledthemembership triples that follow a consistent pattern(see the linked-to definition for the possible patterns). The membership triples of a container allhave the same predicate, called the membership predicate, and either the subject or the object is also a consistent value– the remaining position of the membershiptriples (the one that varies) define the members of the container. In the simplest cases, theconsistent value will be theLDPC resource's URI, but it does nothave to be. The membership predicate is also variable and will oftenbe a predicate from the server application vocabulary or theldp:member predicate.
In LDP 1.0, there exists a way for clients to request responses that contain onlypartial representations of the containers. Applications may define additional meansby which the response representations contain a filtered set of data and including (or excluding)additional details, those means are application-specific and not defined in this document.
This document includes a set of guidelines forcreating new resources and adding them to the list ofresources linked to a container. It goes on to explain how to learn about a set of relatedresources, 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 andpossibly performs some cleanup tasks on unreferenced member resources.
The following illustrates a very simplecontainer with only three members and some information about thecontainer (the fact that it is a container and a brief title):
Request tohttp://example.org/c1/:
Example 1
GET /c1/ HTTP/1.1Host: example.orgAccept: text/turtle
Response:
Example 2
HTTP/1.1 200 OKContent-Type: text/turtleDate: Thu, 12 Jun 2014 18:26:59 GMTETag: "8caab0784220148bfe98b738d5bb6d13"Accept-Post: text/turtle, application/ld+jsonAllow: POST,GET,OPTIONS,HEAD,PUTLink: <http://www.w3.org/ns/ldp#BasicContainer>; rel="type", <http://www.w3.org/ns/ldp#Resource>; rel="type"Transfer-Encoding: chunked@prefix dcterms: <http://purl.org/dc/terms/>.@prefix ldp: <http://www.w3.org/ns/ldp#>.<http://example.org/c1/> a ldp:BasicContainer; dcterms:title "A very simple container"; ldp:contains <r1>, <r2>, <r3>.
The preceding example is very straightforward: there are containment tripleswhose subject is the container, whose predicate isldp:contains, and whose objects are the URIs of the contained resources,and there is no distinction between member resources and contained resources. A POST to this container will create a new resourceand add it to the list of contained resources by adding a new containment tripleto the container. This type of container is called aLinked Data Platform Basic Container.
Sometimes you have to build on existing models incrementally, so you have fewer degrees offreedom in the resource model. In these situations, it can be useful to help clients mapLDP patterns onto existing vocabularies, or to include members not created via the container;LDP Direct Containersmeet those kinds of needs. Direct Containers allow membership triples to use a subjectother than the container itself as the consistent membership value, and/or to usea predicate from an application's domain model as the membership predicate.
Let's start with a pre-existing domain resource for a person's net worth, as illustrated immediately below, and then see how a Container resource can be applied in subsequent examples:
Request tohttp://example.org/netWorth/nw1/:
Example 3
GET /netWorth/nw1/ HTTP/1.1Host: example.orgAccept: text/turtle
In the preceding example, there is ardf:type ofo:NetWorth indicating theresource represents an instance of a person's net worth and ao:netWorthOf predicate indicating the associated person. There are two sets of same-subject, same-predicate triples; one for assets andone for liabilities. Existing domain-specific applications exist that depend on those types and predicates, so changing themincompatibly would be frowned upon.
It would be helpful to be able to use LDP patterns to manage the assets and liabilities-related triples.Doing so using a Basic Container would require duplicating much of the information with different types andpredicates, which would be onerous for large resources.Direct Containersprovide a middle ground, by giving LDP clients a way to map existing domain-specific resources to LDP'stypes and interaction models. In this specific example, it would be helpful to be able to manage the assets and liabilities triples consistently, for exampleby using LDP containers.One way to do this is to create two containers, one to manage assets and another liabilities, as separate HTTP resources. Existing clients have no need to interact with those containers,whereas LDP-enabled clients now have container URLs that they can interact with. The existingresource remains unchanged so that existing clients continue to function normally.This is illustrated in the set of related examples, one example per HTTP resource, starting withtheLDP-RS example from before:
Request tohttp://example.org/netWorth/nw1/:
Example 5
GET /netWorth/nw1/ HTTP/1.1Host: example.orgAccept: text/turtle
The structure of the net worth resource is completely unchanged, so any existing domain-specific applications continue to work without impact.LDP clients, on the other hand, have no way to understand that the asset andliability triples correspond in any way to LDP containers. For that, they need thenext two resources.
GET /netWorth/nw1/assets/ HTTP/1.1Host: example.orgAccept: text/turtle
Response:
Example 8
HTTP/1.1 200 OKContent-Type: text/turtleDate: Thu, 12 Jun 2014 18:26:59 GMTETag: "6df36eef2631a1795bfe9ab76760ea75"Accept-Post: text/turtle, application/ld+jsonAllow: POST,GET,OPTIONS,HEADLink: <http://www.w3.org/ns/ldp#DirectContainer>; rel="type", <http://www.w3.org/ns/ldp#Resource>; rel="type"Transfer-Encoding: chunked @prefix ldp: <http://www.w3.org/ns/ldp#>.@prefix dcterms: <http://purl.org/dc/terms/>.@prefix o: <http://example.org/ontology#>.<http://example.org/netWorth/nw1/assets/> a ldp:DirectContainer; dcterms:title "The assets of JohnZSmith"; ldp:membershipResource <http://example.org/netWorth/nw1/>; ldp:hasMemberRelation o:asset; ldp:contains <a1>, <a2>.
In the preceding asset container, the consistent membership value (membership-constant-URI, still in the subject position) is not thecontainer itself – it is the (separate) net worth resource. Themembership predicate iso:asset,from the domain model. A POST of an asset representation to the asset container will create a newasset and add it to net-worth's list ofassets by adding a new membership tripleto the resource and a containment triple to the container.
GET /netWorth/nw1/liabilities/ HTTP/1.1Host: example.orgAccept: text/turtle
Response:
Example 10
HTTP/1.1 200 OKContent-Type: text/turtleDate: Thu, 12 Jun 2014 18:26:59 GMTETag: "9f50da01f792281ddcfebe9788372d07"Link: <http://www.w3.org/ns/ldp#DirectContainer>; rel="type", <http://www.w3.org/ns/ldp#Resource>; rel="type"Accept-Post: text/turtle, application/ld+jsonAllow: POST,GET,OPTIONS,HEADTransfer-Encoding: chunked@prefix ldp: <http://www.w3.org/ns/ldp#>.@prefix dcterms: <http://purl.org/dc/terms/>.@prefix o: <http://example.org/ontology#>.<http://example.org/netWorth/nw1/liabilities/> 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 preceding liability container is completely analogous to the asset container above, simplymanaging liabilities instead of assets and using theo:liability predicate.
To add a another liability, a client would POST something like this to the liability container:
POST /netWorth/nw1/liabilities/ HTTP/1.1Host: example.orgAccept: text/turtleContent-Type: text/turtleContent-Length: 63@prefix o: <http://example.org/ontology#>.<> a o:Liability. # plus any other properties that the domain says liabilities have
Assuming the server successfully processes this request and assigns the URI<http://example.org/netWorth/nw1/liabilities/l4> to the newly created liability resource, at least two new triples would be added.
In the net worth resource,<http://example.org/netWorth/nw1/> o:liability <liabilities/l4>
In the liability container,<http://example.org/netWorth/nw1/liabilities/> ldp:contains <l4>.
You might wonder why we chose to create two new containers instead of makinghttp://example.org/netWorth/nw1/ itself a container.A single net worth container would be a fine design ifhttp://example.org/netWorth/nw1/had only assets or only liabilities (basically: only a single predicate to manage), but since it has separate predicates for assets and liabilities an ambiguity arises:it is unspecified whether a client's creation request (POST)should add a newo:asset oro:liability triple. Having separatehttp://example.org/netWorth/nw1/assets/ andhttp://example.org/netWorth/nw1/liabilities/ containersallows both assets and liabilities to be created and linked to the net-worth resource using the appropriate predicate. Similar ambiguities ariseif the client wishes to list the members and/or contained resources.
Continuing in the multiple containers direction, we will now extend our net worth example to add a container foradvisors (people) that have managed the assets and liabilities. We have decidedto identify these advisors with URLs that contain a fragment (hash) to representthese real-world resources, not the documents that describe them.
Request tohttp://example.org/netWorth/nw1/:
Example 13
GET /netWorth/nw1/ HTTP/1.1Host: example.orgAccept: text/turtle
Response:
Example 14
HTTP/1.1 200 OKContent-Type: text/turtleDate: Thu, 12 Jun 2014 18:26:59 GMTETag: "e8d129f45ca31848fb56213844a32b49"Link: <http://www.w3.org/ns/ldp#DirectContainer>; rel="type", <http://www.w3.org/ns/ldp#Resource>; rel="type"Allow: GET,OPTIONS,HEAD,PUT,DELETETransfer-Encoding: chunked@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#>.<http://example.org/netWorth/nw1/> a o:NetWorth; o:netWorthOf <http://example.org/users/JohnZSmith>; o:advisor <advisors/bob#me>, # URI of a person <advisors/marsha#me>. <advisors/> a ldp:IndirectContainer; dcterms:title "The asset advisors of JohnZSmith"; ldp:membershipResource <>; ldp:hasMemberRelation o:advisor; ldp:insertedContentRelation foaf:primaryTopic; ldp:contains <advisors/bob>, # URI of a document a.k.a. an information resource <advisors/marsha>. # describing a person
To handle this type of indirection, the triple with predicate ofldp:insertedContentRelation and object offoaf:primaryTopic informs clients that when POSTing to this container, they need to include a triple of theform(<>, foaf:primaryTopic, topic-URI) to inform the server which URI to use (topic-URI) in the new membership triple.
This type of container is referred to as aLDP Indirect Container. It is similar to anLDP Direct Container but it provides an indirection to add (via a create request) as a member any resource, including a URI representing a real-world object. Create requests toLDP Direct Containers can only add information resources [WEBARCH] - the documents they create - as members.
To add a another advisor, a client would POST something like this to the advisors container:
POST /netWorth/nw1/advisors/ HTTP/1.1Host: example.orgAccept: text/turtleContent-Type: text/turtleSlug: georgeContent-Length: 72@prefix foaf: <http://xmlns.com/foaf/0.1/>.@prefix o: <http://example.org/ontology#>.<> a o:Advisor; foaf:primaryTopic <#me>. # plus any other properties that the domain says advisors have
Assuming the server successfully processes this request and assigns the URI<http://example.org/netWorth/nw1/advisors/george> to the newly created advisor resource, at least two new triples would be added.
In the net worth resource,<http://example.org/netWorth/nw1/> o:advisor <advisors/george#me>
In the advisors container,<http://example.org/netWorth/nw1/advisors/> ldp:contains <george>
Fig.3Class relationship of types of Linked Data Platform Containers
The following table illustrates some differences betweenmembership andcontainment triples. For details on the normative behavior, see appropriate sectionsbelow.
The representation of a containerthat has many members will be large. There are several importantcases where clients need to access only the subset of the container's properties that are unrelated to member resources and unrelated to contained documents, forexample to determine the membership triple pattern and membership predicate of anLDP-DC. LDP calls theseminimal-container triples,because they are what remains when the container has zero members and zero contained resources.Since retrieving the whole container representation toget this information may be onerous for clients and cause unnecessaryoverhead on servers, we define a way to retrieve onlythese 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 HTTPPrefer header'sreturn=representation preference for this (seesection7.2Preferences on the Prefer Request Header for details).
The example listed here only showsa simple case where few minimal-container triples areretrieved. In real world situations more complex cases are likely, such as those that add other predicates tocontainers, for example providing validation information andassociatingSPARQL endpoints. [sparql11-query]
Here is an example requesting the minimal-container triples of acontainer identified by the URLhttp://example.org/container1/.
Request tohttp://example.org/container1/:
Example 17
GET /container1/ HTTP/1.1Host: example.orgAccept: text/turtlePrefer: return=representation; include="http://www.w3.org/ns/ldp#PreferMinimalContainer"
Response:
Example 18
HTTP/1.1 200 OKContent-Type: text/turtleETag: "_87e52ce291112"Link: <http://www.w3.org/ns/ldp#DirectContainer>; rel="type", <http://www.w3.org/ns/ldp#Resource>; rel="type"Accept-Post: text/turtle, application/ld+jsonAllow: POST,GET,OPTIONS,HEADPreference-Applied: return=representationTransfer-Encoding: chunked@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 facilityfor updating them via PUT without replacing the entire container's state.
Per [RFC7231], this HTTP method is optional and this specification does not requireLDP servers to support it.When a LDP server supports this method, this specification imposes the following new requirements forLDPCs.
Any server-imposed constraints on creation or updatemust be advertised to clients.
5.2.3.1LDP clientsSHOULD create member resources by submitting a representation asthe entity body of the HTTPPOST to a knownLDPC. If the resource was created successfully,LDP serversMUSTrespond with status code 201 (Created) and theLocationheader set to the new resource’s URL. Clients shall not expect any representation in the responseentity body on a 201 (Created) response.
If the request header specifiesaLDPC interaction model, then the serverMUST handle subsequent requests to the newly created resource's URI as if it is aLDPC.
This specification does not constrain the server's behavior in other cases.
Clients use the same syntax, that isHTTP Link headers, to specify the desired interaction modelwhen creating a resource as servers use to advertise it on responses.
Non-normative note: LDP assumes that the interaction model of a resource is fixed when the resource is created, and this is reflected in the language of the bullets. If an implementation were to extend LDP by allowing theinteraction model to vary after creation, that is viewed as a compatible extension to LDP and the statements above would constrain the default interaction model rather than saying that no other behavior is possible.
5.2.3.5LDP servers that allow creation ofLDP-RSs via POSTMUST allow clients to create new members by enclosing a request entity body with aContent-Type request header whose value istext/turtle [turtle].
5.2.3.6LDP serversSHOULD use theContent-Type request header to determine the request representation's format when the request has an entity body.
5.2.3.10LDP serversMAY allow clients to suggest the URI for a resourcecreated throughPOST, using the HTTPSlug header as defined in [RFC5023]. LDP addsno 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.
5.2.3.11LDP servers that allow member creation viaPOSTSHOULD NOT re-use URIs.
5.2.3.12Upon successful creation of anLDP-NR (HTTP status code of 201-Created and URI indicated byLocation response header),LDP serversMAY create an associatedLDP-RSto contain data about the newly createdLDP-NR. If a LDP server creates this associatedLDP-RS, itMUST indicateits location in the response by adding a HTTPLink header with a context URI identifying the newly createdLDP-NR (instead of the effective request URI),a link relation value ofdescribedby,and a target URI identifying the associatedLDP-RS resource [RFC5988].
5.2.3.13LDP servers that supportPOSTMUSTinclude anAccept-Post response header on HTTPOPTIONSresponses, listingPOST request media type(s) supported by the server.LDP only specifies the use ofPOST for the purpose of creating new resources, but a servercan acceptPOST requests with other semantics. While "POST to create" is a common interaction pattern, LDP clients are not guaranteed, even when making requests to a LDP server, that every successfulPOST request will result in the creation of a new resource; they must rely on out of band information for knowledge of whichPOST requests,if any, will have the "create new resource" semantics.This requirement on LDP servers is intentionally stronger than the one levied in theheader registration; it is unrealistic to expect all existing resourcesthat supportPOST to suddenly return a new header or for all new specifications constrainingPOST to be aware of its existence and require it, but it is a reasonable requirement for newspecifications such as LDP.
5.2.3.14LDP servers that allow creation ofLDP-RSs via POSTMUST allow clients to create new members by enclosing a request entity body with aContent-Type request header whose value isapplication/ld+json [JSON-LD].
5.2.4HTTP PUT
Per [RFC7231], this HTTP method is optional and this specification does not requireLDP servers to support it.When a LDP server supports this method, this specification imposes the following new requirements forLDPCs.
Any server-imposed constraints on creation or updatemust be advertised to clients.
5.2.4.1LDP serversSHOULD NOT allow HTTPPUT to update aLDPC’scontainment triples; if the server receives such a request, itSHOULD respond with a 409(Conflict) status code.
Per [RFC7231], this HTTP method is optional and this specification does not requireLDP servers to support it.When a LDP server supports this method, this specification imposes the following new requirements forLDPCs.
Note that certain LDP mechanisms rely on HTTP headers, and HTTP recommends thatHEAD responses include the same headers asGET responses.LDP servers must also include HTTP headerson responses toOPTIONS, seesection4.2.8HTTP OPTIONS.Thus, implementers supportingHEAD should also carefully read thesection5.2.2HTTP GET andsection5.2.8HTTP OPTIONS.
5.2.7HTTP PATCH
Per [RFC5789], this HTTP method is optional and this specification does not requireLDP servers to support it.When a LDP server supports this method, this specification imposes the following new requirements forLDPCs.
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, yetexperience 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.
6.2.3LDP servers remove the resource identified by theRequest-URI in response to a successful HTTPDELETE request.After such a request, a subsequent HTTPGET on the sameRequest-URI usually results in a 404 (Not found) or 410 (Gone) statuscode, although HTTP allows others.
6.2.4LDP servers can alter the state of other resources as a result of any HTTP request, especially when non-safe methods are used ([RFC7231] section 4.2.1). For example, it is acceptable for the server toremove triples from other resources whose subject or object is thedeleted resource as the result of a successful HTTPDELETE request. It is also acceptable and common forLDP servers tonot do this – the server's behavior can vary, so LDP clients cannot depend on it.
6.2.5LDP servers can implement HTTPPATCH to allow modifications,especially partial replacement, of their resources. Nominimal set of patch document formats is mandated by this document or by the definition ofPATCH [RFC5789].
6.2.6 When theContent-Type request header is absent from a request,LDP servers might infer the content type by inspecting the entity body contents ([RFC7231] section 3.1.1.5).
The LDP Working Group proposes incorporation of the features described in this section.
TheAccept-Post header has applicability beyond LDP as outlined in thisIETF draft [Accept-Post].
This specification introduces a new HTTP response headerAccept-Post usedto specify the document formats accepted by the server on HTTPPOST requests.It is modelled after theAccept-Patch header defined in [RFC5789].
7.1.1The syntax forAccept-Post, usingthe ABNF syntax defined in Section 1.2 of [RFC7231], is:
Accept-Post = "Accept-Post" ":" # media-range
TheAccept-Post header specifies a comma-separated list of media ranges (with optional parameters) as defined by [RFC7231], Section 5.3.2. TheAccept-Post header, in effect, uses the same syntax as the HTTPAccept header minus the optionalaccept-params BNF production,since the latter does not apply toAccept-Post.
7.1.2TheAccept-Post HTTP headerSHOULD appear in theOPTIONS response for any resourcethat supports the use of thePOST method. The presence of theAccept-Post header in response to any method is an implicitindication thatPOST is allowed on the resource identified by theRequest-URI. The presence of a specific document format inthis header indicates that that specific format is allowed onPOST requests to theresource identified by theRequest-URI.
7.1.3IANA Registration Template
The Accept-Post response header must be added to the permanent registry (see [RFC3864]).
This specification introduces new parameters on the HTTPPrefer request header'sreturn=representation preference [RFC7240], 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 theLDPC'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 thesepreferences on caching, as described in section 2 of [RFC7240].
Non-normative note: [RFC7240] recommends that server implementers include aPreference-Applied response header when the client cannot otherwise determine the server'sbehavior with respect to honoring hints from the response content.Examples illustrate some cases where the header is unnecessary.
WhereWSP is whitespace [RFC5234], andldp-uri-list is a double-quoted blank-delimited unordered set of URIs whose ABNF is given below.The generic preference BNF [RFC7240] 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 ofthe form:
ldp-uri-list = DQUOTE *WSP URI *[ 1*WSP URI ] *WSP DQUOTE
whereDQUOTE is a double quote [RFC5234], andURI is an absolute URI with an optionalfragment component [RFC3986].
WhereWSP andldp-uri-list are defined as above forinclude.
7.2.2.3When LDP servers receive a request with conflicting hints, this specification imposesno requirements on their behavior. They are free to reject the request, process itapplying some subset of the hints, or anything else appropriate to the server.[RFC7240] suggests treating similar requests as though none of the conflictingpreferences were specified.
7.2.2.4This specification defines the following URIs for clients to use withincludeandomit parameters. It assigns no meaning to other URIs, althoughother specificationsMAY do so.
# The following is the representation of# http://example.org/netWorth/nw1/assets/# @base <http://example.org/netWorth/nw1/assets/>.@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:marketValue 100.00 .<a2> a o:Cash; o:marketValue 50.00 .<a3> a o:RealEstateHolding; o:marketValue 300000 .
Clients interested only in information about the container (for example, which membership predicate it uses) might use this hint on aGET request:Prefer: return=representation; include="http://www.w3.org/ns/ldp#PreferMinimalContainer"
A server that honors this hint would return a following response containing the HTTP headerPreference-Applied: return=representation and this representation:
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 thisomit parameter value is equivalent to the precedinginclude parameter value, they may not be equivalent in the future due to the definition ofminimal-container triples.Clients should preferentially use theinclude parameter, as it more precisely communicates their needs.
ALDP 1.0 server that honors this hint would return the following response. Serversimplementing later versions of LDP might return substantively different responses.
Clients interested only in information about the container (for example, which membership predicate it uses) and its membership might use this hint on aGET request:Prefer: return=representation; include="http://www.w3.org/ns/ldp#PreferMembership http://www.w3.org/ns/ldp#PreferMinimalContainer".
A server that honors this hint would return (at least) the following response, and perhaps only this (it mightwell 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 predicatesdcterms:title ando:asset demonstrate this in the representation below), there is no need for the server to include aPreference-Applied response header in many common cases like a200 (OK) response. In other cases, like status code303,the header would still be required for the client to know that the303 response entityis a representation of the resource identified by theLocation URI instead of a short hypertext note (one with a hyperlink tothe same URI reference provided in theLocation header field [RFC7231]).
GET /netWorth/nw1/assets/ HTTP/1.1Host: example.orgAccept: text/turtlePrefer: return=representation; include="http://www.w3.org/ns/ldp#PreferMembership http://www.w3.org/ns/ldp#PreferMinimalContainer"
Response:
Example 25
HTTP/1.1 200 OKContent-Type: text/turtleETag: "_87e52ce291112"Link: <http://www.w3.org/ns/ldp#DirectContainer>; rel="type", <http://www.w3.org/ns/ldp#Resource>; rel="type"Accept-Post: text/turtle, application/ld+jsonAllow: POST,GET,OPTIONS,HEADPreference-Applied: return=representationTransfer-Encoding: chunked@prefix dcterms: <http://purl.org/dc/terms/>.@prefix ldp: <http://www.w3.org/ns/ldp#>.@prefix o: <http://example.org/ontology#>.<http://example.org/netWorth/nw1/assets/> 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>.
8.Link Relations
The intent is that these link relations will be registered with IANA per [RFC5988] section 6.2.1.
8.1describedby
The contents of this section were originally taken from [POWDER] appendix D, and then modified to comply with the current registration template.The pre-LDP IANA link relation registry entry fordescribedby refers to a different section of [POWDER] that was substantively updated inan erratum, and that section was notactually the normative definition of the link relation. Since we expect no update to [POWDER] that incorporates the erratum or fixes the registry link, this superseding registration approach is being taken.
The following Link Relationship will be submitted to IANA for review, approval, and inclusion in the IANA Link Relations registry.
Relation Name:
describedby
Description:
The relationshipA describedby B asserts that resource B provides a description of resource A. There are no constraints on the format or representation of either A or B, neither are there any further constraints on either resource.
Descriptions of resources may be socially sensitive, may require processing to be understood and may or may not not be accurate. Consumers of descriptive resources should be aware of the source and chain of custody of the data. Security considerations for URIs (Section 7 of RFC 3986) and IRIs (Section 8 of RFC 3987) apply to the extent that describing resources may affect consumers' decisions about how or whether to retrieve those resources.
The following people have been instrumental in providing thoughts, feedback,reviews, content, criticism and input in the creation of this specification:
Arnaud Le Hors (chair), Alexandre Bertails, Andrei Sambra, Andy Seaborne, Antonis Loizou, Ashok Malhotra, 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, Rob Sanderson, Roger Menday, Ruben Verborgh, Sandro Hawke, Serena Villata, Sergio Fernandez, Steve Battle, Steve Speicher, Ted Thibodeau, Tim Berners-Lee, Yves Lafon
B.Change History
This section is non-normative.
The change history is up to the editors to insert a brief summary ofchanges, ordered by most recent changes first and with heading from whichpublic draft it has been changed from.
