NSDL Registry Use Case Documentation (Vocabularies)

From Metadata-Registry
Revision as of 09:52, 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.
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 Actors
Visitor, Registered User
Prerequisites
None

Sequence

  1. Visitor accesses the Registry and registers himself/herself, providing a name, affiliation, valid email account
  2. System responds with instruction to look for email account validation message, which provides next steps and ability to change system-supplied password
  3. Registered User initiates Organization Registration
  4. Registered User enters basic information about the organization -- Name, address, phone, domain (if available), URL, description, organization contact information including name and email. System will check that the contact name and email are not the same as the Registered User, and will prompt for additional information if there is duplication
  5. Registered User submits form and Registry sends confirmation email to organizational contact(s). Confirmation email will include information on who to contact if registration is not desired or there are questions or issues around registration. Reply to the email is not required to continue.
  6. Registry asks if User wishes to register as a Maintainer for that organization
  7. If yes, see Use Case 12
  8. Registry assigns PURL to organization and stores organization info in database
  9. Registry notifies Registry Manager(s) that Organization has been added. Registry Manager contacts Organization if there are questions or concerns.
Result
Organization is registered. Registered User is now associated with the registered organization.

Use Case 2: Registered User Registers a Vocabulary

Purpose
A Registered User 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 Actors
Registered User, Maintainer or Organization Contact
Prerequisites
Organization must be registered. Registered User must be associated with that Organization and logged in

Sequence

  1. Registered User accesses the Vocabulary Maintenance page and selects 'Add new Vocabulary'
  2. Registry responds by asking if the Registered User wishes to be listed as a Maintainer of the Vocabulary or as an Organization Contact. If yes, the Registry displays the 'Add Vocabulary' form. If no, the Registry displays an 'Add Maintainer' form. [NOTE: Either role will allow registration of the vocabulary itself, but only Maintainers can register terms.]
  3. Maintainer or Organization Contact adds a description of the vocabulary, rights information (see note 1)
  4. Maintainer or Organization Contact defines a namespace URI for the vocabulary, based on the Organization's domain
  5. Maintainer or Organization Contact submits form
  6. Registry stores information in database and sends confirmation email to all defined as Organization Contacts(no response required)
  7. Registry notifies Registry Manager(s) that Vocabulary has been added
  8. Registry Maintainer the opportunity to Register other Maintainers
  9. Maintainer adds Maintainer registration information for other Maintainers
  10. Registry sends other Maintainers a confirmation email indicating that they have been added to this Vocabulary. Simple email confirmation is required before they can be listed as Maintainers.
  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 the Organization 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 to each term
  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 a Vocabulary to the Registry

In this case a user who has already registered the vocabulary as a whole may contribute individual terms via an upload process, subject to validation of the file. The user:

  1. Chooses the file to upload from his/her browser
  2. Receives a validation report from the registry, confirming that required elements are present (including a valid URI for the terms)
  3. Queues the file for the Registry Manager

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