2.Best Practices
2.1Predicate URIs should be HTTP URLs
URIs are used to uniquely identify resources and URLs are usedto locate resources on the Web. That is to say that a URL isexpected to resolve to an actual resource, which can be retrievedfrom the host. A URI, on the other hand, may also be a URL, but itdoes not have to be; it may refer to something that has noretrievable representation.
One of the fundamental ideas behind Linked Data is that thethings referred to by HTTP URIs can actually be looked up("dereferenced"). This important principle was originallyoutlined by Tim Berners-Lee as rule #2 of "the four rules"for linking data [LD-DI]. It is therefore ideal that predicateURIs identify resources with representations that are retrievable. LDPservers should at least provide [RDF-SCHEMA] representations ofthese predicates where possible.
Of course, it is also a common practice to reuse propertiesfrom open vocabularies that are publicly available. In this case,implementers have no control over the result when attempting todereference the URI. For this reason, publishers who wish to maketheir vocabularies useful for linking data should strive to providea retrievable representation of the properties their vocabulariesdefine. Consequently, implementers are also expected to use thispractice as a benchmark for which to judge the efficacy of avocabulary's use for linking data.
2.2Use and include the predicate rdf:type to represent theconcept of type in LDPRs
It is often very useful to know the type (class) of an LDPR, thoughit is not essential to work with the interaction capabilities thatLDP offers. Still, to make data more useful in the broadest context,type should be explicitly defined using therdf:typepredicate defined by [RDF-SCHEMA].
This provides a way for clients to easily determine the type(s)of a resource without having to perform additional processing ormake additional HTTP requests. For example, clients that cannotinfer the type because they do not support inferencing can benefitfrom this explicit declaration.
Example 1: Representation of an LDPR with explicit declaration of rdf:type
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.@prefix contact: <http://www.w3.org/2000/10/swap/pim/contact#>.<http://www.w3.org/People/EM/contact#me> a contact:Person; contact:fullName "Eric Miller"; contact:mailbox <mailto:em@w3.org>; contact:personalTitle "Dr.".
The token 'a' in the predicate position of a Turtle triple represents the IRI http://www.w3.org/1999/02/22-rdf-syntax-ns#type. In the example above, therefore,a contact:Person is the same asrdf:type contact:Person or the fully-qualified form,<http://www.w3.org/1999/02/22-rdf-syntax-ns#type> contact:Person.
2.3Use relative URIs
Relative URIs are useful to the Linked Data Platform in muchthe same ways that relative URLs [RFC3986] have been useful totraditional web systems. Since the things referred to by Linked DataURIs should provide a retrievable representation [LD-DI], LinkedData URIs are usually also URLs; they locate rather than justidentify. As such, the utilitarian value of relative URLs stillapplies; especially since the LDP Container model promoteshierarchical representations.
Implementers should therefore align the function of relativeURIs in LDP with those of traditional relative URLs where possibleand appropriate. Aside from giving developers the comfort andconvenience of familiarity, they provide many of the sameadvantages.
- Relative URIs are shorter than absolute URIs.
In many cases, this can aid development by making code andRDF easier for humans to read. It can also reduce the size ofpayloads, which in turn, can reduce network traffic and stress onservers, while improving response times for end-users.
Example 2: Representation of http://example.org/container1/ with absolute URIs
@prefix dcterms: <http://purl.org/dc/terms/>.@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.@prefix ldp: <http://www.w3.org/ns/ldp#>.<http://example.org/container1/> a a ldp:Container, ldp:BasicContainer; dcterms:title "A very simple container"; ldp:contains <http://example.org/container1/member1>, <http://example.org/container1/member2>, <http://example.org/container1/member3>.
Example 3: Representation of http://example.org/container1/ with relative URIs
@prefix dcterms: <http://purl.org/dc/terms/>.@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.@prefix ldp: <http://www.w3.org/ns/ldp#>.<> a a ldp:Container, ldp:BasicContainer; dcterms:title "A very simple container"; ldp:contains <member1>, <member2>, <member3> .
- Relative URIs can make resources more portable.
- When information which is already known from the context ofthe base resource's retrieval is omitted, there can be lessinformation to modify when its location changes. This can makecopying resources to new servers or to a new position in acontainment hierarchy easier; in the preceding example, a process that clones just the container need not adjust any ofits member URIs.
- Relative URIs are convenient during development.
- During development the scheme and network locationinformation in a URI may either be unknown or likely to change. Thecommonly used 'localhost' for example, is better expressed by theserver name or a domain name. Developers often experience lesshassle by omitting this information. Additionally, the hierarchyimplied by a relative URI may be mimicked in a server file system,which can help developers find and work with information, even whenthe server isn't running.
- Relative URIs support arbitrary, machine-generated URIs.
- RESTful URLs are often defined by a pattern of hierarchical'collections', which clients interact with in very logical ways.For example, when creating a new resource the client does nottypically know the name of the resource until after a successfulPOST to a collection's URL. A POST to
/people/for example, may create the resource/people/1. LDP Containers are such collections whose URIs can benefit fromthe same model, which in some implementations, may actually becrucial.
2.4Avoid dot-segments in URIs of POSTed content or use with caution
The semantics of dot-segments (eg.../) within relative URIs may be implied by other specifications and by common historical use, but in the case of LDP, additional consideration is required.
The LDP specification states that...
LDP serversMUST assign the default base-URI for [RFC3987] relative-URI resolution to be the HTTP 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.
It follows from this definition that use of../ and other non-null relative URI constructs during POST can cause the posted content to be referring to resources in a manner the client might not be able to predict. Dot-segments should therefore be avoided unless the client knows specifically what can be expected of the given implementation and/or deployment.2.5Represent container membership with hierarchical URIs
Hierarchical URIs are good for containers because they enablethe use of relative URIs. They also promote easy interaction withresources that are modeled to represent parent-child relationshipswhere the child logically belongs to the parent.
One example of such a model can be found in the case of theoslc_cm:attachmentcontainer from the vocabularies defined by theOpen Service for LifecycleManagement (OSLC) community. The OSLC defines specifications andvocabularies that are well-aligned to LDP. A resource in an OSLCcompliant change management system such as an issue or bug trackermay have attachments represented by theoslc_cm:attachmentcontainer. The URI for such a container might be represented asfollows:
http://example.org/bugs/2314/attachments/
From this URI, the URI of the parent resource which holds theattachments is easily discerned. The base container for othersibling resources can be discerned by moving up the hierarchy, whichis implied by the URI. Meta-data or binary content might be fetchedfurther down the hierarchy by using a URI such as the following:
http://example.org/bugs/2314/attachments/1
In addition to making the use of relative URIs possible,hierarchical URIs make interacting with resources easier for users becausethey represent the actual structure of the underlying graph.Software agents (code acting on behalf of users [WEBARCH]) must be carefulbefore exploiting the structure of URIs, considering historical problemswhen doing so ([WEBARCH], [metaDataInURI]).
2.6Include a trailing slash in container URIs
When representing container membership with hierarchical URLs,including the trailing slash in a container's URI makes it easier to use relative URIs.Take the following container URI for example:
http://example.org/container1
It is more advantageous to use the following instead:
http://example.org/container1/
To illustrate the advantage, let's start with the followingcontainer using absolute URIs:
Example 4: A simple container
@prefix dcterms: <http://purl.org/dc/terms/>.@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.@prefix ldp: <http://www.w3.org/ns/ldp#>.<http://example.org/container1> a a ldp:Container, ldp:BasicContainer; dcterms:title "A very simple container"; ldp:contains <http://example.org/container1/member1>, <http://example.org/container1/member2>, <http://example.org/container1/member3>.
Suppose now that we wish to reflect the same resource usingrelative URIs. If the URI of the container includes the trailingslash, we end up with a very elegant representation, as shown below.
Example 5: Container URI is http://example.org/container1/
@prefix dcterms: <http://purl.org/dc/terms/>.@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.@prefix ldp: <http://www.w3.org/ns/ldp#>.<> a a ldp:Container, ldp:BasicContainer; dcterms:title "A very simple container"; ldp:contains <member1>, <member2>, <member3> .
But suppose that we omit the trailing slash, issued an HTTPGET, and the container returned the representation shown above. Thiscould produce a graph that is equivalent to the following:
Example 6: Container URI is http://example.org/container1
@prefix dcterms: <http://purl.org/dc/terms/>.@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.@prefix ldp: <http://www.w3.org/ns/ldp#>.<http://example.org/container1> a a ldp:Container, ldp:BasicContainer; dcterms:title "A very simple container"; ldp:contains <http://example.org/member1>, <http://example.org/member2>, <http://example.org/member3>.
That is not what was intended; the member URLs lack thecontainer path segment.The returned document wouldhave to be more verbose in order to be correct:
Example 7: Container URI is http://example.org/container1
@prefix dcterms: <http://purl.org/dc/terms/>.@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.@prefix ldp: <http://www.w3.org/ns/ldp#>.<> a a ldp:Container, ldp:BasicContainer; dcterms:title "A very simple container"; ldp:contains <container1/member1>, <container1/member2>, <container1/member3> .
So, clearly, the better solution is to ensure that containerURIs end with a trailing slash.
2.7Use fragments as relative identifiers
Resource URIs are permitted to end with a fragment; the fragmentcomponent is delimited from the rest of the URI because it isintroduced by a hash mark (#).For this reason, URIs with non-empty fragments are often called hash URIs;a hash URI identifies a subordinate or related resource [RFC3986].
Take the URI,http://www.example.org/products#item10245, for example. The non-fragment portion of the URI is the part preceding the hash mark,http://www.example.org/products, and the fragment identifier is the part that follows,item10245.
When expressing Linked Data Platform Resources in RDF,fragments are useful because they can be expressed as relative URIson the document describing them. This is particularly handy fordescribing multiple LDPRs whose representations are contained withina single document.
First, it provides the convenience and efficiency of brevity.Suppose, for example, the resources foo, bar, and baz arecontained in the same document. Since serving all of thedescriptions in a single document is acceptable, we can mintrelative URIs within the document using the fragment identifier (<#foo>,<#bar>and<#baz>). [LDP] ensures that the default base URI is the documentURI (http://www.example.org/products), so the absolute URI for each is the base URI, plus the hash mark,plus the fragment identifier.
Second, it can help avoid certain complexities inherent withother approaches. Achieving the same result using three independentdereferenceable URIs could be more involved because multipledocuments would have to be published, perhaps also including thesetup of 303 redirects.
See also:
Cool URIs for theSemantic Web
Axioms ofWeb Architecture, URI References: Fragment Identifiers on URIs
http://www.w3.org/DesignIssues/Fragment.html
DereferencingHTTP URIs
http://www.w3.org/2001/tag/doc/httpRange-14/2007-05-31/HttpRange-14
2.8Prefer standard datatypes
LDPR representations should use only the following standarddatatypes. RDF does not by itself define datatypes to be used forliteral property values, therefore a set of standard datatypes basedon [XMLSCHEMA11-2] and [RDF-PRIMER11] should be used:
2.9Re-use established linked data vocabularies instead of(re-)inventing duplicates
This section summarizes some well-known RDF vocabularies that shouldbe used in Linked Data Platform Resources wherever a resource needsto use a predicate whose meaning matches one of these. For example,if a resource has a description, and the application semantics ofthat description is compatible withdcterms:description, thendcterms:descriptionshould be used. If needed, additional application-specificpredicates may be used. A specification for a domain may require oneor more of these properties for a particular resource type. TheRange column in the tables below identifies the definedrdfs:rangefor the properties.
Common Properties
From Dublin Core URI:http://purl.org/dc/terms/
| Property | Range/DataType | Comment |
|---|
| dcterms:contributor | dcterms:Agent | |
| dcterms:creator | dcterms:Agent | |
| dcterms:created | xsd:dateTime | |
| dcterms:description | rdf:XMLLiteral | Descriptive text about the resource represented as richtext in XHTML format. should include only content that is validand suitable inside an XHTML element. |
| dcterms:identifier | rdfs:Literal | |
| dcterms:modified | xsd:dateTime | |
| dcterms:relation | rdfs:Resource | The HTTP URI of a related resource. This is the predicateto use when you don't know what else to use. If you know morespecifically what sort of relationship it is, use a more specificpredicate. |
| dcterms:subject | rdfs:Resource | |
| dcterms:title | rdf:XMLLiteral | A name given to the resource. Represented as rich text inXHTML format. should include only content that is valid inside anXHTML element. |
The predicatedcterms:typeshould not be used, instead userdf:type. [DC-RDF].
From RDF URI:http://www.w3.org/1999/02/22-rdf-syntax-ns#
| Property | Range/DataType | Comment |
|---|
| rdf:type | rdfs:Class | The type or types of the resource |
From RDF Schema URI:http://www.w3.org/2000/01/rdf-schema#
| Property | Range/DataType | Comment |
|---|
| rdfs:member | rdfs:Resource | |
| rdfs:label | rdfs:Literal | Only use this in vocabulary documents, to define the nameof the vocabulary term. |
2.10Use qvalues properly
Quality factors allow the user or user agent to indicate therelative degree of preference for a media-range, using the qvaluescale from 0 to 1. The default value is q=1. Take the following forexample:
Accept: text/turtle; q=0.5, application/json
This should be interpreted as "I prefer application/json, butsend me text/turtle if it is the best available after a 50%mark-down in quality."
Improper handling of qvalues is a common problem inimplementations of content negotiation.
Refer to Section 14, Header Field Definitions, in the[HTTP11] specification to understand the proper use and evaluationof qvalues for both client and server implementations.
2.11Respond with primary URLs and use them for identity comparison
Clients can access an LDPR using multiple URLs. An LDP servershould respond to each of those requests using a single consistentURL, a primary URL, for the LDPR. This primary URL may be foundin the response's Location and/or Content-Location headers, andpotentially also in the representation of the LDPR. A common case isURLs that vary by protocol, one HTTP and one HTTPS, but areotherwise identical. In most cases those two URLs refer to the sameresource, and the server should respond to requests on either URLwith a single (primary) URL.
Clients should use the primary URL as an LDPR's identity;for example, when determining if two URLs refer to the same resourceclients should compare the primary URLs, not the URLs used toaccess the resources. Note that this usagedoes imply that theclient has sufficient reason to trust the headers and/or contentby which the primary URL is communicated to the client, which is beyond what HTTP alone can guarantee [RFC7231].
2.12Representing relationships between resources
LDPRs can use one RDF triple to represent a link(relationship) to another resource. Having the source resource’s URIas the subject and the target resource’s URI as the object of thetriple is enough. Contrary to a misconception that readers withcertain backgrounds may assume, the creation of an"intermediate link" resource is not required to expressthe relationship.
2.13Minimize server-specific constraints
LDP servers should enable simple creation and modification ofLDPRs.
It may be common for LDP servers to put restrictions onrepresentations – for example, the range of rdf:type predicates,datatypes of the objects of predicates, and the number ofoccurrences of predicates in an LDPR, but servers should minimizesuch restrictions.
For some server applications, excessive constraints onmodification of resources may be required. However, enforcement ofmore complex constraints will greatly restrict the set of clientsthat can modify resources. For interoperability with a wider rangeof clients, implementers are therefore encouraged to minimizeserver-specific constraints.