Report a bug or request a featureContact support
Changelog
Back to All
improved

2024-12-12 Schema v2.1

8 days ago by Liz Krznarich

Schema v2.1: Tweaks to locations fields

The current ROR data structure was revised in April of 2024 and formalized into schema v2.0 as a JSON schema document. In schema v2.0, significant changes were made to fields that contained geographic information, including removing fields related to administrative subdivisions corresponding to units such as Canadian provinces, Japanese prefectures, and US states.

While no issues were raised with these changes during the v2.0 feedback process, since the launch of this schema version, the need for additional location details to be included in our records was identified by users. As a result, a proposal for schema v2.1, which adds country subdivision and continent fields, was circulated for public comment and finalized in Nov 2024.

This is a non-breaking change, and schema v2.1 changes have been incorporated directly into the v2 API with no version change needed in the API URL, per ROR's schema and API versioning policy.

Schema changes

In schema v2.1, the following fields have been added to thegeonames_details sub-field within thelocations field:

  • continent_code (required) 2-character code for the continent that the organization is located in, from the GeoNames record for the GeoNames ID in locations.geonames_id. All records have a value in the field.
  • continent_name(required) Name of the continent that the organization is located in, from the GeoNames record for the GeoNames ID in locations.geonames_id. All records have a value in the field.
  • country_subdivision_code2 or 3-character code for the highest-level country subdivision that the organization is located in, from the admin1Codes field of the GeoNames record for the GeoNames ID in locations.geonames_id. These are derived from ISO-3166-2.
  • country_subdivision_nameName of the highest-level country subdivision that the organization is located in, from the admin1Codes field of the GeoNames record for the GeoNames ID in locations.geonames_id. These are derived from ISO-3166-2.

Continents: GeoNames uses a 7-continent name and code convention, so continent name and code values are as follows: Africa (AF), Antarctica (AN), Asia (AS), Europe (EU), North America (NA), Oceania (OC), and South America (SA).

Country subdivisions: The type of subdivision represented by the country_subdivision_code and country_subdivision_name fields varies depending on the location identified by the Geonames ID in the locations.geonames_id field. For the United States, for example, it represents states. Some organizations are not located within a country subdivision (ex, research stations in Antarctica), so not all records have values in these fields. See ISO 3166-2 for a list of country subdivisions by country.

Also, in schema 1.0, Funder has been added as an allowed value in the types field. This is because Funder was initially added as a type in v2 only, and when new records are created in v2 that only have a type of Funder the corresponding v1 record has no values in types. NOTE: Most v2 records with Funder in types have multiple values in types, so only a very small number of records had no types in v1.

API changes

v2 API

  • The above new locations fields now appear in each record in when using the v2 API https://api.ror.org/v2/organizations.
  • continents now appears in the meta section of list results in the v2 API, exhttps://api.ror.org/v2/organizations.
  • New filters for continent name and code are now available in the v2 API, ex https://api.ror.org/v2/organizations?filter=locations.geonames_details.continent_name:Asia and https://api.ror.org/v2/organizations?filter=locations.geonames_details.continent_code:AS.
  • Data in locations fields in all records was updated using the latest values from GeoNames.

v1 API

  • Funder now appears in the types field of v1 records that have funder in types in their corresponding v2 record.
  • Funder is now an allowed value for the types filter, ex https://api.ror.org/organizations?filter=types:Funder.
  • Data in addresses fields in all records was updated using the latest values from GeoNames.
  • NOTE: Beginning with the April 2024 launch of v2, ROR metadata is curated only in v2 and then crosswalked / copied to v1 records. As a result, when records are added or updated, v1 fields that do not have equivalents in v2 are not populated. This includes many addresses sub-fields in v1 records. All records have been updated for v2.1 in release 1.58, and therefore deprecated sub-fields in addresses are now null in all v1 records.

Data dump changes

  • New fields listed above are included in the JSON and CSV v2 data dump files.
  • No changes have been made to filenames.
  • NOTE: Beginning with the April 2024 launch of v2, ROR metadata is curated only in v2 and then crosswalked / copied to v1 records. As a result, when records are added or updated, v1 fields that do not have equivalents in v2 are not populated. This includes many addresses sub-fields in v1 records. All records have been updated for v2.1 in release 1.58, and therefore deprecated sub-fields in addresses are now null in all v1 records.

Search UI changes