Create ROR-powered forms

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.

General best practices

Capture affiliation with ROR

Use a ROR-powered typeahead to capture creator affiliations (e.g., University of Wisconsin-Madison). Department, college, and other sub-units should be captured in a separate field, as in the examples below.

Allow users to search for variant names

The fields name, acronyms, aliases, and 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.

Show information beyond the primary organization name

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 acronyms, aliases, and names in other languages (stored in the labels field). 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.

• Organization type.

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 University, Toronto, Canada" (https://ror.org/05fq50484), "York University, York, United States" (https://ror.org/022jz8688) and "York College, York, United Kingdom" (https://ror.org/04gaeyc40).

Do not require the ROR ID

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.

Do not allow editing of the ROR organization name

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 entering a text string if no ROR match is found

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

Allow users to provide multiple affiliations, since many users are affiliated with multiple organizations. In addition, many users are affiliated with both a high-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

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

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 using ROR data

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.

Implementation approaches

ROR API

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:

1. Send user input to the ROR API.

As the user types their affiliation, send the input to the ROR API. We recommend using the query parameter search. You may also wish to first check the heartbeat of the ROR API.

2. 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.

3. 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.

4. 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.

ROR data dump

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:

1. Download and parse the ROR data dump into a local database.

2. Create a search index.

3. Create an internal API endpoint with logic to query the search index.

4. Use your internal API endpoint to populate your typeahead widget, following the best practices above.

5. Update your database and search index when new ROR data dumps are released.

Typeahead demos and code

• 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