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 RDF.

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 can be found in the W3C technical reports index at https://www.w3.org/TR/.

This document is a part of the Linked Data Basic Profile Submission, which comprises two documents:

1. Linked Data Basic Profile 1.0 (this document)
2. Linked Data Basic Profile 1.0 - Use Cases and Requirements

By publishing this document, W3C acknowledges that the Submitting Members have made a formal Submission request to W3C for discussion. Publication of this document by W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by it. This document is not the product of a chartered W3C group, but is published as potential input to the W3C Process. A W3C Team Comment has been published in conjunction with this Member Submission. Publication of acknowledged Member Submissions at the W3C site is one of the benefits of W3C Membership. Please consult the requirements associated with Member Submissions of section 3.3 of the W3C Patent Policy. Please consult the complete list of acknowledged W3C Member Submissions.

• 1. Introduction
• 2. Terminology
• 3. Conformance
• 3.1 Conventions Used in This Document
• 4. Basic Profile Resource
• 4.1 General
• 4.2 HTTP GET
• 4.3 HTTP POST
• 4.4 HTTP PUT
• 4.5 HTTP DELETE
• 4.6 HTTP HEAD
• 4.7 HTTP PATCH
• 4.8 Common Properties
• 5. Basic Profile Container
• 5.1 Informative
• 5.1.1 Container Member Information
• 5.1.2 Retrieving Only Non-member Properties
• 5.1.3 Paging
• 5.1.4 Ordering
• 5.1 General
• 5.2 HTTP GET
• 5.3 HTTP POST
• 5.4 HTTP PUT
• 5.5 HTTP DELETE
• 5.6 HTTP HEAD
• 5.7 HTTP PATCH
• 6. References
• 6.1 Normative References
• 6.2 Informative References
• 7. Acknowledgements

Terminology is based on W3C's Architecture of the World Wide Web [WEBARCH] and Hyper-text Transfer Protocol [RFC2616] 

Link

A relationship between two resources when one resource (representation) refers to the other resource by means of a URI. [WEBARCH]

Linked Data

As defined by Tim Berners-Lee. [4Rules]

Profile

A specification that defines the needed components from other specifications as well as providing additional clarifications as needed.

Basic Profile Resource (BPR)

HTTP resource that conforms to the simple lifecycle patterns and conventions in this document.

Basic Profile Container (BPC)

BPR resource that also conforms to additional patterns and conventions in this document for managing membership.

Client

A program that establishes connections for the purpose of sending requests. [RFC2616]

Server

An application program that accepts connections in order to service requests by sending back responses. 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. [RFC2616]

Conformance is defined in accordance with the use of the words MUST, MUST NOT, SHOULD, SHOULD NOT, MAY and RECOMMENDED as described in RFC 2119 [RFC2119] .

Conformance statements on BPR representations apply to servers and clients that either create or generate representations that represent the state of a BPR.

Sample resource representations are provided in text/turtle format [TURTLE].

Commonly used namespace prefixes:

@prefix dcterms: <https://purl.org/dc/terms/>.
@prefix rdf:     <https://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs:    <https://www.w3.org/2000/01/rdf-schema#>.
@prefix bp:      <https://open-services.net/ns/basicProfile#>.
@prefix xsd:     <https://www.w3.org/2001/XMLSchema#>.

Basic Profile Resources (BPRs) are HTTP resources that conform to the simple patterns and conventions in this section. HTTP requests to access, modify, create or delete BPRs are accepted and processed by BPR servers. Most BPRs 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 [4Rules], others address additional needs.

The rules for Basic Profile Resources address basic questions such as:

• What resource formats should be used?
• What literal value types should be used?
• Are there some typical vocabularies that should be reused?
• How is optimistic collision detection handled for updates?
• What should client expectations be for changes to linked-to resources, such as type changes?
• What can servers do to ease the burden of constraints for resource creation?

The following sections define the rules and guidelines for use of BPRs.

4.1 General

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:

1. To which URLs can I POST to create new resources?
2. Where can I GET a list of existing resources?
3. How is the order of the container entries expressed?
4. How do I get information about the members along with the container?
5. How do I GET the entries of a large container broken up into pages?
6. How can I ensure the resource data is easy to query?

This document defines the representation and behavior of containers that address these issues. The set of members of a container is defined by a set of triples in its representation (and state) called the membership triples. The membership triples of a container all have the same subject and predicate – the objects of the membership triples define the members of the container. The subject of the membership triples is called the membership subject and the predicate is called the membership predicate. In the simplest cases, the membership subject will be the BPC resource itself, 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 rdfs:member predicate.

This document includes a set of guidelines for using POST to create new resources and add them to the list of members of a container. This document also explains how to include information about each member in the container’s own representation and how to paginate the container representation if it gets too big.

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
#    https://example.org/container1
@prefix dcterms: <https://purl.org/dc/terms/>.
@prefix rdfs: <https://www.w3.org/2000/01/rdf-schema#>.
@prefix bp: <https://open-services.net/ns/basicProfile#>.
<https://example.org/container1>
   a bp:Container;
   dcterms:title "A very simple container";
   rdfs:member
      <https://example.org/container1/member1>,
      <https://example.org/container1/member2>,
      <https://example.org/container1/member3>.

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

Sometimes it is useful to use a subject other than the container itself as the membership subject and to use a predicate other than rdfs:member as the membership predicate, as illustrated below.

# The following is the representation of
#   https://example.org/netWorth/nw1/assetContainer
@prefix rdfs: <https://www.w3.org/2000/01/rdf-schema#>.
@prefix bp: <https://open-services.net/ns/basicProfile#>.
@prefix o: <https://example.org/ontology/>.
<https://example.org/netWorth/nw1/assetContainer>
   a bp:Container;
   bp:membershipSubject <https://example.org/netWorth/nw1>;
   bp:membershipPredicate o:asset.
<https://example.org/netWorth/nw1>
   a o:NetWorth;
   o:asset
      <https://example.org/netWorth/nw1/assetContainer/a1>,
      <https://example.org/netWorth/nw1/assetContainer/a2>.

The essential structure of the container is the same, but in this example, the membership subject is not the container itself – it is a separate net worth resource. The membership predicate is o:asset – a predicate from the domain model. A POST to this container will create a new asset and add it to the list of members by adding a new membership triple to the container. You might wonder why we didn’t just make https://example.org/netWorth/nw1 a container and POST the new asset directly there. That would be a fine design if https://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 https://example.org/netWorth/nw1/assetContainer and https://example.org/netWorth/nw1/liabilityContainer container resources allows both assets and liabilities to be created.

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

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

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

# The following is the representation of
#	 https://example.org/netWorth/nw1/assetContainer
@prefix dcterms: <https://purl.org/dc/terms/>.
@prefix rdfs:    <https://www.w3.org/2000/01/rdf-schema#>.
@prefix bp:      <https://open-services.net/ns/basicProfile#>.
@prefix o:       <https://example.org/ontology/>.
<https://example.org/netWorth/nw1/assetContainer>
   a bp:Container;
   dcterms:title "The assets of JohnZSmith";
   bp:membershipSubject <https://example.org/netWorth/nw1>;
   bp:membershipPredicate o:asset.
<https://example.org/netWorth/nw1>
   a o:NetWorth;
   o:asset
      <https://example.org/netWorth/nw1/assetContainer/a1>,
      <https://example.org/netWorth/nw1/assetContainer/a3>,
      <https://example.org/netWorth/nw1/assetContainer/a2>.
<https://example.org/netWorth/nw1/assetContainer/a1>
   a o:Stock;
   o:value 10000.
<https://example.org/netWorth/nw1/assetContainer/a2>
   a o:Bond;
   o:value 20000.
<https://example.org/netWorth/nw1/assetContainer/a3>
   a o:RealEstateHolding;
   o:value 300000.

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

The example listed here only show a simple case where only a few simple non-member properties 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.

Here is an example requesting the non-member properties of a container identified by the URL https://example.org/container1 and adding the query string ?non-member-properties :

Request:

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

Response:

HTTP/1.1 200 OK
Content-Type: text/turtle; chartset=UTF-8
ETag: "_87e52ce291112"
Content-Length: 325
@prefix rdfs: <https://www.w3.org/2000/01/rdf-schema#>.
@prefix dcterms: <https://purl.org/dc/terms/>.
@prefix bp: <https://open-services.net/ns/basicProfile#>.
<https://example.org/container1>
   a bp:Container;
   dcterms:title "A Basic Profile Container of Acme Resources";
   bp:membershipPredicate rdfs:member;
   dcterms:publisher <https://acme.com/>.

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

To address this problem, BPCs may support a technique called Paging.  Paging can be achieved with a simple RDF pattern. For each container resource, <containerURL>, we define a new resource <containerURL>?firstPage. The triples in the representation of <containerURL>?firstPage are a subset of the triples in <containerURL> - same subject, predicate and object.

BPC servers may respond to requests for a container by redirecting the client to the first page resource – using a 303 “See Other” redirect to the actual URL for the page resource.

Continuing on from the member information from the JohnZSmith net worth example, we’ll split the response across two pages.  The client requests the first page as https://example.org/netWorth/nw1/assetContainer?firstPage:

# The following is the representation of
#    https://example.org/netWorth/nw1/assetContainer?firstPage
@prefix rdf: <https://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix dcterms: <https://purl.org/dc/terms/>.
@prefix bp: <https://open-services.net/ns/basicProfile#>.
@prefix o: <https://example.org/ontology/>.
<https://example.org/netWorth/nw1/assetContainer>
   a bp:Container;
   dcterms:title "The assets of JohnZSmith";
   bp:membershipSubject <https://example.org/netWorth/nw1>;
   bp:membershipPredicate o:asset.
<https://example.org/netWorth/nw1/assetContainer?firstPage>
   a bp:Page;
   bp:pageOf <https://example.org/netWorth/nw1/assetContainer>;
   bp:nextPage <https://example.org/netWorth/nw1/assetContainer?p=2>.
 
<https://example.org/netWorth/nw1>
    a o:NetWorth;
	o:asset
	<https://example.org/netWorth/nw1/assetContainer/a1>,
	<https://example.org/netWorth/nw1/assetContainer/a4>,
	<https://example.org/netWorth/nw1/assetContainer/a3>,
	<https://example.org/netWorth/nw1/assetContainer/a2>.
<https://example.org/netWorth/nw1/assetContainer/a1>
   a o:Stock;
   o:value 100.00.
<https://example.org/netWorth/nw1/assetContainer/a2>
   a o:Cash;
   o:value 50.00.
# server initially supplied no data for a3 and a4 in this response

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

# The following is the representation of
#  https://example.org/netWorth/nw1/assetContainer?p=2
@prefix rdf: <https://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix dcterms: <https://purl.org/dc/terms/>.
@prefix bp: <https://open-services.net/ns/basicProfile#>.
@prefix o: <https://example.org/ontology/>.
<https://example.org/netWorth/nw1/assetContainer>
   a bp:Container;
   dcterms:title "The assets of JohnZSmith";
   bp:membershipSubject <https://example.org/netWorth/nw1>;
   bp:membershipPredicate o:asset.
<https://example.org/netWorth/nw1/assetContainer?p=2>
   a bp:Page;
   bp:pageOf <https://example.org/netWorth/nw1/assetContainer>;
   bp:nextPage rdf:nil.
<https://example.org/netWorth/nw1>
   a o:NetWorth;
   o:asset 
      <https://example.org/netWorth/nw1/assetContainer/a5>.
<https://example.org/netWorth/nw1/assetContainer/a5>
   a o:Stock;
   dcterms:title "Big Co.";
   o:value 200.02.

In this example, there is only one member in the container in the final page.  To indicate this is the last page, a value of rdf:nil is used for the bp:nextPage predicate of the page resource.

BPC guarantees that any and all the triples about the members will be on the same page as the membership triple for the member.

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

Order only becomes important for BPC servers when containers are paginated. If the server does not respect ordering when constructing pages, the client is forced to retrieve all pages before sorting the members, which would defeat the purpose of pagination. In cases where ordering is important, a BPC server exposes all the members on a page with a higher sort order than all members on the previous page and lower sort order than all the members on the next page. The BPC specification provides a predicate - bp:containerSortPredicates - that the server may use to communicate to the client which predicates were used for page ordering. Multiple predicate values may have been used for sorting, so the value of this predicate is an ordered list.

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

# The following is the ordered representation of
#   https://example.org/netWorth/nw1/assetContainer
@prefix rdf: <https://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix dcterms: <https://purl.org/dc/terms/>.
@prefix bp: <https://open-services.net/ns/basicProfile#>.
@prefix o: <https://example.org/ontology/>.
<https://example.org/netWorth/nw1/assetContainer>
   a bp:Container;
   dcterms:title "The assets of JohnZSmith";
   bp:membershipSubject <https://example.org/netWorth/nw1>;
   bp:membershipPredicate o:asset.
<https://example.org/netWorth/nw1/assetContainer?firstPage>
   a bp:Page;
   bp:pageOf <https://example.org/netWorth/nw1/assetContainer>;
   bp:containerSortPredicates (o:value).
<https://example.org/netWorth/nw1>
   a o:NetWorth;
   o:asset
      <https://example.org/netWorth/nw1/assetContainer/a1>,
      <https://example.org/netWorth/nw1/assetContainer/a3>,
      <https://example.org/netWorth/nw1/assetContainer/a2>.
<https://example.org/netWorth/nw1/assetContainer/a1>
   a o:Stock;
   o:value 100.00.
<https://example.org/netWorth/nw1/assetContainer/a2>
   a o:Cash;
   o:value 50.00.
<https://example.org/netWorth/nw1/assetContainer/a3>
   a o:RealEstateHolding;
   o:value 300000.

As you can see by the addition of the bp:containerSortPredicates predicate, the o:value predicate is used to define the ordering of the results.  It is up to the domain model and server to determine the appropriate predicate to indicate the resource’s order within a page, and up to the client receiving this representation to use that order in whatever way is appropriate, for example to sort the data prior to presentation on a user interface.

The Basic Profile does not define how clients discover BPCs.

There are no additional requirements on HTTP HEAD.

Dublin Core

Dublin Core Metadata Initiative Terms , DCMI Recommendation, 11 October 2010. This version is https://dublincore.org/documents/2010/10/11/dcmi-terms/.  The latest version is https://dublincore.org/documents/dcmi-terms/.

RDF

Resource Description Framework (RDF): Concepts and Abstract Syntax, Klyne G., Carroll J. (Editors), W3C Recommendation, 10 February 2004. This version is https://www.w3.org/TR/2004/REC-rdf-primer-20040210/. The latest version is https://www.w3.org/TR/rdf-concepts/.

RFC2119

RFC 2119: Key words for use in RFCs to Indicate Requirement Levels , Scott Bradner, 1997. (See https://www.ietf.org/rfc/rfc2119.txt)

RFC2616

Hypertext Transfer Protocol - HTTP/1.1 . J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee, June 1999. Available at https://www.ietf.org/rfc/rfc2616.txt.

RFC3986

Uniform Resource Identifier (URI): Generic Syntax , Berners-Lee, Fielding, Masinter, January 2005.

RFC5789

PATCH Method for HTTP , L Dusseault, J. Snell, March 2010. Available at https://tools.ietf.org/html/rfc5789

RFC3987

Internationalized Resource Identifiers (IRIs) , Duerst, Suignard, January 2005.

SPARQL-UPDATE

SPARQL 1.1 Update, S. Schenk, P. Gearon, Editor, W3C Working Draft, 26 January 2010, https://www.w3.org/TR/2010/WD-sparql11-update-20100126/. Latest version available at https://www.w3.org/TR/sparql11-update/.

4Rules

Linked Data Design Issues, Tim Berners-Lee, 27 July 2006, https://www.w3.org/DesignIssues/LinkedData.html

DC-RDF

Expressing Dublin Core metadata using the Resource Description Framework (RDF), M. Nilsson and all, 14 January 2008, https://dublincore.org/documents/2008/01/14/dc-rdf/. Latest available at: https://dublincore.org/documents/dc-rdf/.

HTML 4.01

HTML 4.01 Specification, D. Raggett, A. Le Hors, and I. Jacobs, 1999. (See https://www.w3.org/TR/html4/)

IANA

Internet Assigned Numbers Authority (IANA) MIME Media Types, https://www.iana.org/assignments/media-types/index.html

LinkedData

Linked Data at W3C, https://www.w3.org/standards/semanticweb/data

OSLC

Open Services for Lifecycle Collaboration (OSLC), https://open-services.net

RDF Primer

Resource Description Framework (RDF): Concepts and Abstract Syntax , Klyne G., Carroll J. (Editors), W3C Recommendation, 10 February 2004. This version is https://www.w3.org/TR/2004/REC-rdf-primer-20040210/. The latest version is https://www.w3.org/TR/rdf-primer/.

RDF-MT

RDF Semantics, P. Hayes, Editor, W3C Recommendation, 10 February 2004, https://www.w3.org/TR/2004/REC-rdf-mt-20040210/. Latest version available at https://www.w3.org/TR/rdf-mt/.

RDF-REST

RDF Simple Data Interface Protocol – Level Zero, Latest version available at: https://www.w3.org/2001/sw/wiki/index.php?title=REST

REST

Representational State Transfer (REST), R. Fielding, Ph.D. dissertation, 2000, Latest version available at https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm .

RW LinkedData

Read-Write Linked Data, Berners-Lee, August 2009, https://www.w3.org/DesignIssues/ReadWriteLinkedData.html

SPARQL

SPARQL Query Language for RDF, E. Prud'hommeaux, A. Seaborne, Editor, W3C Recommendation, 15 January 2008, https://www.w3.org/TR/2008/REC-rdf-sparql-query-20080115/. Latest version available at https://www.w3.org/TR/rdf-sparql-query/.

SPARQL-HTTP

SPARQL 1.1 Graph Store HTTP Protocol, Latest version available at https://www.w3.org/2009/sparql/docs/http-rdf-update/

TURTLE

Turtle - Terse RDF Triple Language , D. Beckett, T. Berners-Lee, Team Submission, 28 March 2011, https://www.w3.org/TeamSubmission/2011/SUBM-turtle-20110328/. Latest version available at https://www.w3.org/TeamSubmission/turtle/.

WEBARCH

Architecture of the World Wide Web, Volume One , N. Walsh, I. Jacobs, Editors, W3C Recommendation, 15 December 2004, https://www.w3.org/TR/2004/REC-webarch-20041215/. Latest version available at https://www.w3.org/TR/webarch/.

Additional Contributors:

Arthur Ryman (IBM), Ian Green (IBM), Barbara McKee (IBM), Sally Hehir (IBM)