Dataset Versions API: add version differences

[ekraffmiller]

Overview of the Feature Request
For the SPA, we need to update the List Dataset Versions API with the differences between each version, for displaying in the Dataset Versions tab.
For example,

There is already an endpoint for getting the differences between any two versions - https://guides.dataverse.org/en/latest/api/native-api.html#compare-versions-of-a-dataset. The same logic can be re-used to return the differences between versions.

What kind of user is the feature intended for?
(Example users roles: API User, Curator, Depositor, Guest, Superuser, Sysadmin)
API user

What inspired the request?
SPA: Dataset Versions Tab

What existing behavior do you want changed?
Add version difference information to List Dataset Versions API

[johannes-darms]

Please reconsider this feature. We have datasets with >100 versions and quite a few differences between versions. I think the payload will be huge and calculating all those diffs will take some time, resulting in a slow response time. I'd rather suggest a separate request for each difference.

[sekmiller]

@johannes-darms, @ekraffmiller in the jsf version we use an asynchronous load/update of the dataset page, since the default tab is the file list. If the user clicks into the versions tab before the processing is finished they may get a "Loading..." message. I don't think we've gotten too many complaints about this.

[sekmiller]

@ekraffmiller If the response is something like this will it work? {"status":"OK","data":{"302":{"versionNumber":"DRAFT","summary":"Subject (1 Added, 1 Changed); Additional Citation Metadata: (2 Added); Terms of Use/Access Changed","contributors":"Dataverse Admin","publishedOn":""},"301":{"versionNumber":"3.1","summary":"Description (1 Changed); Title (Changed); Additional Citation Metadata: (1 Added); ","contributors":"Dataverse Admin","publishedOn":"2025-02-03"},"296":{"versionNumber":"3.0","summary":"Files (Added: 1)","contributors":"Dataverse Admin","publishedOn":"2025-01-29"},"288":{"versionNumber":"2.0","summary":"Files (Added: 1)","contributors":"Dataverse Admin","publishedOn":"2025-01-27"},"283":{"versionNumber":"1.0","summary":"This is the first published version.","contributors":"Dataverse Admin","publishedOn":"2025-01-27"}}}

[sekmiller]

@ekraffmiller @qqmyers I have some odd ball cases in this example, but I was already picking up File Metadata changes by basing the api on the dataset-versions tab {"status":"OK","data":{"302":{"versionNumber":"DRAFT","summary":"Subject (1 Added, 1 Changed); Additional Citation Metadata: (2 Added); Files (Changed File Metadata: 1)Terms of Use/Access Changed","contributors":"Dataverse Admin","publishedOn":""},"301":{"versionNumber":"3.1","summary":"Description (1 Changed); Title (Changed); Additional Citation Metadata: (1 Added); Files (Added: 1)","contributors":"Dataverse Admin","publishedOn":"2025-02-03"},"296":{"versionNumber":"3.0","summary":"Deaccessioned Reason: There is identifiable data in one or more files. Something, something on a heap!","contributors":"Dataverse Admin","publishedOn":"2025-01-29"},"288":{"versionNumber":"2.0","summary":"Due to the previous version being deaccessioned, there are no difference notes available for this published version.","contributors":"Dataverse Admin","publishedOn":"2025-01-27"},"283":{"versionNumber":"1.0","summary":"Deaccessioned Reason: Not a valid dataset. Just cuz","contributors":"Dataverse Admin","publishedOn":"2025-01-27"}}}

[qqmyers]

Sorry - I was confusing this issue with #11198 for files. (For that - I was just seeing that the

dataverse/src/main/java/edu/harvard/iq/dataverse/DatasetVersionDifference.java

Line 359 in aebec05

public static Map<String,List<String>> compareFileMetadatas(FileMetadata fmdo, FileMetadata fmdn) {

creates a map of the differences and the code at

dataverse/src/main/java/edu/harvard/iq/dataverse/DatasetVersionDifference.java

Line 1711 in aebec05

if (!changedFileMetadata.isEmpty()) {

turns that into Json which is sent back in the /api/datasets/{id}/versions/{versionId1}/compare/{versionId2} call.)

For this PR - would it make sense to just send the JSON differences as currently sent in /api/datasets/{id}/versions/{versionId1}/compare/{versionId2} and let the SPA create the text?

[sekmiller]

We already had the summary code written into the difference object, so it's already working. Most of what I'm doing here is adapting the process of the jsf converting it for the versions tab to a json output response.

[sekmiller]

Spoke to Ellen about this this morning. I will provide the elements of the summary objects as json and not do any translating/formatting.

[sekmiller]

Proposed new response:

{
"status": "OK",
"data": {
"305": {
"versionNumber": "1.0",
"summary": "firstPublished",
"contributors": "Dataverse Admin",
"publishedOn": "2025-02-06"
},
"306": {
"versionNumber": "DRAFT",
"summary": {
"dsDescription": {
"added": 0,
"deleted": 0,
"changed": 1
},
"title": {
"added": 0,
"deleted": 0,
"changed": 1
},
"geospatial": {
"added": 1,
"deleted": 0,
"changed": 0
},
"citation": {
"added": 2,
"deleted": 0,
"changed": 0
},
"files": {
"added": 1,
"removed": 0,
"replaced": 0,
"changedFileMetaData": 2,
"changedVariableMetadata": 0
},
"termsAccessChanged": "false"
},
"contributors": "Dataverse Admin",
"publishedOn": ""
}
}
}