Timeline for the Sunset of Version 1 of the ROR API and Schema

One of the highlights of 2024 for the ROR team and the ROR community was the release of version 2 of the ROR API and schema in April 2024. Before that milestone, we spent many months working together to develop an API and schema versioning policy: that policy states that “Plans to sunset a previous version will be announced at least 1 year prior to the planned sunset date.” We’ve been reminding the ROR community ever since the launch of v2 of the ROR API and schema that version 2 is the recommended, stable version and that v1 of the ROR API would be deprecated in 2025. Today, we’re sharing further details and more precise dates for the deprecation of version 1 of ROR so that ROR users have all the lead time they need to make any necessary changes.

Timeline for ROR v1 sunset

Here’s our basic timeline for deprecating version 1 of ROR.

What you can expect in July

Starting the week of Monday, July 28, 2025, ROR API requests with no version in the path will default to v2 instead of v1. What does that mean, exactly?

• If you use ROR API requests with v2 in the path, you do not need to make any changes.
• If you use ROR API requests with v1 in the path, you do not need to make any changes before July 28, but you should plan to make changes before December.
• If you use ROR API requests with no version in the path, you will need to change your API requests to include v1 in the path if you wish to continue retrieving v1 data. If instead you wish to start retrieving v2 data, you should make sure you understand the differences between ROR schema version 1.0 and ROR schema version 2.1 and update your script or application accordingly before you begin including v2 in the path of your ROR API requests.

Examples of ROR API requests

Here are three examples of the same request to the ROR API for a list of organizations whose type is “funder”: one that specifies version 2, one that specifies version 1, and one that does not specify a version.

ROR API request with v2 in the path

https://api.ror.org/v2/organizations?filter=types:funder

ROR API request with v1 in the path

https://api.ror.org/v1/organizations?filter=types:funder

ROR API request with no version in the path

https://api.ror.org/organizations?filter=types:funder

All three of these requests return the same number and set of records, but you’ll notice that the request without a version in the path currently returns records that use ROR schema version 1.0. As of the end of July, that will change, and an API request that does not specify a version in the path will return records that use ROR schema version 2.1.

Because ROR schema version 1.0 and ROR schema version 2.1 are significantly different, we recommend carefully evaluating the information you retrieve from version 1 of the ROR API before changing your API requests to version 2.

What you can expect in December

In early or mid-December 2025, we will sunset v1 of the ROR API and schema permanently. This means that ROR API requests with v1 in the path will cease to return responses, and we will no longer provide v1 files in the ROR data dump on Zenodo at https://doi.org/10.5281/zenodo.6347574. In addition, ROR documentation pertaining to v1 of the ROR schema and API will no longer be available.

Important additional points to note

Version 2 of the ROR API and schema was deliberately designed for both flexibility and stability, so we don’t anticipate any further breaking changes for quite some time. We’re always collecting feedback about future enhancements on our roadmap, so if there’s something you’d like to see ROR do, please let us know.

Lastly, and perhaps most importantly, we’re here to help! If you’ve got questions about how to update your script or application from v1 of ROR to v2 of ROR, please join the ROR Technical Forum and post your question there or email [email protected]. The ROR Technical Forum is also a great place for developers who’ve successfully switched from v1 to v2 to share lessons learned with others, and we’d love to hear from you there.

After the sunset of the original version of ROR comes a night of restful sleep, and then a new day! See you bright and early on the other side.