Resource Versioning

Trellis keeps track of every change made to a resource. It stores this efficiently by modeling a resource as a stream of changes over time, meaning that the state of a resource at any arbitrary point in time can be retrieved. This is done by following the Memento interaction pattern for accessing resource versions.

For instance, given a resource at https://example.org/container/resource, a client can begin a datetime negotiation by adding the header Accept-Datetime to its request.

Accept-Datetime: Mon, 30 Oct 2017 20:15:00 GMT

For those familiar with the Memento standard, each resource serves as its own timegate. (A TimeGate is a special resource type that allows datetime negotiation via the Accept-Datetime header).

The response will be a redirect to a particular Memento (i.e. version) such as https://example.org/container/resource?version=1508889600734

The value of the version parameter is just a UNIX timestamp with millisecond precision. Provided that the timestamp is a valid value, it will be used to generate the resource representation. That resource will advertise the fact that it is a Memento with a Memento-Datetime header:

Memento-Datetime: Wed, 25 Oct 2017 00:00:00 GMT

Memento resources are always immutable. They are exact versions of the resource at the given moment in time. It is also not possible to change or delete them using the standard LDP operations. A client will notice the lack of POST, PUT, PATCH and DELETE in the Allow header in these responses. Such methods are also absent from an OPTIONS response to a Memento resource.

All Trellis resources are versioned with the exception of the root resource (below the level of the partition).

TimeMaps

Each Trellis resource will also advertise a list of versions it makes available (a client can always request a version from an arbitrary point in time, even if that version isn't listed in the Timemap). Those values will be available in the Link headers, defined with a rel="memento" parameter.

A client can also request a TimeMap resource by following the Link: <timemap-url>; rel="timemap" header. In Trellis, that will always be the URL of a resource followed by ?ext=timemap. This resource is a full-fledged LDP-RS though it is immutable. The TimeMap resource describes all Memento resources for a given LDP-Resource, including its location and the datetime dimensions of the resource. In addition to generating representations as RDF (using the PROV-O vocabulary), TimeMaps also produce representations in a application/link-format serialization. Each serialization provides exactly the same data.

If a client can retrieve a resource an any arbitrary point in time, a logical question is: why are certain moments in time included in the TimeMap? In Trellis, there is a simple rule: whenever a resource is directly modified by a client, there will be a new entry in the TimeMap. If a resource changes only because of a change in Containment or Membership triples, that will not create a new entry in the TimeMap.

A sample TimeMap serialization is below:

@prefix memento: <http://mementoweb.org/ns#> .
@prefix time: <http://www.w3.org/2006/time#> .

<resource> a memento:OriginalResource, memento:TimeGate ;
  memento:timegate <resource> ;
  memento:timemap <resource?ext=timemap> ;
  memento:memento <resource?version=1> , <resource?version=2> , <resource?version=3> .

<resource?ext=timemap> a memento:TimeMap ;
  time:hasBeginning <http://reference.data.gov.uk/id/gregorian-instant/2004-04-12T13:20:00> ;
  time:hasEnd <http://reference.data.gov.uk/id/gregorian-instant/2012-06-02T11:51:00> .

<resource?version=1> a memento:Memento ;
  memento:original <resource> ;
  memento:timegate <resource> ;
  memento:timemap <resource?ext=timemap> ;
  time:hasTime <http://reference.data.gov.uk/id/gregorian-instant/2004-04-12T13:20:00> ;
  memento:mementoDatetime "2004-04-12T13:20:00Z"^^xsd:dateTimeStamp .

<resource?version=2> a memento:Memento ;
  memento:original <resource> ;
  memento:timegate <resource> ;
  memento:timemap <resource?ext=timemap> ;
  time:hasTime <http://reference.data.gov.uk/id/gregorian-instant/2007-01-02T17:42:00> ;
  memento:mementoDatetime "2007-01-02T17:42:00Z"^^xsd:dateTimeStamp .

<resource?version=3> a memento:Memento ;
  memento:original <resource> ;
  memento:timegate <resource> ;
  memento:timemap <resource?ext=timemap> ;
  time:hasTime <http://reference.data.gov.uk/id/gregorian-instant/2012-06-02T11:51:00> ;
  memento:mementoDatetime "2012-06-02T11:51:00Z"^^xsd:dateTimeStamp .