A Version and Variant Authoring Protocol

1
A Version and Variant Authoring Protocol

• Jim Whitehead
• Redmond Interim Meeting
• June 15, 1998

2
Design Principles (1)

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

3
Version/Variant Graph
is-variant-of
is-variant-of
is-variant-of
is-derived-from
is-derived-from
4
Design Principles (2)

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

5
Design Principles (3)

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

6
Design Principles (4)

• No standard mapping of versioning space to URL
  space
• Instead, provide standard operations so a client
  can flexibly perform this mapping.
• Many Web versioning systems require a standard
  mapping of versioning space to URL space, with
  these fatal drawbacks
• It adds semantics to URLs, making them
  non-opaque, and subject to namespace collisions
  with other such URL "munging" schemes.

7
Design Principles (4)

• Drawbacks of a standard mapping of version space
  to URL space (contd)
• It hard-codes derived-from relationships into
  version identifiers, limiting their
  expressiveness, for example, mandating "1.2"
  instead of "Jim's interim version".
• 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.

8
Design Principles (4)

• Drawbacks of a standard mapping of version space
  to URL space (contd)
• It handles variants poorly, since extra
  information must be added to the URL for
  representing variants of a specific version of a
  resource
• Example ",vversion_id,varen,application/pdf"
• It confuses the distinction between a single Web
  resource, and all of the resources contained
  within a Vgraph.

9
Design Principles (5)

• When performing content negotiation, send a GET
  to a resource with Accept headers.
• 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.

10
Design Principles (5)

• Content negotiated resources and tip resources
  can be modeled with the same abstraction, a
  version/variant query resource.
• draft-whitehead-webdav-versioning-00 calls a
  version/variant query resource a Vportal.

11
Version/Variant Protocol

• An overview ofdraft-whitehead-webdav-versioning-0
  0

12
Key Abstractions

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

13
Example
Version Space
HTTP URL Space
Vgraph
Vhandle for this Vgraph
vgraph56de-a45c-436abf87-d32a
Vgraph
Vhandle for this Vgraph
- collection
- Vhandle
vgraph304e-a4d7-667d43a5-4a32
14
Example
Version Space
HTTP URL Space
Vgraph
default for this Vportal
vgraph56de-a45c-436abf87-d32a
Vgraph
default for this Vportal
- Vportal
- collection
- Vhandle
vgraph304e-a4d7-667d43a5-4a32
15
Example
Version Space
HTTP URL Space
Vgraph
vgraph56de-a45c-436abf87-d32a
default for this Vportal
Vgraph
- Vportal
- collection
default for this Vportal
- Vhandle
vgraph304e-a4d7-667d43a5-4a32
16
Example
Version Space
HTTP URL Space
Vgraph
vgraph56de-a45c-436abf87-d32a
Vgraph
- Vportal
- collection
- Vhandle
vgraph304e-a4d7-667d43a5-4a32
17
Vgraph (1)

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

18
Vgraph (2)

• Each version and variant of a conceptual resource
  is a separate resource, with a separate URI.
• Nodes are referentially contained in a Vgraph
• Nodes are identified by their URI
• Nodes and arcs can have properties
• Node properties in a Vgraph have a 11
  correspondence to regular properties

19
Vgraph (3)

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

20
Vgraph Benefits (1)

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

21
Vgraph Benefits (2)

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

22
New Methods Overview

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

23
CREATE

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

24
GRAPHOP (1)

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

25
GRAPHOP (2)

• 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.
• 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.

26
GRAPHOP (3)

• Since 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

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

28
CHECKOUT (1)

• The CHECKOUT method performs the following
  operations on the Vgraph associated with the
  Vportal at the Request-URI
• 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.

29
CHECKOUT (2)

• 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.
• 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.

30
CHECKOUT (3)

• 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.
• Any check-out comments submitted in the request
  body are stored in the comments property on the
  working resource.

31
CHECKOUT (4)

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

32
CHECKIN (1)

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

33
CHECKIN (2)

• All of these operations MUST be performed, or
  none are performed.
• 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.

34
DIFF (1)

• The response from this method is the difference
  between two resources.
• 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.
• 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.

35
DIFF (2)

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

36
DIFF (3)

• 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.
• 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.

37
DIFF (4)

• 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.