1. A Version and Variant Authoring Protocol Jim Whitehead Redmond Interim Meeting June 15, 1998

2. Design Principles (1) zThe version graph and the variant graph are both metadata (and are both the same graph) yThe derived-from and variant-of relationships between versions and variants of resources are true metadata (information about information) yHard-coding derived-from and variant-of relationships in URI naming conventions, as is typical today (e.g., foo.html.en for the English variant of foo.html), leads to serious difficulties as the complexity of the relationships increases to the point where the URI names are insufficient to express these relationships.

3. Version/Variant Graph foo.html vid=1.0 lang=en foo.html vid=1.1 lang=en foo.html vid=1.2 lang=en is-derived-from foo.html vid=1.0fr lang=fr is-variant-of foo.html vid=1.1fr lang=fr is-variant-of foo.html vid=1.1fr lang=fr is-variant-of

4. Design Principles (2) zVersioning and variant authoring are both handled by the same protocol. yVersioning and variant authoring are both operations which manipulate the version/variant graph (or Vgraph) xManipulate is-derived-from and is-variant-of relationships between resources. yBoth services require very similar relationship management capabilities

5. Design Principles (3) zVersioning of collections must be supported yCorollary: A versioning protocol which precludes (or makes very awkward) versioning of collections is not acceptable. ySoftware development and compound documents are two domains which require this support.

6. Design Principles (4) zNo standard mapping of versioning space to URL space yInstead, provide standard operations so a client can flexibly perform this mapping. yMany Web versioning systems require a standard mapping of versioning space to URL space, with these fatal drawbacks: xIt adds semantics to URLs, making them non- opaque, and subject to namespace collisions with other such URL "munging" schemes.

7. Design Principles (4) zDrawbacks of a standard mapping of version space to URL space (cont’d): yIt hard-codes derived-from relationships into version identifiers, limiting their expressiveness, for example, mandating "1.2" instead of "Jim's interim version". ySince a specific version's URL is constructed from a version identifier appended to a base URL, it requires all revisions of a resource to be located on the same server, and resources are limited to membership in just a single Vgraph.

8. Design Principles (4) zDrawbacks of a standard mapping of version space to URL space (cont’d): yIt handles variants poorly, since extra information must be added to the URL for representing variants of a specific version of a resource xExample: ",v{version_id},var{en,application/pdf}" yIt confuses the distinction between a single Web resource, and all of the resources contained within a Vgraph.

9. Design Principles (5) zWhen performing content negotiation, send a GET to a resource with Accept headers. zWhen retrieving a default (tip) member of a versioned resource (e.g., the most recent version), send a GET to a resource which responds with the default resource.

10. Design Principles (5) zContent negotiated resources and tip resources can be modeled with the same abstraction, a version/variant query resource. ydraft-whitehead-webdav-versioning-00 calls a version/variant query resource a Vportal.

11. Version/Variant Protocol An overview of draft-whitehead-webdav-versioning-00

12. Key Abstractions zThere are three key abstractions: yVgraph xA version/variant graph yVhandle xA “pointer” to a Vgraph xSupports structure operations on Vgraphs yVportal xA version/variant query resource xSupports content manipulation operations on Vgraphs (set default, checkin, checkout). yA single resource can simultaneously be both a Vhandle and a Vportal

13. Example Vgraph vgraph:56de-a45c-436abf87-d32a Vgraph vgraph:304e-a4d7-667d43a5-4a32 HTTP URL Space Version Space - collection - Vhandle Vhandle for this Vgraph

14. Example Vgraph vgraph:56de-a45c-436abf87-d32a Vgraph vgraph:304e-a4d7-667d43a5-4a32 HTTP URL Space Version Space - collection - Vhandle default for this Vportal - Vportal default for this Vportal

15. Example Vgraph vgraph:56de-a45c-436abf87-d32a Vgraph vgraph:304e-a4d7-667d43a5-4a32 HTTP URL Space Version Space - collection - Vhandle - Vportal default for this Vportal

16. Example Vgraph vgraph:56de-a45c-436abf87-d32a Vgraph vgraph:304e-a4d7-667d43a5-4a32 HTTP URL Space Version Space - collection - Vhandle - Vportal

17. Vgraph (1) zA Vgraph is a directed acyclic graph which models the versions and variants of a conceptual resource. zA Vgraph contains: yResources (by reference), which are the nodes of the graph yTyped binary relationships, which are the arcs of the graph xTwo relationships: is-derived-from, is-variant-of

18. Vgraph (2) zEach version and variant of a conceptual resource is a separate resource, with a separate URI. zNodes are referentially contained in a Vgraph yNodes are identified by their URI zNodes and arcs can have properties yNode properties in a Vgraph have a 1:1 correspondence to regular properties

19. Vgraph (3) zA Vgraph has a globally unique identifier, which is a URI (the vgraph: URI scheme is defined for this purpose). zAll elements of a Vgraph must have globally unique identifiers: yNodes: URIs yArcs: A unique id using the arcid: URI scheme defined in the spec.

20. Vgraph Benefits (1) zA Vgraph can represent a version/variant graph which: ySpans multiple servers yContains resources from multiple URI schemes (e.g. FTP) zSince resources aren’t directly contained by a Vgraph, a resource may participate in more than one Vgraph yOne with released versions, another with all

21. Vgraph Benefits (2) zMedia Type Independent: yA Vgraph can express is-derived-from and is- variant-of relationship between resources of any media type. yThe media type can vary from resource to resource in the Vgraph (hence able to express different renderings)

22. New Methods Overview zCREATE - Make a new Vhandle or Vportal zDIFF - Retrieve difference between 2 resources zPATCH - Apply a difference to a resource zGRAPHOP - Add/Remove nodes & arcs to a Vgraph zGRAPHGET - Retrieve a listing of a Vgraph zDEFSET - Set default member of a Vgraph zCHECKOUT - Start versioned editing session zCHECKIN - End versioned editing session

23. CREATE zCreates a Vhandle, Vportal, or combination Vhandle and Vportal resource zWhen creating a Vhandle, the client either: ySubmits the URI of an existing Vgraph (the Vhandle is for that Vgraph) ySubmits nothing, and a new Vgraph is created (and the URI of the Vgraph is returned).

24. GRAPHOP (1) zThe GRAPHOP method processes instructions specified in the request body to add a node or remove a node or add an arc or remove an arc from the Vgraph associated with the Vhandle specified by the Request-URI. zInstruction processing MUST occur in the order instructions are received (i.e., from top to bottom).

25. GRAPHOP (2) zInstructions MUST either all be executed, or none executed. Thus if any error occurs during processing all executed instructions MUST be undone and a proper error result returned. zAfter all instruction processing has completed, the server MUST ensure the graph is consistent by removing all arcs which do not have a node at each endpoint, and all nodes which are not connected to at least one arc.

26. GRAPHOP (3) zSince the Vgraph only contains nodes by- reference, and not by-value, if a node is removed from a Vgraph it does not imply the resource associated with that node is deleted.

27. GRAPHGET zThe GRAPHGET method returns an entity body listing the contents of the Vgraph associated with the Vhandle specified by the Request-URI. yDesign issue: How should the Vgraph entity be returned? RDF is one solution, as is XML without RDF semantics.

28. CHECKOUT (1) zThe CHECKOUT method performs the following operations on the Vgraph associated with the Vportal at the Request-URI: yA new resource, known as the "working resource", is created at a location determined by the server. This resource is acted upon by authoring tools, accepting PUTs of intermediate and final results, and allowing properties to be read and set on it.

29. CHECKOUT (2) yThe initial contents of the working resource are identical to the resource whose version is given by the Videntifier header, if specified, or the default resource if not. yAn "is-derived-from" relationship is added to the Vgraph between the working resource and the resource given by the Videntifier header, if specified, or the default resource if not.

30. CHECKOUT (3) yThe working resource is write locked, with the type of the write lock (exclusive or shared) determined by the server. By default, the lock SHOULD be an exclusive write lock. yAny check-out comments submitted in the request body are stored in the comments property on the working resource.

31. CHECKOUT (4) yAccess permissions MUST be set so the principal requesting the check-out has read and write permission to the working resource. All of these operations MUST be performed, or none are performed. yThus, if any error occurs during processing, all operations performed to that time MUST be undone and a proper error result returned.

32. CHECKIN (1) zThe CHECKIN method performs the following operations on the Vgraph associated with the Vportal given by the Request-URI, and on the working resource specified in the request body. yThe working resource is unlocked. yThe access control for the working resource is set such that no principal has write access (i.e., it is frozen). yThe server MAY set the version identifier for the working resource to the version identifier specified in the request body.

33. CHECKIN (2) zAll of these operations MUST be performed, or none are performed. yThus, if any error occurs during processing, all operations performed to that time MUST be undone and a proper error result returned. A valid CHECKIN request MUST include a Lock-Token header listing the lock token of the working resource's lock.

34. DIFF (1) zThe response from this method is the difference between two resources. yEach of the two resources may be given as the URI of a non-versioned resource, or the URI of a Vportal resource combined with a version identifier. xThis supports differences between two arbitrary resources, two resources in the same Vgraph, resources from different Vgraphs, or between a versioned resource and a non- versioned resource.

35. DIFF (2) yThe first resource is specified by the Request-URI. If the Request- URI is the URL of a Vportal, then the version identifier of a specific member of the Vgraph may be specified with the Videntifier header. yThe second resource is specified by the Diff header. yThe entity response from DIFF represents the difference(s) between the two request resources.

36. DIFF (3) yA server MAY return the difference in any format, however a server MUST minimally support the TBD difference format for all media types, and MUST perform Accept header processing of client diff format preferences. yThe server MUST minimally supply differences between two instances of the same media type, for all text media types encoded using the same charset. Ideally, servers will support differences between all media types, minimally providing an octet-level difference.

37. DIFF (4) yThe server SHOULD supply differences between different instances of the text media type, (e.g. text/html and text/xml), and MAY support differences between media types from different top-level trees. For example, supporting a difference between text/xml and application/xml is possible and meaningful, while a difference between text/xml and image/gif is not.