...

https://tools.ietf.org/html/rfc7089#section-7

Delta Documentation

For versioning: Versioning Delta/Specification Notes

For authorization: TBD

Anchor
design design

Design

Before reading through this, it would be good to review the Fedora Specification Versioning Section as well as understand the Memento Terminology. 

This design relates specifically to how versioning could be done in the Modeshape Implementation of Fedora 4

...

Anchor
players players

Players

...

• LDPR - original resource
• LDPRv - same as LDPR, but it has the versioning interaction model turned on (http://fedora.info/definitions/fcrepo#VersionedResource). This implies that it is a TimeGate and has a TimeMap.
• TimeGate - a resource which provides access to LDPRms belonging to a LDPRv via datetime negotiation.  This is the LDPRv.
  
• LDPCv - a LDP container that contains the LDPRms associated with a LDPRv.  Since the TimeMap response is generated from this information the LDPCv and TimeMap are generally considered to be the same, but the LDPCv may contain more information than what is delivered in a TimeMap response. 
• TimeMap - a resource from which a list of URIs of Mementos of the Original Resource is available.
  
• LDPRm - a specific version/memento of a LDPR.  The LDPRv is not a LDPRm itself.

...

Anchor
rest rest

RESTful Interactions

1. Enable Versioning on a LDPR

   1. A PUT or POST request to create an object will make a resource versionable if it includes header Link: rel="type" with type of http://fedora.info/definitions/fcrepo#VersionedResource

      1. A LDPR will be created as a LDPRv with the versioning type.

      2. A LDPCv will be created, from which a TimeMap can be generated.

      3. A LDPRm will be generated, contained by the LDPCv.

      4. Any subsequent responses from the LDPRv will include the appropriate memento links in the header: Timegate, Timemap

   2. A PUT request to an Existing LDPR will make a resource versionable if it includes header Link: rel="type" with type of http://fedora.info/definitions/fcrepo#VersionedResource

      1. The versioning type will be added to the LDPR, making it a LDPRv.

      2. A LDPCv will be created, from which a TimeMap can be generated.

      3. A LDPRm will be generated, contained by the LDPCv.

      4. Any subsequent responses from the LDPRv will include the appropriate memento links in the header: timegate, timemap

2. Check if a resource is versionable and discover the TimeMap/LDPCv

   1. A HEAD request on the LDPRv will return response with Link rel="type" http://fedora.info/definitions/fcrepo#VersionedResource which indicates versioning support and a 'Link rel="timemap"' points to the URL of the LDPCv/TimeMap.

3. Check if the client can create versions

   1. An OPTIONS request on LDPCv/TimeMap that contains an "Allow: POST" header indicates that versions can be created by a client.

4. Creating a new version of a LDPRv 

   • Note: when creating a new version of the LDPRv, only the single resource itself will be versioned. There is no concept of "tree" snapshots anymore. 

   1. A POST request to the LDPCv with an empty body and no "Memento-Datetime" header will cause a new memento of the LDPRv to be created with current date/time. 

   2. A POST request to the LDPCv with header "Memento-Datetime" and no body will create a historic verision with current state of the LDPRv with the specificed date/time. 

   3. A POST request to the LDPCv with header "Memento-Datetime" and a body will create a historic version with the specified body and date/time.

   4. A POST request to the LDPCv with a body and no "Memento-Datetime" header to create a version with the specified body and the current datetime.

5. Access the TimeMap (LDPCv) to see what versions exist

   1. A GET request to the LDPCv with the "Accept: application/link-format" header will cause the TimeMap to be returned. 

   2. A GET request to the LDPCv with no "Accept:" header, or one specificying an RDF format will result in the LDPCv being returned in rdf format. 

   3. The response from the GET will include a "Vary-Post: Memento-Datetime" to indicate that a client can request a specific time be associated with a memento when it's created via a POST. 

6. Access an existing version (LDPRm)

   1. A GET request to the TimeGate Resource (the LDPRv itself) with "Accept-Datetime" header specified will return the LDPRm associated with that datetime, or the closest one if there is not an exact match. 

      • example header usage:  "Accept-Datetime: Thu, 31 May 2007 20:35:00 GMT"

      • a Link header will be in the response to show the TimeGate URI 

   2. A GET request to LDPRm/Memento (if the LDPRm/Memento has its own URI), will result in the memento being returned if it exists.

   3. See: Datetime negotiation algorithm example for Accept-Datetime negotiation details.

   4. Any response from the LDPRv will include link relation headers of type "timegate" (referring to the LDPRv), "original" (also referring to this LDPRv), and "timemap" (referencing the URI of the LDPCv). 

7. Delete an existing version (LDPRm)

   1. A DELETE request to LDPRm/Memento will result in that memento being deleted. 

8. Restore an existing version (LDPRm) 

   • Note: This interaction still needs to be ironed out as this is currently under discussion in Spec Issue 217

   1. A PUT request to LDPRv/TimeGate with header (can't be Content-Location, but something like it) pointing to the LDPRm/Memento URI to indicate the version to restore
      - OR - A PATCH request to LDPRv/TimeGate with no body and a "Memento-Datetime"  header indicating the version to restore, will result in the memento that relates to that date/time being restored. 

...

Internal Interactions / Algorithms

Finding the ACL on a LDPRm (memento): 

...

This section describes the algorithm used in figuring out which memento will be returned on a GET request to the TimeGate with an Accept-Datetime header. 

...

Internal Representation of resources

Here's an example of a LDPRv - what signifies that it is a LDPRv is that a request on the LDPRv returns memento related 'Link' headers in the reponse.  These 'Link' headers point to the TimeMap and TimeGate for this resource . The current behavior is that a 'hasVersions' triple is returned when a LDPR is requested. 

...

@prefix acl:  <http://www.w3.org/ns/auth/acl#> .
@prefix iana:  <http://www.iana.org/assignments/relation/> .
@prefix ldp:  <http://www.w3.org/ns/ldp#> .
@prefix memento:  <http://example.com/memento#> .
@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix time: <http://www.w3.org/2006/time#> .

</path/to/resource/xyz/fcr:versions/12345> a ldp:RDFSource , prov:InstantaneousEvent;
    prov:atTime "2012-04-30T20:40:40"^^xsd:dateTime;
    memento:hasTimegate </path/to/orig/resource/xyz> ;    # how else can we represent this? is this this a given based on url?
    memento:hasOriginalResource </path/to/orig/resource/xyz> ;   # how else can we represent this? Is this a given based on url? 
    iana:next </path/to/xyz/fcr:versions/12346> ;   # to memento
    iana:prev </path/to/xyz/fcr:versions/12344> ;   # to memento
    
   ... triples from original resource at the time of versioning... 
 
 or, if we keep them separate, it might look like this:
(I'm not clear on how a binary and it's metadata would be represented)
    ldp:contains </path/to/xyz/fcr:versions/12345/version> ,
        </path/to/xyz/fcr:versions/12345/version/fcr:metadata> ;   
    

Design Questions

Open Questions

• Do we need a separate memento ontology or can we use PROV-O for most things? 
• For information about TimeMap and TimeGate can these resources not list them explicity and just use some known url formatting for this?  We may not need the pointers to the TimeGate  / TimeMap inside the resources.
  • Timegate is LDPRv URL
  • TimeMap is LDPRv URL + "/fcr:versions"  
  • The code that retrieves the memento can construct the "original", "timemap" and "timegate" link headers from it's own URL – is that okay to do?
• If the mementos have containment triples which point to other resource (either LDPRs or LDPRm's) how do we avoid an issue of the child being in two containers? 
  • LDPRm Creation Example
  • Discussed by a subgroup – decided that we need to research this more. 

...