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.
Name information previously in
labelsfields is now contained in a single parent field
Location information previously in
addressesfield is now in
locationsfield with subfields
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
wikipedia_urlhave been combined into a single parent field
ip_addressesfield has been removed, and a new
domainsfield has been added.
External identifiers information has been restructured within the existing
external_idsfield. Each item in external_ids now has subfields
Administrative information was not included previously. A new parent field
adminhas been added, which contains subfields
last_modified. Each of those subfields contains additional subfields
Controlled lists previously had variations in casing. For example, values in the
relationships.typefields began with an uppercase character, while values in
statuswere 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.
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:
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
adminfield, using actual dates from GRID and ROR data releases.
- Domains HAVE NOT been added. The new
domainsfield is currently an empty list for all records.
- Language codes for items in the new
namesfield are only included for names inherited from the
labelsfield in the current schema. Language codes HAVE NOT been added for names inherited from the
aliasesfields 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.
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.
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 email@example.com . 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.