Names ordering in `v2` - Githubissues

chartgerink commented 1 year ago

Thank you for the incredibly considerate process for the ROR v2 API consultations and feedback period. It's always hard to run community based projects and I appreciate the opportunity to share some feedback from my experience. None of these are demands - only a conversation starter 😊

Which ROR schema/API v2 functionality did you find an issue with?

[ ] Retrieving a single record (https://dev.api.ror.org/v2/organizations/[RORID])
[ ] Retrieving multiple records (https://dev.api.ror.org/v2/organizations)
[ ] Quick search using ?query parameter (https://dev.api.ror.org/v2/organizations?query=)
[x] Advanced search using ?query.advanced parameter (https://dev.api.ror.org/v2/organizations?query.advanced=)
[ ] Affiliation matching using ?affiliation parameter (https://dev.api.ror.org/v2/organizations?affiliation)
[ ] Data dump JSON file
[ ] Data dump CSV file
[ ] Something else (please describe below in Issue description section)

Issue description

Describe the issue & steps to reproduce, if applicable. For issues with API requests, please include the full request URL. We implement API based retrieval of organization information on ResearchEquals. For the v2 changes, the updated names list (previously name) is a breaking change for our implementation - it became clear this was breaking only upon trying to implement it for feedback here.

Switching from our current implementation to names, I provisionally used the first item in the list of names to be the authoritative one (i.e., Array [ "ror_display", "label" ]), but I cannot find in the documentation whether this will always be first in the names array. Is that assumption (in)correct?

If the assumption is incorrect, it will require additional filtering code to assure quality implementations from our end, which would be helpful to understand.

Expected behavior/desired solution

Please provide a clear and concise description of what you expected or would like to happen. It would be helpful for the API changelog to have standardized language to mark changes as adding, changing, or removing functionality. This helps assess where there may be breaking changes for specific implementations as it was not clear at this moment until implementing. An example could be the Stripe changelog.

I understand it may be implied that an array of objects cannot be expected to be sorted in any way. For the v2 upgrade it might be helpful for the documentation to be explicit about this in this scenario as the change makes handling the response slightly more complex (in case others are upgrading in the future too). Would you be able to confirm whether or not the array can be expected to be sorted in any specific way?

Additional context

Please provide any additional information about your specific use case, so that we can better understand the issue. The change from name to names requires additional filtering code if the rank order is not guaranteed, which will regrettably make the code to use the API somewhat more convoluted (requiring an additional filter). I reviewed previous draft proposals but did not realize this until implementing.

Please see also our draft PR where we will track our upgrade and you can see the current implementation (which assumes the first value in the array is the authorative name). https://github.com/libscie/ResearchEquals.com/pull/1739

Optional info

Name of the organization(s) you represent/are affiliated with

Liberate Science GmbH

Type of organization(s) you represent/are affiliated with

[ ] Research institution
[ ] Funder
[x] Publisher
[ ] System vendor/service provider
[ ] Other

Which ROR tools/features do you currently use?

[x] Retrieving a single record (https://api.ror.org/organizations/[RORID])
[x] Retrieving multiple records (https://api.ror.org/organizations)
[x] Quick search using ?query parameter (https://api.ror.org/organizations?query=)
[x] Advanced search using ?query.advanced parameter (https://api.ror.org/organizations?query.advanced=)
[x] Affiliation matching using ?affiliation parameter (https://api.ror.org/organizations?affiliation)
[ ] Data dump JSON
[ ] Data dump CSV
[ ] None (or none yet)
[ ] Something else (please describe below)

lizkrznarich commented 1 year ago

@chartgerink Thanks for the feedback! While records converted programmatically from v1 to v2 all have the ROR display name as the first item in the names array, we cannot 100% guarantee that this will be the case for all future records (though it will likely be the case for most records). I would recommend parsing the names array to extract the name with ror_display in its types. I know that this is more work, however, this is the solution that shook out of the community input process in order to 1. support more potential name types in the future (ex, legal name) without major schema changes and 2. avoid ROR making a subjective decision about which name is "primary" in the case where an organization's name is equally official in multiple languages.

We're aware that the changes to the name fields will impact nearly every ROR API/data dump user, and we do plan to write migration guides for those and other fields. When completely, those will live on our docs site https://ror.readme.io/docs. Under the hood, ROR API updates tend to span multiple repositories, so our changelog lives on our docs site https://ror.readme.io/changelog . This will absolutely be updated with the v2 change details when they are deployed to production.