[Prev][Next][Index][Thread]
High-level annotation issues
Hello everyone on the collab-annotation list. I wrote the following
draft of a design document for an annotation protocol late last night.
It presents the gist of the major ideas I am incorporting into the
protocol, so it is worth discussing at this point.
dan
---
The annotation protocol concerns how clients communicate
with annotation servers in order to manipulate annotations.
An annotation is defined as any object that is associated with another
object by some relationship. (Perhaps that is more general than needed.
It also strays from the "modification" aspect of annotations. Give me an
alternative definition.) The annotation object may be of any type and the
relationship between the annotation object and the object it
annotates may also be of any type.
Often an annotation is intended to be displayed with the object it
annotates, but this is not necessarily the case. An annotation may be
processed and have no visible evidence - it may act as a filter on a
collection of information, as in SOAPs for example, removing components
that are not desired or selecting only those that are desired.
If an annotation is displayed with the object, it may be an invasive
display, a less invasive overlay or sidebar, or an appendage at the end
or in a separate frame. The annotation may be represented in whole
(e.g. embedded) or in part (e.g. title only). The target of an
annotation may be the object as a whole or a segment of it. The way to
specify a segment of the object varies depending on the object type. A
more universal URL scheme might allow the segment spec to be folded into
the URL, similar to how http URLs with named anchors approximate this.
The object that is annotated, called the target, need not be informed of
the existence of the annotation or endorse it in any way, but the target
may know (via its metadata) about some annotations, and may offer that
information to clients.
An annotation server, like other document servers, may have
restrictions on access to its documents and services. The mechanisms
for these restrictions and the management of information pertaining to
who has what capabilities is orthogonal to and therefore beyond the
scope of the annotation protocol. The protocol itself, however, should
be designed to facilitate having different restrictions on each of the
distinct functions in the protocol.
An annotation server may serve annotations for several distinct sets of
URLs. Each set, called an annotation set, should be considered a
distinct logical grouping or collection that is independent of other
sets that may be on the same server, except for the following. An
annotation set may contain several annotation subsets and may be
contained by several annotation supersets. Subsets and supersets may be
on different servers. Everything about a single set should probably
be on a single server, but not necessarily if we can make it work.
The value of subsetting is that properties of a set may be inherited
from supersets. Access restrictions are an obvious example. Anyone
that can read annotations from a set could also read annotations in a
subset.
This DAG structure of annotation sets should apply to collections
in general, and a separate protocol for dealing with collections needs
to be defined for use by the annotation protocol. We could define
the collection protocol first and make it visible, or just define the
annotation protocol hiding the collection protocol it is built on.
(This is inheritance vs composition, in OO terms.)
The server of annotations itself may or may not know about all the
annotation sets it serves, so the annotation protocol should not be
about talking with annotation servers so much as annotation sets. An
annotation set should know about any subsets it contains, however. It
should not be the case that all annotation sets on a server must be
contained in a single annotation set.
The set of annotations of an object is another collection. Annotations
of annotations may be in the same annotation set as the annotation, but
note that a different object is being annotated.
The annotation protocol should facilitate scalable lookup of annotations
by clients and servers. This implies that annotation servers should be
able to offer information to clients about all the URLs that have
annotations or may have annotations so that clients may avoid making
requests of a server that has no annotations in the set. This set may
be given in terms of a pattern or list of alternative patterns to
abbreviate the transfer and speed the lookup. The format of such
patterns should be in the scope of the annotation protocol.
The annotations may be of any type, as mentioned previously. But for
the annotation protocol, we need to define some attributes that are
common across all annotations. These attributes *of* an annotation
might be considered metadata for the annotation, but let's avoid that
debate by defining the protocol such that these attributes will be
available given a URL for an annotation. (Similarly, the annotation
*of* an object may be considered metadata for the object - it is
certainly distinct from the object, but to call it metadata may be
irrelevant.)
The attributes common to all annotations are very simple and deal with
the fact that they are annotations as defined above. In addition to
attributes that an object might have independent of being an annotation
and which can vary between each annotation, such as the owner and a
redirect URL, an annotation must have a list of annotation references.
Each annotation reference is composed of the following: a URL for the
object that is the target of the annotation, an optional segment within
the object, and the relationship of the annotation to the target.
The functions of the protocol may be divided into those concerning
annotation sets and those concerning individual annotations in the sets.
Annotation Sets are objects in their own right - they have URLs.
The operations on an annotation set refers to it by the URL.
Create (name: string, descriptionDoc: URL) return URL of set.
- a new annotation set is created with no superset.
Destroy (aSet)
Add Subset (aSet, aSubset)
Delete Subset (aSet, aSubset)
- this is how you put one set in another and remove it.
Get Subsets (aSet)
Get Supersets (aSet)
Add URL Pattern (aSet, aPattern)
- a pattern may be a specific URL too.
Delete URL Pattern (aSet, aPattern)
- deletion may be equivalent to adding a negative pattern.
Add Annotation (aSet, URL, annotation)
- the annotation of the URL is added to the set
Get Annotations (aSet, URL, selector, parts)
- return all annotations of the URL in the set. If selector given,
select only those annotations that meet the criteria. If parts
given, return the parts requested from each annotation.
This is getting close to a query language. It could be considered
part of the protocol for searchable collections.
An annotation is an object with a URL.
Get (URL) - get the annotation object.
Follow-Ups: