This page documents the new choice management and authority control of Item ("DC") metadata values features in DSpace 1.6. These are actually two separate features: the choice management mechanism is completely independent of authority control and can be configured and deployed independently of it.

...

1. Not a replacement for text metadata value.Metadata fields still have text values.
   • The text value of a metadata field does not have to be derived from the authority, even if authority control is required for that field.
2. Configured by field. The authority control status of each field is independently configured, but it affects all values of that field.
3. Authority control can be optional or required. When optional, metadata values may take on values that did not come from the authority.

4. Authority values are ubiquitous. Authority values are accessible by crosswalk

   Footnote
   Crosswalk in DSpace context is a functionality that allows DSpace metadata format to be translated to external formats.

   plugins, in the UI, through OAI-PMH, etc.

   • All of those context can detect whether a value is authority-controlled or not by testing for presence of an authority key.
5. Text-based searching and indexing is unchanged. Since metadata values still have text values, the browse and search systems will work unchanged.
6. Choice behavior decoupled. The selection and choice mechanisms can be invoked independently (e.g. in the submit UI) of authority control.

...

We will consider adding an administrative UI to detect and list these metadata problems.

Display and CrosswalkCrosswalk  

Every metadata value potentially includes values for an authority key, and an authority confidence. They are only present when the field is under authority control, and when there is an actual authority value, otherwise they are absent (e.g. in the DIM XML representation) or null.

The presentation UI can call on a generic method to get the canonical display string for an authority key, but it is welcome to interpret it in custom code to present a more detailed view. For example, one site may want to customize their Item display so a personal name appears with a link to their page on the institution's social networking site, which it obtains through the authority key.

Dissemination crosswalks will crosswalks will also receive the authority key so they can pass that knowledge on through OAI-PMH, exported packages, and any other dissemination vehicles.

...

The basic implementation only adds two columns to the MetadataValue table:

Oracle:

ALTER TABLE MetadataValue
   ADD ( authority VARCHAR(100),
         confidence INTEGER DEFAULT -1);

Postgres:

ALTER TABLE MetadataValue
   ADD COLUMN authority VARCHAR(100),
   ADD COLUMN confidence INTEGER DEFAULT -1;

...

There are symbolic constants (and corresponding String symblic names) for the confidence levels defined in the Choices class:

...

...

...

...

...

...

...

...

The icon rendering in the XMLUI Mirage 2 theme takes place in choice-authority-control.xsl.

Separation of Choices from Authority Control

...

To search on this index, you would submit an OpenSearch query such as this to retrieve Items with an author whose authority key matches no2004117088:

http://dspace.myuni.edu/open-search/?query=author_authority:no2004117088

...

How do you get the authority key value on which to search? If it comes from an external source (e.g. the Library of Congress Naming Authority), and you happen to know the details of how it is derived, you can derive it directly from the source. Otherwise, you can use the Browse UI on an authority-controlled browse index to display a list of authority keys in the first-order browse list. Each value is a link whose URL is of the form:

http://dspace.myuni.edu/browse?type=*BROWSE_INDEX_NAME*&authority=*AUTHORITY_KEY*

e.g.

http://dspace.myuni.edu/browse?type=author&authority=no2004117088

...

Since choice management and authority control affect the operation of the interactive submission pages, there is naturally some interdependence with that configuration as well. This table shows how the data type chosen for a metadata field affects choice and authority management:

Other Restrictions

Plugins and "Select" Presentation Style

...

First, configure all your ChoiceAuthority plugins in the usual PluginManager style. The example plugins provided in the DSpace code are configured here:

plugin.named.org.dspace.content.authority.ChoiceAuthority = \
  org.dspace.content.authority.SampleAuthority = Sample, \
  org.dspace.content.authority.LCNameAuthority = LCNameAuthority, \
  org.dspace.content.authority.SHERPARoMEOPublisher = SRPublisher, \
  org.dspace.content.authority.SHERPARoMEOJournalTitle = SRJournalTitle, \
  org.dspace.content.authority.SolrAuthority = SolrAuthorAuthority

Automatic Choice Authority from Configurable Submission value-pairs

The default configuration also includes a special self-named plugin that picks up all the value-pairs elements defined in your input-forms.xml configuration and makes them available as choice authorities (especially suitable for the select presentation style:

plugin.selfnamed.org.dspace.content.authority.ChoiceAuthority = \
  org.dspace.content.authority.DCInputAuthority

Some of the ChoiceAuthority instances available in the default configuration are:

• LCNameAuthority - Sample Library of Congress (USA) name authority - NOT for serious use.
• SRPublisher - Journal Publisher names based on SHERPA/RoMEO database
• SRJournalTitle - Journal Titles based on SHERPA/RoMEO database

...

First, any authority-controlled field must also be configured with a source of choices. This is also defines a simple choice field:

choices.plugin._schema.element.qualifier_ = _plugin-name_

e.g.

choices.plugin.dc.relation.journal = SRJournalTitle

...

This determines the UI presentation of the choice (mainly in the interactive submission UI).

choices.presentation._schema.element.qualifier_ = select | suggest | lookup

e.g.

choices.presentation.dc.relation.journal = suggest

...

Finally, the choices for a metadata field may be specified as open (i.e. values not included in the choices are allowed) or closed (restricted to the set of values offered. The default is open. This means that when a proposed value is not already in the choices, it is added as an allowable choice.

choices.closed._schema.element.qualifier_ = true | false

e.g.

choices.closed.dc.relation.journal = false

...

To declare a field as authority-controlled, just add a property like this, in addition to its Choices plugin declaration:

authority.controlled._schema.element.qualifier_ = true

e.g.

authority.controlled.dc.relation.journal = true

...

To further constrain an authority-controlled field so that it must have an authority key whenever setting a metadata value, add the property:

authority.required._schema.element.qualifier_ = true

...

• accepted
• uncertain
• ambiguous
• notfound
• failed
• rejected
• novalue
• unset

For example:

authority.minconfidence.dc.contributor.author = accepted

...

. The built-in default is ACCEPTED, but if you find this is too high, you may prefer AMBIGUOUS to give automatically-derived authority keys the benefit of the doubt, e.g.

authority.minconfidence = ambiguous

Example of some field configurations

# Simple configuration of authory-controlled author, authority not required
 choices.plugin.dc.contributor.author = LCNameAuthority
 choices.presentation.dc.contributor.author = lookup
 authority.controlled.dc.contributor.author = true
 #
 # As an example, get journal title for dc.title.alternative
 choices.plugin.dc.title.alternative = SRJournalTitle
 choices.presentation.dc.title.alternative = suggest
 #
 # This employs a select to restrict choices for dc.type field on EditItemMetadata page:
 choices.plugin.dc.type = common_types
 choices.closed.dc.type = true
 choices.presentation.dc.type = select

...

You can control the images shown for various authority confidence levels with style tags such as img.ds-authority-confidence.cf-NAME, where NAME is the symbolic name of the confidence level, such as accepted (see above for the list). For example, this displays a thumbs-up icon to mark a human-approved level of confidence in the authority value:

img.ds-authority-confidence.cf-accepted
  \{ background: transparent url(../images/confidence/6-thumb2.gif); \}

...

You can turn on the display of authority-value fields, ideally just for debugging since it clutters the display. Adjust the value of the display style to inline to see authority value fields on Submission UI forms. (Note that the Edit Item Metadata page already displays authority values.)

input.ds-authority-value \{ display: none; \}

...

The prototype CSS also includes some styles for the Scriptaculous JavaScript autocomplete feature as well. These lines should be copied (and customize as necessary) into your theme's CSS:

div.autocomplete
 div.autocomplete ul
 div.autocomplete ul li.selected
 div.autocomplete ul li
 div.autocomplete ul li span.value

...

For customization, examine the contents of these pages in the webapp:

/tools/lookup.jsp
 /tools/edit-item-form.jsp
 /submit/edit-metadata.jsp

...

The collection is supplied as a database ID in order to save the overhead and database access which would be required to create a DSpaceObject instance – on the assumption that it is not always going to be used, and in fact probably pretty rarely, and that the speed of a choice request is very important in the interactive context, the expense of querying the collection is deferred so it is only incurred by those implementations which really need it.

public Choices getMatches(String text, int collection, int start, int limit, String locale);

...

Note that getBestMatch() is given a collection argument, just like the collection context given to getMatches() – see above for details.

public Choices getBestMatch(String text, int collection, String locale);

...

Get the canonical, human-readable label (i.e. short descriptive text) corresponding to the authority key of a value. This is only called for fields defined as authority-controlled; a choice plugin that is never used for authority-controlled fields does not need to implement this.

public String getLabel(String key, String locale);

...

Add methods that take authority-key and confidence arguments:

public void addMetadata(String schema, String element, String qualifier, String lang, String value, String authority, int confidence)
 public void addMetadata(String schema, String element, String qualifier, String lang, String[) values, String authorities(), int confidences(])

...

The old addMetadata methods are still available, of course, although they have a new failure mode. Whent the field is authority-controlled they will call the field's configured ChoiceAuthority's getBestMatch() method to generate an authority key and confidence value. If the field is configured to require an authority key, an exception is thrown if getBestMatch() does't return one.

Changes to

...

Metadatum

Add fields:

public String authority;
 public int confidence;

Changes to MetaDataValue

public String getAuthority()
 public void setAuthority(String value)
 public int getConfidence()
 public void setConfidence(int value)

...

The DIM Field element gains two new attributes to represent the authority and confidence (when available) of DC metadata values, e.g.

<dim:field schema="dc" element="contributor" qualifier="author" *authority="n79-21164" confidence="6"*>
 Mark Twain
 </dim:field>

...

Any Theme for a DSpace using the Choice or Authority Control features must include the CSS declarations prototyped in the Reference theme. The corresponding images must also be available in your theme. All of the other elements (JavaScript, translations, etc) are implemented below the theme layer.

Installing the Prototype

Here is how to install the prototype on your system:

1. Checkout from the the special "sandbox" on svn:
   • svn co http://scm.dspace.org/svn/repo/sandbox/authority-control-1_6-prototype
2. Modify your dspace.cfg properties to enable choice and/or authority control on some fields. Unless you configure choice control, nothing will be any different. (See "Configuration" section above for details)
3. Configure and build as usual:
   • Be sure to choose the Reference theme, otherwise you'll have to copy over the choice/authority additions to your chosen theme (see above).
4. After the fresh install, convert the database schema to 1.6 by running the SQL statements in the file: Oracle: /dspace/etc/oracle/database_schema_15_16.sql or Postgres: /dspace/etc/database_schema_15_16.sql
5. Start the webserver as usual.

Work To Be Done

This prototype needs a little additional work before it can be ready for merging into 1.6 source. I'm hoping there will be developers interested in volunteering since these tasks are not relevant to my site and I have no extra time for them:

1. <s>Test and support on the PostgreSQL database.</s> done.
   • This should be a simple matter of porting the SQL statements and testing it, easy if you already have that database running.
2. <s>Port UI changes to JSPUI. More challenging.</s> done, thanks to Andrea Bollini
   • I'm willing to advise a bit, but have no time nor much non-rusty expertise in JSPUI.

Comments?

Please use the Discussion page.