• Name: Annotate
  

This Service Genre has been developed from a wide range of projects and work across the partners. Systems are often required to allow users to make comments, notes or other annotations to existing data items within a collection, without alterting the base item itself. This Service Genre has been developed to show the functionality and behaviours required of Services that seek to fulfill this requirement.

• v1.1

This Service Genre describes the assignment of annotations from an open ended set to an object. An example of this might be to add a footnote to a document, or to add a comment to a blog entry.

The original object MAY be modified by the Annotation Service. Annotations MAY be applied to a proxy of the original object. Annotations MAY be included as metadata. The Service Genre does not dictate how annotations are to be attached to the original object. There is no limit to the number of annotations that can be made to an object.

Annotations are made by specific actors and the identity of the Annotator SHOULD be made known. Anonymous annotation is OPTIONAL.

As defined the Annotate Service Genre is not access controlled. Any client may attempt to contact an Annotate service end point. There are no authentication controls. The service end point is responsible for determining which individual objects can be Annotated and which clients can make annotations to existing content.

The Annotate Service Genre supports functions that enable the creation, update and deletion of annotations:

Apply annotations: Add a new annotation to an existing resource or content. The annotation would typically be text, and would represent a footnote, endnote or inline comment. Services would modify either the original content, a proxy, or add an attachment as defined by the Service Expression.

Remove Annotation: Remove an existing annotation from an existing resource or content.

Edit Annotation: Edit an existing annotation. Services modify the target annotation, however it was applied to the content. Annotations must exist in order to be modified.

No other functionality is defined. The functionality that is defined MAY be extended.

Annotation Services are useful in distributed collaborative environments. Authors can share comments on work, leading to improvements in quality.

Annotation SHOULD NOT be used as an alternative to issuing new versions of the original source object.

Care should be taken with Annotations when controlled editing of documents is used.

Annotate SHOULD be used when an unordered, unbounded value is to be assigned to an object.

Annotations MAY be applied to collections of objects as well individual objects.

Annotate SHOULD NOT be used if an ordered, bounded value is to be assigned to an object. Rating SHOULD be used instead.

Annotate SHOULD NOT be used if an unordered, bounded value is to be assigned to an object. Classify SHOULD be used instead.

Requests SHOULD be implemented to enable all functionality.

Create Annotation SHALL meet the following conditions:

• The Request SHOULD specify:
  • The author of the annotation.
  • The target object to be annotated.
  • Data which is the annotation.

Remove Annotation SHALL meet the following conditions:

• The Request SHOULD specify:
  • The author of the annotation.
  • The target annotation to be altered.
  • The new data which is to be the annotation.

Edit Annotation SHALL meet the following conditions:

• The Request SHOULD specify:
  • The target annotation to be deleted.

Responses SHOULD:

• Indicate any error conditions (such as the Annotation not being accepted).

Individual Service Expressions SHOULD provide models showing how clients interact with service interfaces.

None

Authorisation SHOULD be considered when specialising this Service Genre. Specifically, whether owners of the original object are authorised to delete and edit Annotations. Additionally, Service Expressions should consider whether Annotations can be modified by other Annotators.

The management of which objects can be annotated SHOULD be considered by the Service Expression or SUM which incorporates Annotation.

Annotea

• UK HE Admissions Structured Personal Statement v1.2