A Version and Variant Authoring Protocol Jim Whitehead

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

Design Principles (1) z The version graph and the variant graph are both metadata (and are both the same graph) y. The derived-from and variant-of relationships between versions and variants of resources are true metadata (information about information) y. Hard-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.

Version/Variant Graph is-variant-of foo. html vid=1. 0 lang=en foo. html vid=1. 1 fr lang=fr foo. html vid=1. 0 fr lang=fr is-derived-from is-variant-of foo. html vid=1. 1 lang=en is-derived-from is-variant-of foo. html vid=1. 2 lang=en

Design Principles (2) z. Versioning and variant authoring are both handled by the same protocol. y. Versioning and variant authoring are both operations which manipulate the version/variant graph (or Vgraph) x. Manipulate is-derived-from and is-variant-of relationships between resources. y. Both services require very similar relationship management capabilities

Design Principles (3) z. Versioning of collections must be supported y. Corollary: A versioning protocol which precludes (or makes very awkward) versioning of collections is not acceptable. y. Software development and compound documents are two domains which require this support.

Design Principles (4) z. No standard mapping of versioning space to URL space y. Instead, provide standard operations so a client can flexibly perform this mapping. y. Many Web versioning systems require a standard mapping of versioning space to URL space, with these fatal drawbacks: x. It adds semantics to URLs, making them nonopaque, and subject to namespace collisions with other such URL "munging" schemes.

Design Principles (4) z Drawbacks of a standard mapping of version space to URL space (cont’d): y. It hard-codes derived-from relationships into version identifiers, limiting their expressiveness, for example, mandating "1. 2" instead of "Jim's interim version". y. Since 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.

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

Design Principles (5) z. When performing content negotiation, send a GET to a resource with Accept headers. z. When 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.

Design Principles (5) z. Content 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.

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

Key Abstractions z There are three key abstractions: y. Vgraph x. A version/variant graph y. Vhandle x. A “pointer” to a Vgraph x. Supports structure operations on Vgraphs y. Vportal x. A version/variant query resource x. Supports content manipulation operations on Vgraphs (set default, checkin, checkout). y. A single resource can simultaneously be both a Vhandle and a Vportal

Example Version Space HTTP URL Space Vgraph Vhandle for this Vgraph vgraph: 56 de-a 45 c-436 abf 87 -d 32 a Vgraph Vhandle for this Vgraph - collection vgraph: 304 e-a 4 d 7 -667 d 43 a 5 -4 a 32 - Vhandle

Example Version Space HTTP URL Space Vgraph vgraph: 56 de-a 45 c-436 abf 87 -d 32 a default for this Vportal Vgraph default for this Vportal vgraph: 304 e-a 4 d 7 -667 d 43 a 5 -4 a 32 - Vportal - collection - Vhandle

Example Version Space HTTP URL Space Vgraph vgraph: 56 de-a 45 c-436 abf 87 -d 32 a Vgraph vgraph: 304 e-a 4 d 7 -667 d 43 a 5 -4 a 32 default for this Vportal - collection - Vhandle

Example Version Space HTTP URL Space Vgraph vgraph: 56 de-a 45 c-436 abf 87 -d 32 a Vgraph - Vportal - collection vgraph: 304 e-a 4 d 7 -667 d 43 a 5 -4 a 32 - Vhandle

Vgraph (1) z. A Vgraph is a directed acyclic graph which models the versions and variants of a conceptual resource. z. A Vgraph contains: y. Resources (by reference), which are the nodes of the graph y. Typed binary relationships, which are the arcs of the graph x. Two relationships: is-derived-from, is-variant-of

Vgraph (2) z. Each version and variant of a conceptual resource is a separate resource, with a separate URI. z. Nodes are referentially contained in a Vgraph y. Nodes are identified by their URI z. Nodes and arcs can have properties y. Node properties in a Vgraph have a 1: 1 correspondence to regular properties

Vgraph (3) z. A Vgraph has a globally unique identifier, which is a URI (the vgraph: URI scheme is defined for this purpose). z. All elements of a Vgraph must have globally unique identifiers: y. Nodes: URIs y. Arcs: A unique id using the arcid: URI scheme defined in the spec.

Vgraph Benefits (1) z. A Vgraph can represent a version/variant graph which: y. Spans multiple servers y. Contains resources from multiple URI schemes (e. g. FTP) z. Since resources aren’t directly contained by a Vgraph, a resource may participate in more than one Vgraph y. One with released versions, another with all

Vgraph Benefits (2) z. Media Type Independent: y. A Vgraph can express is-derived-from and isvariant-of relationship between resources of any media type. y. The media type can vary from resource to resource in the Vgraph (hence able to express different renderings)

New Methods Overview z CREATE - Make a new Vhandle or Vportal z DIFF - Retrieve difference between 2 resources z PATCH - Apply a difference to a resource z GRAPHOP - Add/Remove nodes & arcs to a Vgraph z GRAPHGET - Retrieve a listing of a Vgraph z DEFSET - Set default member of a Vgraph z CHECKOUT - Start versioned editing session z CHECKIN - End versioned editing session

CREATE z. Creates a Vhandle, Vportal, or combination Vhandle and Vportal resource z. When creating a Vhandle, the client either: y. Submits the URI of an existing Vgraph (the Vhandle is for that Vgraph) y. Submits nothing, and a new Vgraph is created (and the URI of the Vgraph is returned).

GRAPHOP (1) z The 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. z Instruction processing MUST occur in the order instructions are received (i. e. , from top to bottom).

GRAPHOP (2) z Instructions 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. z After 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.

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

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

CHECKOUT (1) z. The CHECKOUT method performs the following operations on the Vgraph associated with the Vportal at the Request -URI: y. A 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.

CHECKOUT (2) y. The 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. y. An "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.

CHECKOUT (3) y. The 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. y. Any check-out comments submitted in the request body are stored in the comments property on the working resource.

CHECKOUT (4) y. Access 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. y. Thus, if any error occurs during processing, all operations performed to that time MUST be undone and a proper error result returned.

CHECKIN (1) z The 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. y. The working resource is unlocked. y. The access control for the working resource is set such that no principal has write access (i. e. , it is frozen). y. The server MAY set the version identifier for the working resource to the version identifier specified in the request body.

CHECKIN (2) z. All of these operations MUST be performed, or none are performed. y. Thus, 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.

DIFF (1) z. The response from this method is the difference between two resources. y. Each 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. x. This 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.

DIFF (2) y. The 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. y. The second resource is specified by the Diff header. y. The entity response from DIFF represents the difference(s) between the two request resources.

DIFF (3) y. A 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. y. The 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.

DIFF (4) y. The 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.