LDS³ - Linked Data Specification and Storage Service

1. Introduction
2. Notational Conventions
3. Terminology
4. Data Type Prefixes
5. Namespaces
6. Protocol Overview
7. Authentication
8. Protocol Operations
  8.1. Submitting a New Document
    8.1.1 Submitting a New Document with no self description
    8.1.2 Submitting a New Document containing self description
    8.1.3 Two-Part submission. Obtaining a directy editable Edit-IRI first.
  8.2. Updating an Existing Document
    8.2.1 Document Direct Update
    8.2.2 In-Direct Document Update
  8.3. Deleting Data
    8.3.1 Deleting a Document
    8.3.2 Delete via POST
    8.3.3 Deleting Data
  8.4 Retrieving Data
    8.4.1 Implementing a Timegate
9. References

Credits

Technical Lead: David Tarrant, University of Southampton

Project Manager: Bram Van Der Werf, Open Planets Foundation

Technical Advisory Group

Chris Gutteridge, University of Southampton

Ian Millard, University of Southampton

Further acknowledgements of input

1. Introduction

Linked-data is quickly becoming a widely used technology. However, maturity of best practices, management specifications and support for quad based models (to allow versioning and provence) are all still in their early stages of development. This specfication outlines an HTTP CRUD (Create, Retrieve, Update, Delete) based method for managing, versioning and tracking linked-data which supports provenance techniques.

This sepecification is based heavily on existing HTTP techniques and recommends some best practices for storing and managing documents containing data pertaining to a number of objects. By utilising the GUID, each document can be managed to create, update and delete data relating to objects being described. As the objects themselves cannot be edited directly, the document management system strictly enforces versioning and provenance support.

2. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119].

3. Terminology

Throughout this document we will regularly refer to several items in a specific context, these are outlined here:

IRI-Prefix

IRI-Prefix refers to the domain or domain prefix being managed. For example a IRI-Prefix could be http://data.mydomain.org/

Document

A Document is the entity which is exchanged and controlled throughout this specification. A Document contains data pertaining to a number of objects which may include itself.

Doc-URL

A Document-URI refers to one specific instance of a document.

Edit-IRI

The Edit-IRI refers to the container used to store a number of related documents. The Edit-IRI acts as a referece point for the latest information pertaining to a document and the data contained within it. The Edit-IRI is used for the majority of editorial operations outlined.

DS-URL

The DS-URL is the Data Submission URL to which all new data is initially submitted. It can also be used to request a new Edit-IRI from.

Data-IRI

A Data IRI is any non-document and non-edit IRI which is outside of the editorial scope of the system. These IRIs are those being defined by the documents.

4. Data Type Prefixes

In order to segment data into understandable catagories, it is RECOMMMENDED that a series of data type prefixes be used. The main aim is to separate documents from physical/virtual things and separate both of these from dynamic data/metadata/reports which result from interacting with these things. Documents can describe both but should be careful with IRI/URI usage. The following IRIs and URIs are RECOMMENDED as best practise.

The Edit-URI Prefix - http://IRI-Prefix/doc/{GUID}

Document storage where each is given a GUID as referece point. In the case of this specification this is used as the Edit-IRI which stays constanst for each version of the same document.

A Doc-URL - http://IRI-Prefix/doc/{GUID}/{YYYY-MM--DDTHH:ii:ss+01:00}

A Doc-URL where an [iso8601] formatted date has been appended to the Edit-IRI to represent a particular instance/version of a document in time.

Data-IRI for identifiable object - http://IRI-Prefix/id/type/foo/bar

A Data-IRI. The ID prefix for physical/virtual object IRIs (things that can be assigned a distinct identifier). The type/foo/bar gives suggestion of a further way to segment and manage this single prefix.

Data-IRI for non-identifiable object - http://IRI-Prefix/report/type/foo/bar

A Data-IRI intended as a way to separate identifiable objects from reports and other resources relating to these objects.

5. Namespaces

Several common namespaces in Linked-data shall be refered to by the following shorthand notation.

6. Protocol Overview

Data is managed but Creating, Reverting, Updating and Deleting (a variation on CRUD) Documents. No direct manipulation of objects is permitted other than retrieval.

When a Document is POST/PUT into the system, a document Edit-IRI is either created/identified or manually submitted by the user. This Edit-IRI MUST conform to the Edit-IRI namespace schema outlined by the host system. In the event where the submitting user has identified a different IRI, this MAY be translated into a conforming IRI if possible.

Data pertaining to the EDIT-URI MUST only relate to that document and SHOULD contain data such as when the document was created, by whom and with which tools. Data relating to the time the document was submitted and by who MUST be added (or checked existing) by the server side application handling the document submission.

The server SHOULD perform a series of checks to ensure that the document is appropriate for acceptance into the data store and the client MUST be able to handle the messages returned by the server.

Once a document is accepted, the server will return both the Edit-IRI and a static Doc-URL. The Edit-IRI MUST be capable of accepting Update and Delete requests. The Doc-URL gives the location of a specific version of the document, in most cases the one created as a result of the previous operation.

7. Authentication

Authentication (if required) SHOULD use either Authenticated REST Requests (as per [Amazon Authentication Model]) or HTTP basic auth. It is recommended that Authenticated REST Requests be used where possible.

A unit test client is available here to check Amazon based REST requests against a server implemtation. A server MUST supply an example file at http://server-name.com/tests/auth against which anyone can authenticate.

8. Protocol Operations

While specific HTTP status codes are used below, a client should be prepared to handle any status code as per the HTTP status code definitions [RFC2616]

8.1. Submitting a New Document

There are two main considerations when submitting a new document which are outlined individually in this section.

A document with no self description.

This form of document only describes third party objects and provides no data relating to the document itself, such as when it was written and by whom.

A document with self description.

In this document, situation data is provided relating to the document itself. Examples of document metadata may include who wrote the document, when and with which tools.

8.1.1 Submitting a New Document with no self description

In this case the document contains no pre-defined data of any kind relating to itself. The only data contained within the document relates to other objects and resources outside of document scope.

In order to submit a document with no self description the client roles are as follows:

• The client MUST ensure that all data described in the document related to objects outside of the Edit-URI Prefix.
• The client MUST perform an HTTP POST requrest to the DS-URL
• The client MUST must be able to handle a variety of errors declared by the HTTP status code definitions [RFC2616]
• The client SHOULD be able to understand the Location header returned with the result of a successful operation and store this in order to allow future operations on this document

The server also has various responsibilities to play in order to handle a document containing no self description.

• The server MUST be able to create a new Edit-IRI and Doc-URL conforming to the Edit-IRI and Doc-URL schema and ensure neither are being used already.
• The server SHOULD check that the client request is correct and that the document is not defining or conflicting with existing documents
• The server SHOULD parse the document, checking for errors
• The server MUST store the document and provide the client an Edit-IRI through which updates can occur at a later stage and a Doc-URL outlining where the submitted data is permenantly available from.

The following represents an example of a document which defines data about a person called Bob.

POST DS-URL HTTP/1.1
Host: example.org
Date: Sun, 1 Jan 2012 09:00:00 +0000
Content-Length: xxx
Content-Type: application/rdf+xml
Authorization: LDS LDSAccessKeyId:Signature

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:contact="http://www.w3.org/2000/10/swap/pim/contact#">

  <contact:Person rdf:about="http://IRI-Prefix/id/person/BobSmith">
    <contact:fullName>Bob Smith</contact:fullName>
    <contact:mailbox rdf:resource="mailto:bob_smith@example.org"/>
    <contact:personalTitle>Dr.</contact:personalTitle> 
  </contact:Person>

</rdf:RDF>

In order to process this request the server COULD follow the following proceedure:

1. Check the document parses
2. Check that the input document does not define any data about more than one node within the Edit/Document Prefix (http://IRI-Prefix/doc/...)
3. Locate a valid document URL if only one is defined (see the following section) OR create a new valid document Edit-URI (this section).
4. With the Edit-IRI and Doc-URL created, the server SHOULD populate the input document with data relating to the document and inport process, such as when the document was submitted and by whom.
5. The server should then store this document such that it can be updated at a later stage
6. The server should index the latest version of this document to be queried, removing any previous version of the document from the index only

If successful the servers response COULD look like the following:

201 Created
Link: <[Edit-IRI] (e.g. http://IRI-Prefix/doc/4E5E357B-69A3-4C84-BCBA-572693FBCEA3)>; rel="edit-iri";
Content-Location: [Doc-URL/strong>] (e.g. http://IRI-Prefix/doc/4E5E357B-69A3-4C84-BCBA-572693FBCEA3/2011-12-31T23:59:00+00:00)
Content-Length: xxx
Content-Type: application/rdf+xml=

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:contact="http://www.w3.org/2000/10/swap/pim/contact#"
	 xmlns:dcterms="http://purl.org/dc/terms/">

  <rdf:Description rdf:about="[Doc-URL]">
    <dcterms:publisher>Dave Tarrant</dcterms:publisher>
    <dcterms:dateSubmitted>2011-12-31T23:59:00+00:00</dcterms:dateSubmitted>
  </rdf:Description>

  <contact:Person rdf:about="http://IRI-Prefix/id/person/BobSmith">
    <contact:fullName>Bob Smith</contact:fullName>
    <contact:mailbox rdf:resource="mailto:bob_smith@example.org"/>
    <contact:personalTitle>Dr.</contact:personalTitle> 
  </contact:Person>

</rdf:RDF>

In this example note that:

• The Edit-IRI is a GUID on the doc prefix (effectively a container/folder where all subsequent version of the document go)
• The Doc-URL is the Edit-IRI with the submission time (according to [iso8601]) appended (this is the URI of the actual document in the container)
• The publisher (person who submitted the resource in order to make it available) and dateSubmitted are added to the document data (as metadata relating to the Doc-URL, such items of data will not always be relevant to the Edit-IRI)

The publisher could equally refer to a IRI of a person/entity rather than just be a textual name.

A unit test client is available here, this test client will attempt to post the document outlined in this section to a defined server, the DS-URL and the IRI-Prefix can be defined.

8.1.2 Submitting a New Document containing self description

In this case the client wishes to pre-define some information about the document which the server MUST maintain when handling this document.

In order to submit a document containing self description the client roles are as follows:

• The client MUST ensure that all data described in the document related to objects outside of the Edit-URI Prefix.
• The client MUST define their own custom document prefix which can be of any type as long as it is distinct.
• The client MUST perform an HTTP POST requrest to the DS-URL append a ?Doc-URI= parameter to the end of the request which defines the source URI of the document self description data.
• The client MUST must be able to handle a variety of errors declared by the HTTP status code definitions [RFC2616]
• The client SHOULD be able to understand the Location header returned with the result of a successful operation and store this in order to allow future operations on this document

The following represents an example of a document which defines data about a person called Bob.

POST DS-URL?Doc-URI=http://my-namespace.org/doc/this-doc HTTP/1.1
Host: example.org
Date: Sun, 1 Jan 2012 09:00:00 +0000
Content-Length: xxx
Content-Type: application/rdf+xml
Authorization: LDS LDSAccessKeyId:Signature

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:contact="http://www.w3.org/2000/10/swap/pim/contact#"
	 xmlns:dcterms="http://purl.org/dc/terms/">
  
  <rdf:Description rdf:about="http://my-namespace.org/doc/this-doc">
    <dcterms:creator>Richard Philips</dcterms:creator>
    <dcterms:date>2011-12-26T12:30:14+00:00</dcterms:date>
    <dcterms:isPartOf rdf:resource="http://id.my-realy-cool-project.org/"/>
  </rdf:Description>

  <contact:Person rdf:about="http://IRI-Prefixstrong>/id/person/BobSmith">
    <contact:fullName>Bob Smith</contact:fullName>
    <contact:mailbox rdf:resource="mailto:bob_smith@example.org"/>
    <contact:personalTitle>Dr.</contact:personalTitle> 
  </contact:Person>

</rdf:RDF>

The server has various key responsibilities:

• The server MUST be able to create a new Edit-IRI and Doc-URL conforming to the Edit-IRI and Doc-URL schema and ensure neither are being used already.
• The server MUST be able to change all instances of the Doc-URI defined by the client to a valid and resolvable instance of an internal Doc-URL
• The server SHOULD check that the client request is correct and that the document is not defining or conflicting with existing documents
• The server SHOULD parse the document, checking for errors
• The server MUST store the document and provide the client an Edit-IRI through which updates can occur at a later stage and a Doc-URL outlining where the submitted data is permenantly available from.

If successful the server SHOULD return something similar to the following:

201 Created
Link: <[Edit-IRI] (e.g. http://IRI-Prefix/doc/4E5E357B-69A3-4C84-BCBA-572693FBCEA4)>; rel="edit-iri";
Content-Location: [Doc-URL] (e.g. http://IRI-Prefix/doc/4E5E357B-69A3-4C84-BCBA-572693FBCEA4/2011-12-31T23:59:00+00:00)
Content-Length: xxx
Content-Type: application/rdf+xml

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:contact="http://www.w3.org/2000/10/swap/pim/contact#"
	 xmlns:dcterms="http://purl.org/dc/terms/">

  <rdf:Description rdf:about="[Doc-URL]">
    <dcterms:creator>Richard Philips</dcterms:creator>
    <dcterms:date>2011-12-26T12:30:14+00:00</dcterms:date>
    <dcterms:isPartOf rdf:resource="http://id.my-realy-cool-project.org/"/>
    <dcterms:publisher>Dave Tarrant</dcterms:publisher>
    <dcterms:dateSubmitted>2011-12-31T23:59:00+00:00</dcterms:dateSubmitted>
  </rdf:Description>

  <contact:Person rdf:about="http://IRI-Prefix/id/person/BobSmith">
    <contact:fullName>Bob Smith</contact:fullName>
    <contact:mailbox rdf:resource="mailto:bob_smith@example.org"/>
    <contact:personalTitle>Dr.</contact:personalTitle> 
  </contact:Person>

</rdf:RDF>

Note that the document is still automatically annotated with the submission information and this information relates to the document alongside the data which the client submitted.

A unit test client is available here, this test client will attempt to post the document outlined in this section to a defined server, the DS-URL and the IRI-Prefix can be defined.

8.1.3 Two-Part submission. Obtaining a directy editable Edit-IRI first.

In order to submit a document to a server, here a client requests an Edit-IRI first and then submits content directly to this IRI. In this case this Edit-IRI can also be used to define document data directly.

In order to obtain an Edit-IRI the client roles are as follows:

• The client MUST be able to send a blank request to the server
• The client MUST be able to understand the "Location" and "Expires" HTTP headers and re-act before the servers expiry time is reached.

A set of similar requirements is placed upon the server:

• The server MUST be able to create a new document Edit-IRI and retain this for the client.
• The server SHOULD be capable of expiring requests, thus stopping clients from unnecessarily reserving Edit-IRIs and never using them

Example request:

POST DS-URL HTTP/1.1
Host: example.org
Date: Sun, 1 Jan 2012 09:00:00 +0000
Content-Length: 0
Authorization: LDS LDSAccessKeyId:Signature

Example Response

202 Accepted
Link: <[Edit-IRI] (e.g. http://IRI-Prefix/doc/4E5E357B-69A3-4C84-BCBA-572693FBCEA3)>; rel="edit-iri";
Expires: Sat, 31 Dec 2011 23:59:59 GMT

The client can then use this Edit-IRI in order to construct any document and MAY include pre-defined metadata relating directly to the Document Edit-IRI as follows:

POST Edit-IRI HTTP/1.1
Host: example.org
Date: Sun, 1 Jan 2012 09:00:00 +0000
Content-Length: xxx
Content-Type: application/rdf+xml
Authorization: LDS LDSAccessKeyId:Signature

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:contact="http://www.w3.org/2000/10/swap/pim/contact#"
	 xmlns:dcterms="http://purl.org/dc/terms/">
  
  <rdf:Description rdf:about="[Edit-IRI]">
    <dcterms:creator>Richard Philips</dcterms:creator>
    <dcterms:date>2011-12-26T12:30:14+00:00</dcterms:date>
    <dcterms:isPartOf rdf:resource="http://id.my-realy-cool-project.org/"/>
  </rdf:Description>

  <contact:Person rdf:about="http://IRI-Prefix/id/person/BobSmith">
    <contact:fullName>Bob Smith</contact:fullName>
    <contact:mailbox rdf:resource="mailto:bob_smith@example.org"/>
    <contact:personalTitle>Dr.</contact:personalTitle> 
  </contact:Person>

</rdf:RDF>

In order to version the document:

• The server MUST add a version identifier (e.g. date) to the end of the Edit-IRI within the document.

The server response SHOULD look like the following:

201 Created
Link: <[Edit-IRI] (e.g. http://IRI-Prefix/doc/4E5E357B-69A3-4C84-BCBA-572693FBCEA5)>; rel="edit-iri";
Content-Location: [Doc-URL] (e.g. http://IRI-Prefix/doc/4E5E357B-69A3-4C84-BCBA-572693FBCEA5/2011-12-31T23:20:00+00:00)
Content-Length: xxx
Content-Type: application/rdf+xml

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:contact="http://www.w3.org/2000/10/swap/pim/contact#"
	 xmlns:dcterms="http://purl.org/dc/terms/">

  <rdf:Description rdf:about="[Doc-URL]">
    <dcterms:creator>Richard Philips</dcterms:creator>
    <dcterms:date>2011-12-26T12:30:14+00:00</dcterms:date>
    <dcterms:isPartOf rdf:resource="http://id.my-realy-cool-project.org/"/>
    <dcterms:publisher>Dave Tarrant</dcterms:publisher>
    <dcterms:dateSubmitted>2011-12-31T23:20:00+00:00</dcterms:dateSubmitted>
  </rdf:Description>

  <contact:Person rdf:about="http://IRI-Prefix/id/person/BobSmith">
    <contact:fullName>Bob Smith</contact:fullName>
    <contact:mailbox rdf:resource="mailto:bob_smith@example.org"/>
    <contact:personalTitle>Dr.</contact:personalTitle> 
  </contact:Person>

</rdf:RDF>

A unit test client is available here, this test client will attempt to create the Edit-IRI first and then post a document to this location, as per the example above. The DS-URL and the IRI-Prefix can be defined.

8.2. Updating an Existing Document

As with creating a document there are two main techniques to update a document, direct and indirect update. In both cases the client MUST POST the update to the Edit-IRI.

8.2.1 Document Direct Update

When using direct update the client can either:

• Not outline any data related to the document.
• Outline data relating to the document and use the Edit-IRI namespace when detailing this.

In order to update a document, the client roles are as follows:

• The client MUST perform an HTTP POST requrest to the document Edit-IRI
• The client MUST ensure that all data described in the document relates to objects outside of the Edit-IRI Prefix unless the IRI in the Edit-IRI Prefix is the same as the Edit-IRI being POSTed too.
• The client MUST must be able to handle a variety of errors declared by the HTTP status code definitions [RFC2616]

Example:

POST Edit-IRI HTTP/1.1
Host: example.org
Date: Sun, 1 Jan 2012 09:00:00 +0000
Content-Length: xxx
Content-Type: application/rdf+xml
Authorization: LDS LDSAccessKeyId:Signature

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:contact="http://www.w3.org/2000/10/swap/pim/contact#"
	 xmlns:foaf="http://xmlns.com/foaf/0.1/"
	 xmlns:dcterms="http://purl.org/dc/terms/">
  
  <rdf:Description rdf:about="[Edit-IRI]">
    <dcterms:creator>Richard Philips</dcterms:creator>
    <dcterms:creator>Brenda Rodgers</dcterms:creator>
    <dcterms:date>2011-12-26T12:30:14+00:00</dcterms:date>
    <dcterms:isPartOf rdf:resource="http://id.my-realy-cool-project.org/"/>
  </rdf:Description>

  <contact:Person rdf:about="http://IRI-Prefix/id/person/BobSmith">
    <contact:fullName>Bob Smith</contact:fullName>
    <foaf:name>Bob Smith</foaf:name>
    <contact:mailbox rdf:resource="mailto:bob_smith@example.org"/>
    <foaf:mbox rdf:resource="mailto:bob_smith@example.org"/>
    <contact:personalTitle>Dr.</contact:personalTitle> 
    <foaf:title>Dr.</foaf:title> 
    <foaf:knows rdf:resource="http://IRI-Prefix/id/person/SueSmith"/>
  </contact:Person>
  
  <contact:Person rdf:about="http://IRI-Prefix/id/person/SueSmith">
    <contact:fullName>Sue Smith</contact:fullName>
    <foaf:name>Sue Smith</foaf:name>
    <contact:mailbox rdf:resource="mailto:sue_smith@example.org"/>
    <foaf:mbox rdf:resource="mailto:sue_smith@example.org"/>
    <contact:personalTitle>Mrs.</contact:personalTitle> 
    <foaf:title>Mrs.</foaf:title>
    <foaf:knows rdf:resource="http://IRI-Prefix/id/person/BobSmith"/>
  </contact:Person>

</rdf:RDF>

In this example the client has added both data related to the document and the existing person from before (Bob). A new person (Sue) has also been defined by this same document. It is not recommended that one document be used to define all data!

In order to update the documument the server has many process to perform:

• The server SHOULD parse the document, checking for errors
• The server MUST be able to verify that the client is updating an existing document and not attempting to creating a new one.
• The server MUST be able to validate the input document and verify that the client is not attempting to change data relating to any other document other than that defined by the Edit-IRI being updated.
• The server MUST store the document and provide the client an Edit-IRI through which updates can occur at a later stage and a persistant Doc-URL where the stored data can be retrieved at any point.
• The server SHOULD update any local indexes to reflect the changes, removing and archiving old data from these indexes
• The server MUST NOT delete the old document which is being replaced
• The server SHOULD automatically link the new document to the previous version (or verify that the client has already done it)

Below is an example response from the server, showing the link between the submitted version and a potential previous version:

200 OK HTTP/1.1
Link: <Edit-IRI>; rel="edit-iri";
Content-Location: [Doc-URL]
Content-Length: xxx
Content-Type: application/rdf+xml

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:contact="http://www.w3.org/2000/10/swap/pim/contact#"
	 xmlns:foaf="http://xmlns.com/foaf/0.1/"
	 xmlns:dcterms="http://purl.org/dc/terms/">
  
  <rdf:Description rdf:about="Doc-URL">
    <dcterms:creator>Richard Philips</dcterms:creator>
    <dcterms:creator>Brenda Rodgers</dcterms:creator>
    <dcterms:date>2012-01-03T14:34:14+00:00</dcterms:date>
    <dcterms:isPartOf rdf:resource="http://id.my-realy-cool-project.org/"/>
    <dcterms:publisher>Dave Tarrant</dcterms:publisher>
    <dcterms:dateSubmitted>2012-01-03T14:45:00+00:00</dcterms:dateSubmitted>
    <dcterms:replaces rdf:resource="http://IRI-Prefix/doc/4E5E357B-69A3-4C84-BCBA-572693FBCEA5/2011-12-31T23:20:00+00:00"/>
  </rdf:Description>

  <contact:Person rdf:about="http://IRI-Prefix/id/person/BobSmith">
    <contact:fullName>Bob Smith</contact:fullName>
    <foaf:name>Bob Smith</foaf:name>
    <contact:mailbox rdf:resource="mailto:bob_smith@example.org"/>
    <foaf:mbox rdf:resource="mailto:bob_smith@example.org"/>
    <contact:personalTitle>Dr.</contact:personalTitle> 
    <foaf:title>Dr.</foaf:title> 
    <foaf:knows rdf:resource="http://IRI-Prefix/id/person/SueSmith"/>
  </contact:Person>
  
  <contact:Person rdf:about="http://IRI-Prefix/id/person/SueSmith">
    <contact:fullName>Sue Smith</contact:fullName>
    <foaf:name>Sue Smith</foaf:name>
    <contact:mailbox rdf:resource="mailto:sue_smith@example.org"/>
    <foaf:mbox rdf:resource="mailto:sue_smith@example.org"/>
    <contact:personalTitle>Mrs.</contact:personalTitle> 
    <foaf:title>Mrs.</foaf:title>
    <foaf:knows rdf:resource="http://IRI-Prefix/id/person/BobSmith"/>
  </contact:Person>

</rdf:RDF>

A unit test client is available here, this test client will attempt to edit an existing Edit-IRI with the above data. A valid Edit-IRI and IRI-Prefix must be defined.

8.2.2 In-Direct Document Update

When using direct update the client can define additional document metadata using its own document URI, which is given to the server as part of the request. Note that the Edit-IRI is still the one needed to post the document too.

In order to update a document, the client roles are as follows:

• The client MUST ensure that all data described in the document relates to objects outside of the Edit-IRI Prefix.
• The client MUST perform an HTTP POST requrest to the document Edit-IRI
• The client MUST must be able to handle a variety of errors declared by the HTTP status code definitions [RFC2616]

Example: Same as in 8.2.1 except that the client has defined its own Document URI

POST Edit-IRI?Doc-URI=http://my-namespace.org/doc/this-doc HTTP/1.1
Host: example.org
Date: Sun, 1 Jan 2012 09:00:00 +0000
Content-Length: xxx
Content-Type: application/rdf+xml
Authorization: LDS LDSAccessKeyId:Signature

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:contact="http://www.w3.org/2000/10/swap/pim/contact#"
	 xmlns:foaf="http://xmlns.com/foaf/0.1/"
	 xmlns:dcterms="http://purl.org/dc/terms/">
  
  <rdf:Description rdf:about="http://my-namespace.org/doc/this-doc">
    <dcterms:creator>Richard Philips</dcterms:creator>
    <dcterms:creator>Brenda Rodgers</dcterms:creator>
    <dcterms:date>2011-12-26T12:30:14+00:00</dcterms:date>
    <dcterms:isPartOf rdf:resource="http://id.my-realy-cool-project.org/"/>
  </rdf:Description>

  <contact:Person rdf:about="http://IRI-Prefix/id/person/BobSmith">
    <contact:fullName>Bob Smith</contact:fullName>
    <foaf:name>Bob Smith</foaf:name>
    <contact:mailbox rdf:resource="mailto:bob_smith@example.org"/>
    <foaf:mbox rdf:resource="mailto:bob_smith@example.org"/>
    <contact:personalTitle>Dr.</contact:personalTitle> 
    <foaf:title>Dr.</foaf:title> 
    <foaf:knows rdf:resource="http://IRI-Prefix/id/person/SueSmith"/>
  </contact:Person>
  
  <contact:Person rdf:about="http://IRI-Prefix/id/person/SueSmith">
    <contact:fullName>Sue Smith</contact:fullName>
    <foaf:name>Sue Smith</foaf:name>
    <contact:mailbox rdf:resource="mailto:sue_smith@example.org"/>
    <foaf:mbox rdf:resource="mailto:sue_smith@example.org"/>
    <contact:personalTitle>Mrs.</contact:personalTitle> 
    <foaf:title>Mrs.</foaf:title>
    <foaf:knows rdf:resource="http://strong>IRI-Prefix/id/person/BobSmith"/>
  </contact:Person>

</rdf:RDF>

As in 8.2.1 the client has added both data related to the document and the existing person from before (Bob). A new person (Sue) has also been defined by this same document. It is not recommended that one document be used to define all data!

In order to update the documument the server has many process to perform:

• The server SHOULD parse the document, checking for errors
• The server MUST be able to change all instances of the document-uri defined by the client to a valid and resolvable instance of an internal Doc-URL.
• The server MUST be able to verify that the client is updating an existing document and not attempting to creating a new one.
• The server MUST be able to validate the input document and verify that the client is not attempting to change data relating to any other document other than that defined by the Edit-IRI being updated.
• The server MUST store the document and provide the client an Edit-IRI through which updates can occur at a later stage and a persistant Doc-URL where the stored data can be retrieved at any point.
• The server SHOULD annotate the Doc-URL with relavent provenance information.
• The server SHOULD update any local indexes to reflect the changes, removing and archiving old data from these indexes
• The server MUST NOT delete the old document which is being replaced
• The server SHOULD automatically link the new document to the previous version (or verify that the client has already done it)

Having done all of this the response from the server should look the same as that in 8.2.1.

A unit test client is available here, this test client will attempt to edit an existing Edit-IRI with the above data. A valid Edit-IRI and IRI-Prefix must be defined.

8.3. Deleting Data

As Doc-URLs are persistant and contain provenance information they can never be deleted completly. While the same is true of non document IRIs, data relating to these IRIs can be removed, thus emptying the current instance of the IRI. Deleting can either be done using a HTTP DELETE request on the Edit-IRI or by POSTing a blank document to the same IRI, both have the same affect.

Due to the fact that many documents can annotate a single Data-IRI, Data-IRIs MUST NOT directly support delete. This can only be achieved via document updating/deletion as outlined in this section.

8.3.1 Deleting a Document

Here the clients intention is to DELETE an Edit-IRI (the document container IRI), removing all data related to this document as well as information about the document itself. In order achieve this the client should request that the Edit-IRI be deleted, as follows:

DELETE Edit-IRI HTTP/1.1
Host: example.org
Date: Sun, 1 Jan 2012 09:00:00 +0000
Authorization: LDS LDSAccessKeyId:Signature

Due to the requirement to maintain historical information the server MUST handle this request in the same way as a blank post:

• The server SHOULD create and annotate a new Doc-URL with relavent provenance information.
• The server SHOULD update any local indexes to reflect the changes, removing and archiving old data from these indexes
• The server MUST NOT delete the old document which is being replaced
• The server SHOULD automatically link the "new" document to the previous version

While a delete operation is supported, for historical reasons the Edit-IRI should not be deleted completely (neither should any of the Doc-URLs). It is up to the server to decide if it still supports GET requests on the documernt-URI or marks the document as deleted and returns a 410 Gone response.

The server MUST support the re-use of an Edit-IRI, this can either be supported via a PUT or POST request to the Edit-IRI both the client and server have the same responsibilities as outlined in section 8.2.1.

A unit test client is available here, this test client will attempt to delete an existing Edit-IRI with the above data. A valid Edit-IRI must be defined.

8.3.2 Delete via POST

Delete via post simply represents an update (as in 8.2) where the document contains empty nodes, for example the client could post the following document:

POST Edit-IRI HTTP/1.1
Host: example.org
Date: Sun, 1 Jan 2012 09:00:00 +0000
Content-Length: xxx
Content-Type: application/rdf+xml
Authorization: LDS LDSAccessKeyId:Signature

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:contact="http://www.w3.org/2000/10/swap/pim/contact#"
	 xmlns:foaf="http://xmlns.com/foaf/0.1/"
	 xmlns:dcterms="http://purl.org/dc/terms/">

</rdf:RDF>

As in 8.2 the client has many options for the update and the requirements on the server and client remain the same.

A unit test client is available here, this test client will attempt to edit an existing Edit-IRI with the above data. A valid Edit-IRI and IRI-Prefix must be defined.

8.3.3 Deleting Data

Due to the fact that many documents can annotate a single Data-IRI, Data-IRIs MUST NOT directly support delete. This can only be achieved via document updating/deletion as outlined in this section.

8.4 Retrieving Data

This section does not define any requirements on the server or client, but makes some recomendations on best practice and outlines some of the posibilities of what can be achieved by using this specification.

Generally:

• The server SHOULD allow the client to request Doc-IRIs, Edit-IRIs and Data-IRIs where possible.
• The server SHOULD allow the client to perform content-type negotiation against all retrievable IRIs and support formats such as RDF, JSON and Turtle amoungst others.

It is advisable that any server implemenation use software such as [Puelia-PHP] which already provides a number of serialisations for data as well as the capability to serve it from a SPARQL server where it may be indexed.

8.4.1 Implementing a Timegate

Due to the server storing all historical instances of documents (and thus data) it should be possible for the client to be able retrieve historical data for any IRI (except Doc-URLs which are static already) using the [Memento TimeGate] specification.

The only issue here is that the server may not have historical versions of IRIs indexed, thus in order to acurately serve data from a specific time the server will need to build a tempory index in a sandbox and serve the data from this index. In this way content negotion can still happen against the tempory index instead of a whole new system being required. The server may choose to delay the processing of requests and the client should support the fact it might take some time to complete its request.

More on implementing a TimeGate will follow at the point when a reference implemenation is developed to accompany this specification.

9. References

[Amazon Authentication Model] Amazon, "Authenticating Requests Using the REST API", Amazon Web Services Developer API, March 2006, http://docs.amazonwebservices.com/AmazonS3/latest/dev/S3_Authentication2.html)

[iso8601] "Data elements and interchange formats -- Information interchange -- Representation of dates and times", ISO 8601, 2004, http://www.iso.org/iso/catalogue_detail?csnumber=40874

[Memento TimeGate] VandeSompel et al, "HTTP framework for time-based access to resource states - Memento", Internet Draft, December 2011, http://www.mementoweb.org/guide/rfc/ID/#HTTP_TimeGate

[Puelia-PHP] - http://code.google.com/p/puelia-php/

[RFC2616] Fielding et al, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999 http://www.w3.org/Protocols/rfc2616/rfc2616.html