2022-12-01 Organization status changes

After a 6-month period of planning, community input and implementation, we've released changes to the API, UI and data dump in order to support cases where an organization has ceased to operate, merged with another organization, was added to ROR in error. Read the rest of this post for complete details!

These changes were developed in consultation with the ROR community; a draft proposal was open for public comment 15 Jun-15 Jul 2022 and a "final" proposal was shared in Aug 2022. The specifications for these changes were based on the final proposal.

These changes are non-breaking and are compatible with the current ROR schema.

What changed?

Record schema

New values allowed in status field:

• inactive: Organization no longer operates as described in its ROR record. For example, it has split into multiple organizations, merged with 1 or more organizations or has otherwise ceased to operate.
• withdrawn: Organization whose ROR record was created in error. For example, the organization already existed in ROR under a different name or the organization is not in scope for ROR and should not have been added.

New values allowed in relationships.type field:

• Successor: An active organization that continues the work of a given organization after it has become inactive
• Predecessor: An inactive organization that previously carried out the work of a given organization

Note: Unlike Parent/Child relationships in ROR, Successor/Predecessor relationships are not always added in pairs. In other works, each Successor relationship does not necessarily have a corresponding Predecessor relationship.

See ROR data structure for more information about status and relationships.

API

• Returns active records only by default; use parameter ?all_status to return all records. ?all_status=true and ?all_status=false are also supported. This is true for listing organizations using /organizations, querying using either ?query or ?query.advanced and matching affiliation strings using ?affiliation.
• When retrieving a record by its ROR ID, the record will be returned regardless of its status and whether ?all_status or ?filter parameters are present.
• New filter parameter value status is available, ex ?filter=status:inactive. If ?filter=status: is used, ?all_status parameter is ignored.
• New status and relationship type values are available in fielded searches using query.advanced, ex ?query.advanced=status:inactive. If a fielded search includes status field, ?all_status parameter is ignored.
• New aggregation statuses in meta section of responses

Data dump

• Data dump files include all records with all statuses. No changes, except that some records contain the new values above in status and relationships.type fields. The first data dump file with new status and relationship type values is https://doi.org/10.5281/zenodo.7387951.

Search UI

• List views return active records only by default
• Results can be filtered by status
• Query for a specific ROR ID will return matching result regardless of status

Data release v1.15

Additionally, we’ve just published data release v1.15, which is the first data release that includes records with the new status and relationship type values above. Release v1.15 includes open IDs and metadata for 103,047 organizations (102,935 active, 103 inactive, 9 withdrawn). Both the API and data dump have been updated. The latest data dump is available at https://doi.org/10.5281/zenodo.7387951. This release includes updated records listed in the v1.15 data release notes.

Example records

Inactive

• https://ror.org/02h60r346 (no successor)
• https://ror.org/000d53575 (with successor)

Withdrawn

• https://ror.org/03ybx0x41 (with successor)

Example API requests

List active organizations only (no change from existing request)

curl https://api.ror.org/organizations

Note: Request above returns same results as ?filter=status:active and ?query.advanced=status:active

List organizations with any status

curl https://api.ror.org/organizations?all_status

Query active organizations only (no change from existing request)

curl https://api.ror.org/organizations?query=university

Query organizations with any status

curl https://api.ror.org/organizations?query=university&all_status

Match affiliation strings to active organizations only (no change from existing request)

curl https://api.ror.org/organizations?affiliation=Laboratory+of+Hydrology+and+Geochemistry

Match affiliation strings to organizations with any status

curl https://api.ror.org/organizations?affiliation=Laboratory+of+Hydrology+and+Geochemistry?all_status

Filter by status

curl https://api.ror.org/organizations?filter=status:inactive

Can be repeated, for example to retrieve organizations with a status of inactive OR withdrawn

curl https://api.ror.org/organizations?filter=status:inactive,status:withdrawn

Can be combined with other filters (see list of available filters and values)

curl https://api.ror.org/organizations?filter=status:inactive,status:withdrawn,country.country_code:us

Can be combined with ?query or ?query.advanced searches.
Note: Filters cannot be used with ?affiliation searches.

curl 'https://api.ror.org/organizations?query=International+Union&filter=status:inactive,status:withdrawn'

Use new status/relationship type values in fielded searches

Note: if a fielded search includes status field, ?all_status is not needed in order to return records with statuses other than active.

curl 'https://api.ror.org/organizations?query.advanced=status:inactive+AND+addresses.city:Yerevan'

curl 'https://api.ror.org/organizations?query.advanced=status:inactive+AND+relationships.type:Successor'

The API documentation has also been updated to reflect the above changes.