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
, andlabels
fields is now contained in a single parent fieldnames
with subfieldslang
,value
andtypes
.Location information previously in
addresses
field is now inlocations
field with subfieldsgeonames_id
andgeoneames_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
andwikipedia_url
have been combined into a single parent fieldlinks
with subfieldstype
andvalue
. Theip_addresses
field has been removed, and a newdomains
field has been added.External identifiers information has been restructured within the existing
external_ids
field. Each item in external_ids now has subfieldstype
,all
andpreferred
.Administrative information was not included previously. A new parent field
admin
has been added, which contains subfieldscreated
andlast_modified
. Each of those subfields contains additional subfieldsdate
andschema_version
.Controlled lists previously had variations in casing. For example, values in the
types
andrelationships.type
fields began with an uppercase character, while values instatus
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 thelabels
field in the current schema. Language codes HAVE NOT been added for names inherited from thename
andaliases
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?
Read the complete beta documentation and testing instructions.
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 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.
RSS Feed
Categories
Archives
Tags
- adoption
- annual-meeting
- api
- aps
- caltechdata
- clear-skies
- coki
- communication
- community
- cross-post
- crossref
- curation
- data
- datacite
- datasalon
- development
- dryad
- europepmc
- fairsharing
- feedback
- figshare
- funders
- governance
- grei
- grid
- hierarchy
- implementation
- integrations
- interviews
- inveniordm
- jobs
- latin-america
- machine-learning
- matching
- metadata
- mvr
- open-access
- open-infrastructure
- openalex
- optica
- orcid
- osf
- persistent-identifiers
- pidapalooza
- pids
- prototype
- publishers
- registry
- research-integrity
- researchequals
- resources
- rockefeller-university-press
- schema
- scholastica
- silverchair
- steering-group
- straininfo
- sustainability
- team
- working-group
- zenodo