Community:Collections and Metadata/Annotations Functional Requirements

From NSDLWiki

Jump to: navigation, search




Draft #1 of 2001-12-09
Diane Hillmann


1.1. According to the American Heritage Dictionary of the English Language, Fourth Edition, an annotation is a "critical or explanatory note; a commentary." NSDL intends to provide options for users to contribute annotations or reviews of resources.

1.2. Other kinds of annotations, such as those that might be attached to links (currently termed "link labels") are not specified in this document.

1.3. This document is part of the draft documentation archived in the "Annotation Services" workspace at


2.1. Annotations may be in any format supported for content. Support for textual annotations will be available in the first release; support for other formats will follow in subsequent releases.

2.2. Annotations will be stored in a Content Repository, along with the relevant metadata. The metadata will be harvestable by the Metadata Repository for the purpose of making the annotations available for searching.

2.3. Annotation content will not be made available for harvesting, and may be revised or updated only by the MR Administrator or the creator of the annotation.

2.4. Annotations may be created on the NSDL site or supplied in batch by annotation services. Only batch files for annotations that support the standard Content Repository format for annotation storage will be available in the initial releases of NSDL. [This basically says that anyone that implements annotations the same way that we do can also give us annotation metadata that goes in the MR. That should be trivial for us to support - if we can deal with one Annotation service/CR combo, then we should be able to do two or more ][Previous comment - This feels odd. Why are we ingesting all annotations centrally? Don't we just want to inject the metadata about annotations, which means that the annotation metadata record had better say where the annotation sits and not assume that all annotations sit in the content repository?]

2.5. Search result sets that contain annotations will always also contain the the resources to which the annotations apply.

2.6. Annotations are always associated with users who have been authenticated by the Columbia authentication protocol. Annotations are handled the same way as other user created content by the User Profiles database. [The relationship of annotations to the User Profiles will be described in the Columbia documentation - well, it needs to be described here]


3.1. Requirements for annotations include:

  • support for a display of indications of the presence of annotations with items or associated collections
  • support for display of all annotations relevant to an item or collection, both as brief listings of all available, or as a single annotation [Again, I think we better think very carefully of how we will control junk and objectionable stuff here. How does amazon control profanity on its reviews? How much human effort is there?]
  • support for variable display of information about annotators, based on choices made at the time of registration
  • an input process for single, user-contributed annotations will be developed for the initial release
  • batch ingest process for annotations made available for harvesting by services will be available in the same format as that used by the central annotation service. Other annotation formats may be supported after the first releases of NSDL.
  • a record format for annotations and annotation metadata [TBA]

Each of these requirements is discussed in the sections below.


4.1. [Annotation elements and definitions will be described in a separate document]

4.2. The default display of a group of annotations is brief, consisting of a name or alias for the annotator [Does allowing arbitrary aliases suffice to deal with privacy issues? Do we get into privacy issues here? How much information do we want to give about the annotator?] (underlined to indicate a link to other displayable information about the annotator), a defined number of characters of the annotations text, and a a “more info” button linking to the full annotation.

4.3. Single annotations should be displayed in full form.

4.4. Annotations received as batch files will be crosswalked if received in a different format. This will not be supported in the initial NSDL release. [DBK - we should NOT centrally store all annotations. Again. we centrally store all annotations??. I can imagine annotation services that don't want us to sotre their annotations]

4.5. If a description field exceeds the fixed number of characters allowed in the display, the description should be truncated at the last full word, and end with ellipses.

4.6. If the content to which an annotation refers is not online, a link to a message will be made instead of to a resource. If the collection wishes to support a link to a collection-specific message giving instructions for obtaining the item, this will be supported, otherwise a generic message maintained by NSDL as a help file will be at the end of the link.


5.1. [The metadata format for annotations will be described in a separate document]

5.2. The metadata will not include the text of the annotation (if the annotation is textual), although keywords may be extracted from that text for the purpose of searching. However, the metadata may include a textual summary of the purpose or nature of the annotation.

5.3. Metadata for textual annotations will be created automatically from the annotation, and will be harvested using the methods developed for other content registries. Metadata for other formats may be requested from the creator, or defaults supplied.

5.4. Metadata for annotations that consist of numerical rankings of content items will be supported. [This is the Amazon-style model, and it sure helps in finding things compared to just text-only annotations. Big question - do we go here?]


6.1. Annotations may be created by registered users only, and all NSDL annotations will be linked to a registered user.

6.2. Anonymous annotations will not be accepted. [Ok, but does this mean that annotators will be identified by name, e.g., on e-bay i'm identified by my user idea and people can send me email through ebay - DBK-I would say that users can use arbitrary unique aliases. We do need to be able to track them down as administrators.]

6.3. As part of the ingest process, the user should be prompted to add information to their user profile, particularly information that might be of use to a reader of their annotation. [Do we support any way to "verify" or provide authority supporting user's statements about themselves?]


7.1. Annotations maintained by the NSDL may be updated or deleted by the creator or by the MR Administrator. Update or deletion of the annotation will trigger modification of the metadata record for that annotation.

7.2. Annotations received from other services may be updated or deleted in batch mode. Updated or deleted annotations will trigger modifications on the metadata record.


8.1. Contact information may be made publicly available at the option of the annotator. Contact information already in the user profile will not be linked from the annotation unless the user has explicitly given permission for their contact information to be revealed to other users. [ok, this answers some of my questions. We should consider ebay, amazon models]


9.1. User authentication for the creation of annotations will be similar to that for other NSDL functions.


10.1. Resources in a result set which have associated annotations will have an option to see the annotations, in a manner similar to the "more info" button.

10.2. Annotations will be displayed in a new window in the lower left quadrant of the screen.

10.3. Multiple annotations will be in a brief tabular display with the name of the annotator and a fixed number of characters of the annotation. A link to the entire annotation will be provided with the name.

10.4. Single annotations will display as full records, including creator, the full text of the annotation, and the date of the annotation.

10.5. Full annotations will be displayed with a link to additional information, including the name of the annotator, additional information available about the annotator (and released for display by that annotator).

Personal tools