1. Introduction
This section is non-normative.
The Requirements for Collection Management Systems include a general obligation for vendors to implement the Network of Terms API in their collection management systems. However, feedback from users of these systems, as well as questions from vendors, has shown the need for more detailed guidance. The requirements below provide such guidance, specifying in more detail the steps needed for performant and user-friendly implementations of the Network of Terms. The goal is to help both users and vendors.
2. Definitions
- Collection manager
-
A person who creates heritage object metadata in a collection management system and links terms to those objects.
- Configurator
-
A special type of collection manager who configures the collection management system for searching the Network of Terms, without requiring vendor modifications.
- Collection management system
-
A software application for creating, editing, and publishing heritage object metadata that implements the Network of Terms API.
- Terminology source
-
A source of terms, such as a thesaurus or vocabulary, that is available through the Network of Terms.
- Vendor
-
The organization that supplies the collection management system.
3. Requirements
These requirements are organized into four phases: selecting sources, searching terms, viewing terms, and publishing links.
3.1. Terminology sources
3.1.1. Search in selected sources
Collection manager searches MUST be executed only in selected terminology sources and MUST NOT default to searching all sources.
NDE has observed implementations querying all sources (by default). This makes the user wait needlessly for slow terminology sources and puts unnecessary load on terminology sources.
3.1.2. Select sources
Configurators MUST be able to select which terminology sources are available for searching without requiring vendor involvement.
Allowing customers to make their own selection, and being able to adapt it later as need arises, improves the adoption speed of the Network of Terms.
3.1.3. New sources immediately available
When new terminology sources are added to the Network of Terms, they MUST become available to configurators for selection.
Being dependent on vendors to add terminology sources slows down lead times.
3.1.4. Identify sources by URI
To identify terminology sources. their URI MUST be used; distribution information MUST NOT be hardcoded.
Distribution information may change over time (e.g. the terminology source’s SPARQL endpoint), but the dataset’s URI will remain the same.
3.2. Search terms
3.2.1. Debounce queries
Collection management systems MUST debounce collection manager search queries, waiting for strings of 3 or more characters before querying the Network of Terms.
Reduces load on terminology sources; many terminology sources don’t handle short search strings well.
3.2.2. Display complete term information
All information from the Network of Terms MUST be displayed without truncation in search results. This includes prefLabel, altLabel, scopeNote, and broader/narrower terms.
Collection managers need to see all relevant information about terms to differentiate terms and make informed decisions about which terms to link.
3.2.3. Display source information
For each term, its source MUST be shown, including name, alternateName (short name) and creator name and alternateName (short name).
Helps collection managers select a term from a source appropriate to the resource and the property they are editing, for example ‘material’.
3.2.4. Display error messages
Errors from the Network of Terms MUST be shown to collection managers.
This communicates to users that they are searching live in external sources that may be periodically unavailable, through no fault of the Network of Terms.
3.2.5. Send multilingual queries
Collection management systems MUST send multilingual queries to the Network of Terms.
Users have observed labels in multiple languages being combined in a single search result, which is confusing and hard to read.
3.2.6. Identify client in requests
Collection management systems MUST send a User-Agent HTTP header identifying the system and version to the Network of Terms.
Helps NDE to monitor usage and advise vendors in optimizing their implementations.
3.2.7. Distinguish previously linked terms
Collection management systems MAY distinguish previously linked terms in search results through highlighting or prioritization.
Improves term usage consistency within the dataset and interlinking between datasets, which becomes easier if fewer different terms are used.
3.3. View terms
3.3.1. Store term URIs
The URI for each linked term MUST be stored in the collection management system.
To maintain stable references to terms, implementations must store the term’s identifier. This also enables looking up the term later, to refresh its information in the collection management system.
3.3.2. Display term information
When viewing heritage objects in the collection management system, all linked term information MUST be displayed, including term information and source information.
This provides context to collection managers when they are viewing objects.
3.3.3. Cache term information
Term information MAY be cached but MUST then be periodically refreshed from the Network of Terms.
Caching reduces load on terminology sources. However, users must be presented with recent term information.
3.4. Publish links to terms
3.4.1. Publish term URIs
Linked term URIs MUST be included in published datasets. prefLabels MAY be included.
Consumers of the dataset should have access to linked terms. This requirement is in accordance with Schema.org Application Profile for NDE § implementation-of-the-nde-network-of-terms.