feat: add "isInReviewState" to API responses about dataset versions

[vera]

What this PR does / why we need it:

This PR adds "isInReviewState" to API responses about dataset versions, which is useful information.

This PR adds a list of locks currently active on a dataset to the API response sent by GET /api/datasets/$ID.

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"

mvn test -Dtest="DatasetsIT#testDatasetLocksApi"

mvn test -Dtest="InReviewWorkflowIT"

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:

/

[stevenwinship]

Change isInReviewState to isInReview since this is not a state. Being in review is a lock

[qqmyers]

@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.

[ekraffmiller]

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
    }
}

[stevenwinship]

@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?

[ekraffmiller]

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]

@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.

[pdurbin]

We have discussed handling multiple languages in general by adding a requested language in the API header.

Yes, here's an (unmerged) example: 99fcede

And here's the (merged) language switcher:

• New SPA Runtime Configuration and Language Selector dataverse-frontend#880

[stevenwinship]

@vera
Hi, could you let me know if you are addressing the comments in this issue? It has been in review for a while now. Thanks

[vera]

@vera Hi, could you let me know if you are addressing the comments in this issue? It has been in review for a while now. Thanks

@stevenwinship yes, I'm sorry for the delay. I am out of office next week and hope to address the comments as soon as possible after I return

[vera]

Thank you all for your feedback and for discussing this PR @qqmyers @ekraffmiller @stevenwinship and sorry again for the delay in responding.

I have made the changes requested (returning a list of current locks, not returning the single flag).

Since locks are dataset-level, not version-level, I felt like it makes sense to return the info from GET /api/datasets/$ID and not GET /api/datasets/$ID/versions.

I assumed that it makes sense to return only a list of the lock types, since I don't want to clutter up the API response, and all other details about the lock(s) like start time or user can be retrieved using the already existing GET /api/datasets/$ID/locks.

Example API response:

{
    "status": "OK",
    "data": {
        "id": 7,
        "identifier": "FK2/E1GLL9",
        "persistentUrl": "https://doi.org/10.5072/FK2/E1GLL9",
        "protocol": "doi",
        "authority": "10.5072",
        "separator": "/",
        "publisher": "Root",
        "storageIdentifier": "local://10.5072/FK2/E1GLL9",
        "datasetType": "dataset",
        "locks": [
            "InReview"
        ],
        "latestVersion": {
            "id": 3,
            "datasetId": 7,
            "datasetPersistentId": "doi:10.5072/FK2/E1GLL9",
            "datasetType": "dataset",
            "storageIdentifier": "local://10.5072/FK2/E1GLL9",
            "internalVersionNumber": 6,
            "versionState": "DRAFT",
            "isInReviewState": true,
            "latestVersionPublishingState": "DRAFT",
            "UNF": "UNF:6:x10r+Q9EK6aF/BMi+eKzGw==",
            "lastUpdateTime": "2026-01-23T14:43:22Z",
            "createTime": "2026-01-23T14:43:20Z",
            "license": {
                "name": "CC0 1.0",
                "uri": "http://creativecommons.org/publicdomain/zero/1.0",
                "iconUri": "https://licensebuttons.net/p/zero/1.0/88x31.png",
                "rightsIdentifier": "CC0-1.0",
                "rightsIdentifierScheme": "SPDX",
                "schemeUri": "https://spdx.org/licenses/",
                "languageCode": "en"
            },
            "fileAccessRequest": false,
            "metadataBlocks": {...},
            "files": [...]
        }
    }
}

(Just FYI, I had initially used the "My data" API response as inspiration, which returns a flag called is_in_review_state for each dataset, which is why I chose the similar name isInReviewState:

{
  "success": true,
  "data": {
    "pagination": {...},
    "items": [
      {
        "name": "Test title",
        "type": "dataset",
        ...
        "publicationStatuses": [
          "Unpublished",
          "Draft"
        ],
        "versionId": 64654,
        "versionState": "DRAFT",
        "publication_statuses": [
          "Unpublished",
          "Draft"
        ],
        "is_draft_state": true,
        "is_in_review_state": false,
        "is_unpublished_state": true,
        "is_published": false,
        "is_deaccesioned": false,
        "is_valid": true,
        ...
      },
      ...
    ]
  }
}

)

[coveralls]

coverage: 24.333% (-0.001%) from 24.334%
when pulling 3a7bb2c on vera:feat/is-in-review-state
into cc37d4d on IQSS:develop.