NSDL Registry Use Case Documentation (Vocabularies)

From Metadata-Registry
Revision as of 10:45, 3 October 2005 by Diane (Talk | contribs)

Jump to: navigation, search

Actors

Human Actors

System Administrator
Overall system administrator. Responsible for system-level software and hardware maintenance
Registry Manager
Person (or persons) responsible for the administrative tasks involved in the management of a registry
Vocabulary Editor/Reviewer
Person (or persons) responsible for editorial functions related to submitted vocabularies
Visitor
Anyone viewing or browsing the site who is not logged in, including registered Maintainers who have not yet logged in.
Registered User
A Vistor who has registered himself/herself for the purpose of registering an organization or vocabulary. A Registered User may assume an additional role (Maintainer, Organization Contact) while registering an organization or vocabulary.
Organization Contact
Person acting on behalf of an organization, to whom notifications to the Organization may be sent.
Maintainer
Person responsible for maintaining a vocabulary

Non-human Actors

Registry
The registry software, including user interfaces, processing systems, and services
Service
An interface intended to be used by machines that provides data in response to a request
Service Consumer
Machine requesting data from a service
Organization
Basically a term for for group of persons or an educational or business unit rather than an individual. For instance, an NSDL Project is an organization. In the current context the organization is also the entity responsible for the vocabulary. Vocabularies are associated with an Organization and maintained by a Maintainer who is authorized by the Organization. (Policy question?)

Terms

Vocabulary
[Merriam-Webster] "a list or collection of words or of words and phrases usually alphabetically arranged and explained or defined" ; [In the context of this project] "A set of concepts, represented by words and word relationships, presented in a structured manner." [NOTE: the DC Abstract Model uses the term Vocabulary Encoding Scheme, defined as "A vocabulary encoding scheme is a class that indicates that the value of a property is taken from a controlled vocabulary (or concept-space), such as the Library of Congress Subject Headings"]
Terms
DC Abstract Model "The generic name for a property (i.e. element or element refinement), vocabulary encoding scheme, syntax encoding scheme or concept taken from a controlled vocabulary (concept space)"
Tokens
[from Wikipedia] "In computer science, specifically lexical analysis, a token is usually a word or an atomic element within a string. Tokenizing is systematically replacing portions of a string by such corresponding token"
Simple Knowledge Organization System (SKOS)
[from SKOS Home Page] "SKOS is an area of work developing specifications and standards to support the use of knowledge organization systems (KOS) such as thesauri, classification schemes, subject heading lists, taxonomies, terminologies, glossaries and other types of controlled vocabulary within the framework of the semantic web"
PURLs
[from the OCLC PURL Home page] "A PURL is a Persistent Uniform Resource Locator. Functionally, a PURL is a URL. However, instead of pointing directly to the location of an Internet resource, a PURL points to an intermediate resolution service. The PURL resolution service associates the PURL with the actual URL and returns that URL to the client. The client can then complete the URL transaction in the normal fashion. In Web parlance, this is a standard HTTP redirect"

Policies

WARNING - assumption alert!! Many of the use cases below make assumptions about yet-to-be-decided policies (as of 9/2005)

  • Vocabularies must be associated with an Organization that acts as the Entity responsible for the Vocabulary
  • Vocabulary Maintainers are individuals and they must be associated with an Organization in order to maintain an Organization's Vocabularies
  • A Maintainer may be associated with more than one Organization and more than one Vocabulary
  • Maintainers assertion of association with an Organization will be assumed to be valid unless the organization, after notification of a vocabulary registration, questions the association. In other words, Organizations don't need to specifically authorize individual Maintainers to maintain a specific Vocabulary, but reasonable measures will be taken to assure the Registry against fraud and error.
  • Organizations must be able to be associated with an internet domain that will form the root of individual Vocabulary namespaces, or agree to allow the registry domain to substitute.

Registry Use Cases (Vocabularies)

Use Case 1: A Visitor wishes to register an Organization

Purpose
An NSDL project has a small subject vocabulary that they wish to register and needs to register their organization and at least one Maintainer
Primary Actor
Visitor
Prerequisites
None

Sequence

  1. Visitor accesses the Registry and initiates Organization Registration
  2. Visitor enters basic information about the organization -- Name, address, phone, domain (if available), URL, description, organization contact information including name and email
  3. Visitor submits form and Registry sends confirmation email to organizational contact.
  4. Registry asks if Visitor wishes to register as a Maintainer for that organization
  5. If yes, see Use Case 12
  6. Organization responds to confirmation email
  7. Registry assigns PURL to organization and stores organization info in database
  8. Registry notifies Registry Manager(s) that Organization has been added
Result
Organization is registered. Visitor is now a Maintainer associated with the registered organization.

Use Case 2: Maintainer Registers a Vocabulary

Purpose
A Maintainer associated with an Organization wishes to register the description of a Vocabulary with the Registry. This step is necessary before entering specific terms or uploading terms from an extant vocabulary.
Primary Actor
Maintainer
Prerequisites
Organization must be registered. Maintainer must be associated with that Organization and logged in

Sequence

  1. Maintainer accesses the Vocabulary Maintenance page and selects 'Add new Vocabulary'
  2. Registry displays the 'Add Vocabulary' form, containing a list of Organizations with which Maintainer is associated
  3. Maintainer selects Organization, adds a description of the vocabulary, rights information (see note 1)
  4. Maintainer defines a namespace URI for the vocabulary, based on the Organization's domain
  5. Maintainer submits form
  6. Registry assigns PURL to vocabulary, stores vocabulary info in database and sends confirmation email (no response required)
  7. Registry notifies Registry Manager(s) that Vocabulary has been added
  8. Registry displays a list of other Maintainers associated with this Organization and asks if Maintainer wishes to add them to this Vocabulary and also offers Maintainer the opportunity to Register other Maintainers or add existing Maintainers to this Organization
  9. Maintainer selects from list and/or adds Maintainer registration information for other Maintainers
  10. Registry sends other Maintainers a confirmation email indicating that they have been added to this Vocabulary
  11. Registry offers Maintainer the opportunity to:
    1. Add terms to the new Vocabulary (If yes, see Use Case 3); or
    2. Upload an existing vocabulary encoded in an acceptable syntax (If yes, see Use Case 4); or
    3. Add no vocabulary terms
Result
Vocabulary is registered.

Notes

  1. It might be useful to allow insertion of a full rights text block, a URL of a rights document, or a link to the Creative Commons Rights selection wizard that the MediaWiki setup uses: http://creativecommons.org/technology/web-integration

Use Case 3: Maintainer Registers Terms with a Vocabulary

Purpose
The Maintainer of a Vocabulary wishes to add specific terms to a Vocabulary
Primary Actor
Maintainer
Prerequisites
Vocabulary must be registered. Maintainer must be associated with that Vocabulary and logged in

Sequence

  1. Maintainer accesses "Vocabulary Maintenance' page and selects 'Maintain Vocabulary'
  2. Maintainer selects Vocabulary from a list of Vocabularies with which they are associated
  3. Maintainer adds the required data and some optional data for each term (what data?)
    1. Adds term declaration
    2. Adds relationships between new term and other existing terms
  4. Registry assigns a permanent term URI (PURL) to each term
    1. If Vocabulary has URI assigned by organization, a term URI will also be assigned based on the Vocabulary URI
  5. Maintainer submits terms
  6. Registry validates terms and when the terms pass validation routines, the terms are stored in the Registry
  7. Registry notifies Registry Manager(s) that terms have been added to a Vocabulary
Result
Terms added to Vocabulary

Use Case 4: Maintainer Uploads Vocabulary Terms to the Registry

Purpose
In this case a Maintainer who has already registered the vocabulary as a whole may contribute individual terms via an upload process, subject to validation of the file.
Primary Actor
Maintainer
Prerequisites
Vocabulary must be registered. Maintainer must be associated with that Vocabulary and logged in

Sequence

  1. Maintainer accesses 'Vocabulary Maintenance' page and selects 'Maintain Vocabulary'
  2. Maintainer selects Vocabulary from a list of Vocabularies with which they are associated
  3. Maintainer chooses the 'upload file' option
  4. Maintainer chooses the file to upload from his/her browser window, and submits the file
  5. The Maintainer (and the Organization Contact for the Organization) receive a validation report from the registry, confirming that required elements are present and that the Registry has generated valid URIs for the terms. The notification includes the caveat that the file must be reviewed by the Registry Manager before being inserted into the registry.
    1. If the file does not validate, the notification includes error messages associated with the process, a link to a FAQ detailing the error messages and possible next steps, and the email of the Registry Manager and/or Vocabulary Editor/Reviewer
  6. Queues the file for the Registry Manager and/or Vocabulary Editor/Reviewer
  7. The Registry Manager submits the final file to the Registry. Notification of this event is sent to the Maintainer and the Organization Contact
Result
The Vocabulary terms are registered. Updates to the Vocabulary terms can be made individually or by uploaded file.

Use Case 5: Maintainer Adds Information to Registered Term

An authenticated user who already has vocabulary terms registered comes back to the registry to maintain the terms. The user:

  1. Searches for the term he/she wishes to maintain
  2. The Registry associates the user with the vocabulary, and presents a menu of choices for maintenance
  3. The user chooses the appropriate task, and is presented with a form
  4. The user completes the form, which sends the update through validation and reports back to the user
  5. The user okays the transaction, and it goes to the Registry Manager's queue

Notes This use case doesn't address the issue of versioning at all (yet). Some potential versioning requirements:

  1. must be able to allow people/services to create dependencies on a 'versioned' snapshot of a particular SKOS/OWL representation of a vocabulary and it's relationships
  2. must be able to encode the version 'number' in the above snapshot
  3. individual values in a vocabulary may be created, updated, or deprecated, but not deleted
  4. URIs of individual values won't contain version information
  5. Namespaces of vocabulary schemas won't be versioned
  6. Vocabulary schema names will contain version information
  7. Schema name versioning will only change if the version change would break backward compatibility

Use Case 6: Maintainer Changes Semantics of Term

Use Case 7: Maintainer Changes Status of Term

Use Case 8: Registry Software Validates Inputs and Uploads

Use Case 9: Registry Manager Interacts with User and User Input

Use Case 10: External Service Interactions

Use Case 11: External User Interactions

Use Case 12: Visitor registers as a Maintainer associated with an organization

Purpose
A Visitor wishes to be registered as a Maintainer for an existing Organization
Primary Actor
Visitor
Prerequisites
None

Sequence

  1. Visitor accesses the Registry and initiates Maintainer Registration
  2. Registry asks Visitor to login or register
  3. If register selected...
    1. Registry displays user registration form and Visitor enters email address (will be their id and Registry will check for uniqueness in the background), selects a password, supplies real name and contact information: address, phone
    2. Visitor selects Organization from list and submits form.
    3. Registry sends confirmation email to Visitor
    4. Visitor replies to confirmation email and user info is stored in database.
  4. If login selected...
    1. Visitor enters login info and submits
    2. Registry displays list of Organizations
    3. Visitor selects one and submits
  5. Registry sends confirmation email to contact
  6. Visitor replies to confirmation email. Registry stores user info in database as confirmed
Result
Visitor is registered. Visitor is now a Maintainer associated with a registered organization.

Example Registries