Organization status implementation (Oct/Nov 2022)

On 1 Dec 2022, ROR plans to release 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.

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, but we're making them available in development environments prior to production release to ensure that integrators have an opportunity to test and adapt their applications as needed.

What's changing?

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 ?allStatus 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 file includes all records with all statuses. No changes, except that records may contain new values in status and relationships.type fields.

Search UI

  • Returns active records only by default
  • Results can be filtered by status (note: work on status filter is still in progress)

Testing & feedback

We have deployed several records with the new statuses and relationship types to our development environment and created a sample data dump with the same records. Access these resources at:

Records with inactive/withdrawn statuses are:

Testing notes:

  • Records in the dev environment use the production domain "ror.org" in their id field, but they are retrieved in the web search interface using the dev domain "dev.ror.org".
  • The dev environment is actively used for development purposes, so you may see changes deployed here during the beta testing period (particularly in the web search interface). We would typically use the staging environment for beta testing, but, staging is tightly integrated into ROR's curation workflow, so using it for testing changes would block curation activities.

Reporting issues

  • To report any issues you find in testing, please add comments to the request for feedback on the ROR Community Roadmap GitHub Discussion forum.
  • Note that the metadata approach for handling organization status changes and successors/predecessors have already been through several rounds of community feedback. At this point, we are primarily interested in feedback on the technical implementation, especially any bug/issues.

Example API requests

List active organizations only (no change from existing request)

curl https://api.dev.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.dev.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.dev.ror.org/organizations?filter=status:inactive

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

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

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

curl https://api.dev.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.dev.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.dev.ror.org/organizations?query.advanced=status:inactive+AND+addresses.city:Yerevan'
curl 'https://api.dev.ror.org/organizations?query.advanced=status:inactive+AND+relationships.type:Successor'