IQSS
feat: add "isInReviewState" to API responses about dataset versions
What this PR does / why we need it:
This PR adds "isInReviewState" to API responses about dataset versions, which is useful information.
Which issue(s) this PR closes:
Not aware of any issue.
Special notes for your reviewer:
/
Suggestions on how to test this:
I've extended the API test: mvn test -Dtest="DatasetsIT#testDatasetVersionsAPI"
Does this PR introduce a user interface change? If mockups are available, please link/include them here:
/
Is there a release notes update needed for this change?:
I've added a short release note.
Additional documentation:
/
@vera - FWIW: I think we have design questions about this. Being in review is because of a review lock and we already have an API for locks: https://guides.dataverse.org/en/latest/api/native-api.html#dataset-locks . While understanding that it can be convenient to get all useful info in a single call, having multiple ways to get the same info can be confusing. Further, making the output of a GET different from what's allowed in a PUT can also be confusing and make it harder for API users to deal with round trip changes. We certainly have cases where we've allowed extra info in GETs for convenience already, but we're starting to question doing more of that. In this case, I think there's an additional question too: are we starting down a road where we will also have entries for all the other possible locks in the version response?
I think the things were discussing are:
- accept this and punt the question of what's best to the version 2 API (in the indefinite future),
- if this info is always important when you get version info, does that also apply to other locks, and, if so, should we instead ask for a PR to add all locks to the version API (one "locks" key whose value is the same as the locks api?), or
- just reject given that there is a way to get the info already. I'm not sure there's a consensus yet, but your opinion on whether the locks api is sufficient, whether getting the rest of the lock info is going to be needed and so making a more general PR makes sense, or whether this PR, as is, is really key for some reason, would be useful input.
I think it useful to add isInReview to the API response - although we haven't implemented the Submit for Review feature yet in the SPA, we do need to display an 'In Review' label in the View Dataset page, and we already are returning 'In Review' in the search results on the Collection Page. When a Dataset is In Review, the search API returns that in an array of publicationStatuses (see example below). Other locks, like 'Ingest' and 'PidRegister' are more transient, they only last while an automatic process is ongoing. But since 'In Review' lock depends on user actions, it lasts longer, and I think it makes sense to return it as part of the response.
{
"status": "OK",
"data": {
"q": "*",
"total_count": 93,
"start": 0,
"spelling_alternatives": {},
"items": [
{
"name": "Ellen's dataset",
"type": "dataset",
"url": "https://doi.org/10.5072/FK2/LXDCT9",
"global_id": "doi:10.5072/FK2/LXDCT9",
"description": "test",
"publisher": "Root",
"citationHtml": "Kraffmiller, Ellen, 2025, \"Ellen's dataset\", <a href=\"https://doi.org/10.5072/FK2/LXDCT9\" target=\"_blank\">https://doi.org/10.5072/FK2/LXDCT9</a>, Root, DRAFT VERSION",
"identifier_of_dataverse": "root",
"name_of_dataverse": "Root",
"citation": "Kraffmiller, Ellen, 2025, \"Ellen's dataset\", https://doi.org/10.5072/FK2/LXDCT9, Root, DRAFT VERSION",
"publicationStatuses": [
"Unpublished",
"Draft",
"In Review"
],
"storageIdentifier": "s3://10.5072/FK2/LXDCT9",
"subjects": [
"Agricultural Sciences"
],
"fileCount": 0,
"versionId": 89,
"versionState": "DRAFT",
"createdAt": "2025-12-03T14:51:18Z",
"updatedAt": "2025-12-03T15:02:24Z",
"contacts": [
{
"name": "Kraffmiller, Ellen",
"affiliation": ""
}
],
"publications": [
{}
],
"authors": [
"Kraffmiller, Ellen"
]
},
.....
],
"count_in_response": 10
}
}
@ekraffmiller RE: "publicationStatuses": [ "Unpublished", "Draft", "In Review" ]
Does it make sense for the localization to be done in the backend? Wouldn't it make more sense to return a fixed value that can be localized by the UI?
Hi @vera, thanks for your PR! We discussed it and think that for maintainability, it would be better to return a list of current locks on the dataset, rather than having a flag for the existence of a particular lock. That way if more locks are added in the future, the API code won't need to be updated.
@ekraffmiller RE: "publicationStatuses": [ "Unpublished", "Draft", "In Review" ]
Does it make sense for the localization to be done in the backend? Wouldn't it make more sense to return a fixed value that can be localized by the UI?
This is a good point. We have discussed handling multiple languages in general by adding a requested language in the API header. We we implement that, this data could be returned in the requested language, rather than translated in the frontend.
We have discussed handling multiple languages in general by adding a requested language in the API header.
Yes, here's an (unmerged) example: https://github.com/IQSS/dataverse/pull/11753/commits/99fcede6aa3a31d96e3a3933b8b2c0ffff227d88
And here's the (merged) language switcher:
- https://github.com/IQSS/dataverse-frontend/pull/880
