If your system includes fields that users enter affiliation information into, you can standardize that input and capture corresponding ROR IDs by adding a typeahead (or "autosuggest") widget that prompts users to select an organization from ROR. Learn more about best practices and implementation steps here.
Use a ROR-powered typeahead to capture the "top level" organization (e.g., University of Wisconsin-Madison). Department, college, or other sub-unit should be captured in a separate text field, as in the examples below.
labels all include variations on an organization's name, any of which a user might and should be able to search for. The
?query parameter of the ROR API will search an index of all these fields, but if you build your own search logic, make sure you configure your typeahead to allow searching for the values in any and all name-related fields.
In the below example, the ROR record for the University of Wisconsin-Madison, https://ror.org/01y2jtd41, has the single value "University of Wisconsin-Madison" in the
name field, the value "UW-Madison" in the
aliases field, the value
UW in the
acronyms field, and the organization's name in French and Spanish in the
labels field. All values are searchable.
In addition to the primary organization name, display other ROR record fields in order to help users select the correct organization. We recommend including:
Name variations such as
aliases, and names in other languages (stored in the
labelsfield). This is particularly important because a user's query should be able to match a name variation rather than the primary name in a ROR record.
Geographic information such as city and country.
We do not recommend displaying ROR IDs to end users.
Identifying organizations without U.S. state information
ROR is a global registry, and most countries do not have an administrative region corresponding to the U.S. state. Note that our analysis shows that there appear to be no records with duplicate name, city, and country in the ROR registry, so users should be able to choose the correct organization based on name, city, and country alone, e.g., "York College, York, United States" (https://ror.org/022jz8688) and "York College, York, United Kingdom" (https://ror.org/04gaeyc40).
We strongly discourage requiring users to enter only organizations with ROR IDs, because there are many valid reasons why a user may be unable to select an organization with a ROR ID as their affiliation:
- The user may be affiliated with a research organization that is in scope for ROR but has not yet been added to the registry
- The user may be affiliated with a research organization that is not in scope for ROR, such as a single-person consultancy
- The user may be an independent researcher
Forms can still require users to give an institutional affiliation by allowing users to enter free text strings if no appropriate suggestion is made by the ROR typeahead.
After a user chooses an organization from the list, don't allow them to edit the name, as this will likely result in incorrectly matched ROR IDs. Instead, prompt them to choose a new organization from the ROR list or else enter an organization name as a free text string.
Allow the user to enter the organization name as a text string if no appropriate option is suggested by the typeahead.
Allow users to provide multiple affiliations, since many users are affiliated with multiple organizations. In addition, many users are affiliated with both a top-level organization such as the University of Wisconsin-Madison and a "child" research organization such as the Morgridge Institute for Research. Making the ROR-powered institutional affiliation field repeatable enables users to provide both affiliations.
See ROR hierarchies and relationships for more information about parent, child, and sibling research organizations in ROR.
Follow accessibility best practices for form controls, such W3C Web accessibility initiative (WAI), including:
Label and group form controls correctly
Include form instructions in a way that can be read by assistive technologies, such as screen readers
Ensure that keyboard/tab navigation is possible
Ensure that form controls function at a variety of screen sizes/zoom levels
Ensure that colors with sufficient contrast are used, and that color alone is not used to convey information
Consider Filtering the list of suggestions displayed to the user based on context, such as the user's email domain, organization type, or location (either browser geolocation or location information entered in other fields on the same form).
Consider populating other fields in your form automatically using data from the ROR record selected by the user. See the list of ROR record fields in ROR data structure.
A simple way to populate a typeahead widget is to query the ROR REST API in real time as the user types. While this approach has the advantage of being easy to implement, it comes with some disadvantages:
Slower/more variable response time vs querying data stored locally
Depends on being able to reach the ROR API
Performance may be impacted by other ROR API users
Steps to implement a typeahead widget using the ROR REST API will vary depending on your system architecture, but may include the following:
- Send user input to the ROR API.
- Parse results.
Results are returned as a list of ROR records, ordered by matching score. Note that the matching score itself is not returned. Results are paginated, and the first 20 results are returned by default. See example responses in the Query parameter section of the REST API guide.
- Display results.
Display the top results to the user. In addition to the name, include information from ROR like acronyms, aliases, names in other languages, city, country, URL and organization type to help the user choose the correct result. We do not recommend displaying ROR IDs to users.
- Store selected result.
Store the ROR ID for the selected result in your system along with any other required information. We recommend storing and displaying ROR IDs as full URLs in the form https://ror.org/01y2jtd41. Read more about the ROR identifier pattern.
Regardless of the source data, typeahead widgets perform faster when querying data stored locally vs making requests to external resources.
While performance is much better and both data and search results can be tuned to meet the needs of a particular system, this approach requires more initial development time, as well as ongoing maintenance.
Steps to implement a widget using the ROR data dump vary depending on your system architecture, but may include the following:
Download and parse the ROR data dump into a local database.
Create a search index.
Create an internal API endpoint with logic to query the search index.
Use your internal API endpoint to populate your typeahead widget, following the best practices above.
Update your database and search index when new ROR data dumps are released.
- Try our demonstration version of a ROR typeahead at https://ror-community.github.io/ror-typeahead-demos/
- Take a look at the code for our ROR typeahead demos at https://github.com/ror-community/ror-typeahead-demos
Updated 5 months ago