Help Us Test v2 of the ROR API!

Throughout 2022 and into 2023, ROR gathered community feedback about how to handle schema and API versioning and about what should be included in a new version of ROR’s metadata schema. Today, we are thrilled to release a beta version of ROR’s first major schema and API update. Version 2 of the ROR API and metadata schema is open to the public for testing through October 16, 2023. As a community-driven initiative, ROR relies on input from its stakeholders to ensure that new and updated features serve the needs of its wide array of users and use cases.

We plan to incorporate changes from this beta test this fall and to make API v2 available in production in early 2024. The current version, version 1, will remain the default version until at least early 2025.

A full account of the changes and detailed instructions for participating in the beta test are available in our v2 beta test documentation, but we provide some highlights below.

What’s new in v2 of the ROR metadata schema

• Name information previously in name, acronyms, aliases, and labels fields is now contained in a single parent field names with subfields lang, value and types.

• Location information previously in addresses field is now in locations field with subfields geonames_id and geoneames_details. Many fields containing very granular information derived from Geonames have been removed, as this information is available directly from Geonames.

• Website/domain information previously in links and wikipedia_url have been combined into a single parent field links with subfields type and value. The ip_addresses field has been removed, and a new domains field has been added.

• External identifiers information has been restructured within the existing external_ids field. Each item in external_ids now has subfields type, all and preferred.

• Administrative information was not included previously. A new parent field admin has been added, which contains subfields created and last_modified. Each of those subfields contains additional subfields date and schema_version.

• Controlled lists previously had variations in casing. For example, values in the types and relationships.type fields began with an uppercase character, while values in status were lowercase and external ID types contained a variety of casings. In v2, allowed values in controlled lists are consistently lowercase, with the exception of country codes derived from ISO-8166, which are uppercase per the standard.

What’s new in v2 of the ROR API

Version 2 of the ROR REST API includes all the same search and retrieval functionality as the current version (v1) of the ROR REST API, but with ROR records in responses formatted according to the v2 schema. For all ROR API requests, the API version is specified in the path portion of the request, as in the following example:

curl https://api.dev.ror.org/v2/organizations

Sample v2 ROR data

A sample data dump containing both v1 and v2 files is available in the locations below:

• Zenodo sandbox: https://sandbox.zenodo.org/record/1241263
• GitHub: https://github.com/ror-community/ror-data-test/blob/main/v1.32-2023-09-14-ror-data.zip

These files are for review and testing purposes only and are not official ROR release files. Note too that there are several new fields/subfields in v2, and the dataset used in the beta has not been fully updated with values in all new fields/subfields. In particular:

• Created/last modified dates HAVE been added to all records in the new admin field, using actual dates from GRID and ROR data releases.
• Domains HAVE NOT been added. The new domains field is currently an empty list for all records.
• Language codes for items in the new names field are only included for names inherited from the labels field in the current schema. Language codes HAVE NOT been added for names inherited from the name and aliases fields in the current schema.

We plan to add data to empty fields in v2 over the coming months, carefully curating the records to ensure accuracy.

How can I provide feedback on the v2 beta?

1. Read the complete beta documentation and testing instructions.

2. Check the ROR schema & API v2 beta project board to see if the same or a closely related issue has already been reported. If so, please add comments to that issue.

3. If you have new feedback that’s not related to another issue on the ROR schema & API v2 beta project board, submit a GitHub issue using the ROR schema & API v2 beta feedback template.

All issues will be reviewed by ROR staff, and we may contact you using your GitHub handle to request additional information. If you are not a GitHub user or prefer to submit your feedback privately, please email support@ror.org . Please provide your feedback by October 16, 2023.

We are grateful for your help! Following the close of the beta test, we will review all reports and work to incorporate the improvements before we release v2 into production.

Thanks, as always, to everyone who works to make ROR the best it can be.