--- agentTools: projectIndex: https://ror.readme.io/llms.txt --- # 2024-12-12 Schema v2.1 Today we are announcing a non-breaking change to the ROR schema that adds geographic location. The current ROR data structure was revised in April of 2024 and formalized into [schema v2.0](https://ror.readme.io/docs/schema-v2) 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](https://docs.google.com/document/d/11-bDfQWK038uoUBkL_CBZxP__xB6nBy0dVPH7tWxNnY), 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](https://ror.readme.io/v2/docs/api-versions). ## Schema changes In schema v2.1, the following fields have been added to the`geonames_details` sub-field within the`locations` 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_code`2 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](https://en.wikipedia.org/wiki/ISO_3166-2). * `country_subdivision_name`Name 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](https://en.wikipedia.org/wiki/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, ex`https://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](https://github.com/ror-community/ror-updates/releases/tag/v1.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](https://github.com/ror-community/ror-updates/releases/tag/v1.58), and therefore deprecated sub-fields in `addresses` are now null in all v1 records. ## Search UI changes * No changes have been made to the search UI at .