Overview
This refines the use cases with a focus on user stories for each use case.
See also: Initial Use Case Definitions - Search API Best Practices for Authoritative Data Working Group
Required will be marked as...
- MUST HAVE - This feature must be in place for the system to work as required.
- IMPORTANT - The feature will be heavily used and the lack of this feature reduces the usefulness of the system.
- WOULD LIKE - This feature is desired and will make the system more usable and useful.
- OPTIONAL - This feature is optional. The system can continue to work well without it. May want to be able to turn it off.
Use Case: User wants to find the URI of an external entity from within a metadata editor
Required? | User Story |
---|---|
Catalogers | |
MUST HAVE | As a cataloger, I want to edit an entity (e.g. work, instance, etc.) and add a link to an external URI from an external authoritative sources (e.g. LCNAF, OCLC FAST, etc.). |
MUST HAVE | As a cataloger, I want to edit an entity (e.g. work, instance, etc.) and display a label from an external authoritative sources (e.g. LCNAF, OCLC FAST, etc.). |
MUST HAVE | As a cataloger, I want to be able to enter the exact external authoritative label and get the URI from the external authority linked to the entity being edited. This applies when there is a unique authoritative term. |
MUST HAVE | As a cataloger, I want to start typing a known external authoritative label and get the URI from the external authority linked to the entity being edited. This is left anchored type-ahead. |
MUST HAVE | As a cataloger, I want to start typing a known variant external authoritative label and get the URI of the authoritative label linked to the entity being edited. |
MUST HAVE | As a cataloger, I want additional information in the search that indicates that the term listed has a variant that matches the keyword typed. |
MUST HAVE | As a cataloger, I want to type in the alternate identifier (e.g. Q label in wikidata, ISNI label, organization code etc.) and get the URI for those entities. |
OPTIONAL | As a cataloger, I want to be able to search for a broader term in a hierarchy and get a list of narrower terms from which to select. NOTE: Some systems have seen performance issues in actual implementations. Catalogers generally know what they are looking for. |
OPTIONAL | As a cataloger, I want to be able to see broader and narrower terms when the authority is hierarchical. |
OPTIONAL | As a cataloger, I want to be able to step into broader or narrower terms when the authority is hierarchical. |
As a cataloger, when I am unable to find what I'm looking for in an authority lookup, I want to be able to search an authority source in an external site by clicking on a link to its native search UI. | |
As a cataloger, I know some keywords that will help me locate and select an authoritative term to add as metadata about an entity. | |
As a cataloger, I want search results to contain highly relevant terms for my keyword search. | |
As a cataloger, I want to see, for each entity that appears in results of my keyword search, which of the fields that were searched triggered its inclusion in those results. | |
As a cataloger, I want to see contextual information about an authoritative term that distinguishes it from other, similar-looking terms, to help me to select the correct authoritative term and to recognize false positives. | |
As a cataloger, I want to be able to filter search results to a specific date range for a field on the authoritative term (e.g. birth date, death date, floruit, etc.). | |
As a cataloger, I want to be able to filter search results to a specific class type (e.g. a corporate body). | |
As a cataloger, I want to be able to filter search results to a specific language. (Christine asks: does this mean "As a cataloger, I want to see labels and other strings tagged with my preferred language when viewing search results"? And/or "As a cataloger, I want to prioritize search results based on strings tagged with my preferred language"? Or something else?) | |
As a cataloger, I want search results to be returned quickly, so that I can catalog efficiently. | |
As a cataloger, I want to be able to request additional search results if what I am looking for isn't in the current set of results displayed. | |
As a cataloger, I want to determine whether the entity I'm searching for doesn't exist in the resource that I'm searching. | |
Developers | |
As a developer, I want one field in the authoritative term to be a human readable, meaningful representation of the term that can be displayed to users to identify the term for selection. | |
As a developer, I want to receive a permanent URI for each term to uniquely identify the term. | |
As a developer, I want to provide a widget that enables a cataloger to select a term from an authoritative source using left anchored autocomplete. | |
As a developer, I want to provide a widget that enables a cataloger to type in keywords and see a list of terms sorted in rank order. | |
As a developer, I want to provide additional information about terms to facilitate the accuracy of selection. | |
As a developer, I want to quickly show search results to users (e.g. sub-second, specific threshold TBD) | |
As a developer, I want to receive pagination information with search results, such that, I can request the next page of results. | |
As a developer, I want data to be returned as linked data allowing for configurations that map ontologies to a normalized json format. | |
As a developer, I want data to be returned in the same format from all authorities (e.g. normalized json, json-ld, or something else) | |
As a developer, I want to be able to fulfill all search requests. (e.g. source authorities respond to all requests with excellent uptime) | |
As a developer, I want to update cached labels and URIs as changes are made to the authoritative source data. | |
Providers | |
As a provider, I want my data to be used. | |
As a provider, I want my data to be used accurately. | |
As a provider, I want to support the creation of application widgets that provide access to our data. | |
As a provider, I want our API(s) to be performant (e.g. sub-second queries, specific threshold TBD) | |
As a provider, I want access to our data to be available 24-7 with occasional outages for maintenance that will be announced in advance. |
Cache of entire or significant portion of dataset with updates via retrieve a known concept using a consistent format across datasets
Update cached data
Required? | User Story |
---|---|
Catalogers | |
As a cataloger, I want to be able to search across multiple authorities. | |
As a cataloger, I want the display of data in the editing app to follow a consistent and predictable format. | |
Developers | |
As an application developer, I want a reliable source of data, such that, I am able to fulfill all search requests. | |
As a cache developer, I want to store all or significant portion of authoritative data locally. | |
As a developer, I want to control how data is searched. | |
As a developer, I want to control what data is returned to and displayed in the end user application (e.g. extended context). | |
As a developer, I want to control the format of data the editing application receives for the selection widget. | |
As a cache developer, I want to update cached data as changes are made to the authoritative source data. | |
Producers | |
As a producer, I want to make my data available for download. | |
As a producer, I want consumers of my data to use the most up to date version of the data. | |
As a producer, I want to provide a change management API that provides information on changes to terms in the dataset (e.g. new, deleted, changed, deprecated, moved, split, merged, etc.). |
Common External Search Format/Ontology
Required? | User Story |
---|---|
Catalogers | |
As a cataloger, I want to know that data drawn from multiple authorities have the same meaning. | |
Developers | |
As a developer, I want to use the same code to process data coming from multiple authorities. | |
As a developer, I want to support searching across multiple authorities. | |
Producers | |
As a producer, I want data alignment between authorities. | |
As a producer, I want to have an internal representation of my data that may be different from other authority providers. | |
As a producer, I want to provide a mapping of my data to a community supported search ontology. |
Auto-fill Batch processing
Required? | User Story |
---|---|
Catalogers | |
As a cataloger, I want auto-reconciliation processes to run that identify 'same-as' type relationships from other authorities. | |
Developers | |
As a developer, I want to run auto-batch processes once data has been entered. | |
Producers | |
As a producer, I want to support auto-reconciliation. |
Manual Batch processing
Required? | User Story |
---|---|
Catalogers | |
As a cataloger, I want to load data in a reconciliation program (e.g. open refine) and apply changes across multiple entities (e.g. works, instances, etc.) | |
As a cataloger, I want to be able to filter potential choices by date range. | |
Developers | |
Producers | |
As a producer, I want to support an API that allows my data to work with popular reconciliation programs (e.g. open refine) |