...
| Required? | User Story |
|---|---|
| Catalogers | |
| NOTE: The following user stories are related to creating or editing resource descriptions typically within a metadata editor or similar application. | |
| 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, other attributes related to the entity that are not in the primary or variant label (e.g. occupation, resource type, etc.), that will help me locate and select an authoritative entity. | |
As a cataloger, I want search results to contain highly relevant terms for my keyword search based on standard indexing approaches. Actual relevancy is subjective. | |
| As a cataloger, I want transparency in the approach for indexing to be clear. (e.g. exact match on primary label, stemming, which fields are searched, etc.) May vary between authorities. | |
| As a cataloger, I want search results listed in rank order as determined by standard indexing approaches. | |
| As a cataloger, I want to choose how search results are returned (e.g. left anchored, keyword indexing rank, or as yet unknown approach) | |
| 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. (e.g. keyword was in the variant label, occupation, or descriptions instead of the primary label) | |
| As a cataloger, I want to see contextual information (e.g. variant labels, occupation, birth date, etc.) about the search results that distinguishes it from other, similar-looking results, to help me to select the correct authoritative entity and to recognize false positives. The context may be drawn from authoritative entities and real world object entities based on what is available in the authoritative data. | |
| As a cataloger, I want to be able to filter search results to a specific date range for a field on the authoritative entity (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 name, person name, meeting name, etc.; manifestation, item, expression, etc.). | |
| As a cataloger, I want to be able to filter on specific fields in the search results (e.g. occupation, resource format, agent, etc.) This is a filter of results after they are returned similar to a facet. | |
| As a cataloger, I want to be able to specify in the search limiting results to a keyword in a particular field (e.g. an advanced search that passes in 'occupation includes humorist'). | |
| As a cataloger, I want search results to be returned quickly, so that I can catalog efficiently, generally seen as sub-second results or some indicator that a longer search is being processed. | |
As a cataloger, I want to be able to request additional search results if what I am looking for isn't visible in the current set of results displayed, e.g. I didn't get it in the first 10, so give me 10 more results (aka pagination). | |
| As a cataloger, I want to determine whether the entity I'm searching for doesn't exist in the authoritative source that I'm searching. Perhaps stating No Result Found indicating the search completed and there were no results, or No Exact Match Found when this was an exact match? Christine Fernsebner Eslao Can you confirm this is an adequate description? It may not be possible to definitively state that the entity doesn't exist. May need to redirect to the source authority to do a search there to confirm whether or not the desired entity exists.As a cataloger, if a request fails, it should fail in a reasonable amount of time and reply gracefully providing a reason for the failure (e.g. Time Out, No Result Found, No Exact Match, etc.) | |
As a cataloger, I want information displayed in the editor UI to match the information in the authoritative source. This primarily impacts editing and displaying of entities where the data in the authoritative data has changed (e.g. split, merged, renamed, deleted) to be sure that cataloged data remains accurate over time. | |
| As a cataloger, I do not want authoritative data to be automatically updated when the data is changed in the authoritative source. I want to control if and when that information is updated. | |
| Application Developers (UI and Backend) | |
| As a UI developer, I want to provide a selection widget that enables a cataloger to type in keywords and see a list of entities sorted in rank order. | |
| As a UI developer, I want to provide a selection widget that enables a cataloger to type in a left-anchored string and see a list of entities that start with the typed string sorted alphabetically. This could be implemented as an autocomplete. | |
As a UI developer, I want to provide a widget that shows search results that the end user can understand by displaying a representative label. This is typically the preferred label of the resources in the search results, but not necessarily, notably in the case of identify management systems (e.g. ISNI, VIAF, etc.) DISCUSSION: If, for example in ISNI, the representative label is the ISNI number, you would need additional context to be able to distinguish between entities. As a UI developer, I want to show the user something and the user wants this to be understandable. I don't want to have to create this differently for each authority. In general, the response from the service should have not just the representative label, but also additional information. Ex. if the user does a search and the search hits a variant, from the UI perspective, you want to help the user why they are seeing the results and how it came from the variant. | |
| As a UI developer, I do not want to decide what label to display as the representative label whether the results come from a vocabulary with a clear preferred label or an identity management system. | |
As a UI developer, I want to show users additional information (aka extended context) to help them make an accurate selection. DISCUSSION: Not sure that authority provider can give rank order results, that it may be more appropriate for the application to allow the user to decide based on the extended context. As a developer, I don't want to have to understand the extended context, I just want to display it to the end user. I don't want to have to treat each service uniquely. One way of handling differences between authority ontologies is to provide configurations identifying ldpath to each piece of extended context in the result graph. | |
| As a UI developer, I want the selection widget to allow the user to ask for more results (i.e., page through results). | |
As a UI developer, I want to provide the end user with a search interface based on the authority's ontology and allow the user to select which field they want to search. (aka advanced search) DISCUSSION: This implies some understanding of the unique aspects of each authority. Perhaps a better approach would be to define what fields you want to search and connecting the fields of the ontology to the search fields. This doesn't take advantage of the linked data aspect where the data could be more variable. Are we asking for consensus at the data model level? Maybe we can abstract out some by mapping at the service level some common fields to the ontology of the authority. ISNI approached this by using general ontologies (e.g. schema, skos) that allow for an easier way to come to common understanding of fields across multiple authorities. | |
As a backend developer, I want a consistent way to specify parameters that is the same for all authorities (i.e. standardized API request). Want to avoid one off code requiring if-then-else processing. As a backend developer, I want data returned in a consistent way across all authorities. Minimally the data structure of extended context (e.g. lists, nested lists). Are there non-textual data like images or DISCUSSION: Having fields be structured the same is what is important. We want to be able to display the results without needing to interpret them. One exception would be to handle by datatype (e.g. image). As a backend developer, I want data to be returned in the same format from all authorities (e.g. normalized json, json-ld, or something else). There is a request for normalized json preferred over json-ld. DISCUSSION: The last thing the developer wants is json-ld. It is very difficult to work with. Not always consistent json. Querying RDF data is complicated. A normal json structure is easily processed by most developers without special knowledge. Inconsistent or bad libraries for dealing with json-ld. Json-ld is not always constructed consistently making it difficult to process as simple json. | |
As a backend developer, I want to identify the search depth to follow in the broader graph in the authority (e.g. follow links up to 3 levels deep). This has implications for performance if the levels are too deep. The goal of this user story is to have authorities provide enough data to help the end-user make an accurate selection. Ex. ldpath: (madsrdf:hasAffiliation/madsrdf:organization/skos:prefLabel) | (madsrdf:hasAffiliation/madsrdf:organization/rdfs:label) | (madsrdf:hasAffiliation/madsrdf:organization/madsrdf:authoritativeLabel) :: xsd:string | |
| As a developer, I want to receive a permanent URI for each entity to uniquely identify the entity. | |
| As a backend developer, I want to have documentation of authority search API describing parameters and the structure of the data that will be returned. (e.g. See example documentation at Agrovoc and OCLC.) | |
| As a backend developer, I want to be able to support left anchored search and keyword search. | |
| As a UI developer, I want to know whether an authority supports left anchored search and/or keyword search so I can provide a UI widget to support switching between these approaches. | |
As a backend developer, I want to receive results marked with a ranked order. There are various approaches to do this in RDF (e.g. RDF sequence, identified by predicate, etc.) This is typically driven by keyword search and produced by the provider's indexing approach. | |
| As a normalization backend developer, I want data to be returned as linked data allowing for configurations that map ontologies to a normalized json format. | |
| As an application backend developer, I want to receive data in a consistent format that allows for a single approach to interpret results. (e.g. needs of an Application like Sinopia) | |
| As a normalization backend developer, I want to receive search results as resources in a linked data graph. | |
| As a backend developer, I want to receive search results as a simple list of URIs. From those I would be able to fetch individual resources for more information. (May have performance issues when fetching many individual resources.) | |
| As a backend developer, I want to be able to request the level of detail (e.g. extended context vs. simple response) and format (e.g. linked data graph, simple JSON structure). This could be fulfilled as a single API with parameters or as separate APIS. | |
As a UI developer, I want to provide additional information in the selection widget about entities to improve the accuracy of selection. | |
| As a backend developer, I want to receive additional information about an entity in the same predictable format for all authorities (e.g. json) | |
| As a backend developer, I want to receive what facets are available to support browse by facet and advanced search. | |
As a backend developer, I want to pass filtering requests to the provider's API and receive search results with the filter applied. (e.g. date range, class type, language, arbitrary field) | |
| As a backend developer, I want to receive facet values that can be filtered by (e.g. language is the facet, values are English, German, Spanish, etc., and counts for each value) . The facet information should include values for the entire result set and not just the current page's result. | |
As a backend developer, I want to receive pagination information with search results (e.g. first result position, last result position, current retrieved results count, total count in full result set), such that, I can request the next page of results. | |
| As a backend developer, I want to receive pagination information following a standard (e.g. JSON-API Pagination) | |
| As a backend developer, I want to be able to fulfill all search requests. (i.e. source authorities respond to all requests with excellent uptime) | |
| As a backend developer, I want to quickly show search results to users (e.g. sub-second, specific threshold TBD) | |
| As a backend developer, I want to update cached labels and URIs as changes are made to the authoritative source data. Want to receive change management feed of changed resources (e.g. added, renamed, moved, split, deleted, etc.) | |
| Providers | |
| STOPPED HERE | 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. | |
| As a provider, I want to provide data for download facilitating local caching. | |
| As a provider, I want to keep download files up to date. Need to define and publish expectations of reasonably up to date: quarterly, monthly, weekly, or daily | |
| As a provider, I want to be able to provide partial downloads with only modifications since last download update. | |
| As a provider, I want to provide notifications of changes to data (e.g. new, deleted, deprecated, moved, split, and merged entities) | |
As a provider, I want to provide a representative label for each entity returned in search results. DISCUSSION: I want one field in the authoritative entity to be a human readable, meaningful representation of the entity that can be displayed to users to identify the entity for selection. The challenge here may be the difference between an authoritative source and an identity management system. For example, ISNI does not provide a display label. The question is who is responsible for creating a meaningful label. Do we need "a" label or "the" label? Example, VIAF has multiple labels in varying scripts. Do you request label in a particular script? Example, label for a work that identifies that work may need to include contributors in addition to the title. One way to address the need for additional data to be able to make a decision is to include additional context along with the identified human readable label that are displayed in separate fields as opposed to a single joined data field. The label likely won't be unique. Are we making a distinction between authority management system where there is an authorized access point that has a preferred unique label and other approach where data may not be standardized? | |
...