Editing terms of use and license via API

[paul....@ubc.ca]

I was wondering if there was a way to edit the 'license' and 'termsOfUse' of a Dataverse study.  There is the  "Updata metadata for a dataset" example (https://guides.dataverse.org/en/5.6/api/native-api.html#update-metadata-for-a-dataset), which translated to Python using requests yields:

requests.put('https://test.invalid/api/datasets/:persistentId/versions/:draft', headers=headers, params=params, json=some_new_meta)

where  headers and params are the headers and parameters respectively, and some_new_meta is a dict like {'metadataBlocks': {arbitraryData}'}}. This works just fine.

Of course, 'license' and 'termsOfUse' aren't children of 'metadataBlocks'. That is, if you have a look at a dataset's latest version, the top level keys are:

dict_keys(['id', 'datasetId', 'datasetPersistentId', 'storageIdentifier', 'versionState', 'distributionDate', 'lastUpdateTime', 'createTime', 'license', 'termsOfUse', 'fileAccessRequest', 'metadataBlocks', 'files'])

Attempting the same style of put request, ie, passing JSON like {'termsOfUse':'EULA goes here'} fails with a 500. I'm assuming that's because they're not part of the 'metadataBlocks' tree.

It's certainly possible that I have made a gross blunder with my code, but seeing as I have no problem updating the metadataBlocks and the structure of license and termsOfUse are much simpler, I suspect that either I'm using the wrong API endpoint or that it can't be done via the API.

I'm hoping for the former but suspect the latter.  If the latter, I hope this functionality exists and I've just missed it or that it can be added. It's not unheard of license terms to be changed, as I have clearly discovered. I also think that license and terms should be considered part of the metadata, but that's a more philosophical discussion. Thanks in advance for any guidance you can provide.

Sincerely,

Paul Lesack

University of British Columbia Library

[James Myers]

Paul,

As far as I know, there hasn’t been a way to set these via API – as you found, the json add/edit/delete api calls in the native api are focused on the metadata in the blocks.

 

There is a new ‘experimental’ API that allows this - added in v5.6 and documented in the developers: https://guides.dataverse.org/en/latest/developers/dataset-semantic-metadata-api.html?highlight=semantic%20api . This API uses json-ld instead – the same format as in the OAI_ORE metadata export.

 

Copying and altering the example in the guides, setting the TermsOfUse field would be done with

 

  curl -X PUT -H X-Dataverse-key:$API_TOKEN -H 'Content-Type: application/ld+json' -d '{" https://dataverse.org/schema/core#termsOfUse":"Some terms"}' "$SERVER_URL/api/datasets/$DATASET_ID/metadata?replace=true"

 

or

  curl -X PUT -H X-Dataverse-key:$API_TOKEN -H 'Content-Type: application/ld+json' -d '{" dvcore:termsOfUse":"Some terms", "@context":{"dvcore":"https://dataverse.org/schema/core#"}}' "$SERVER_URL/api/datasets/$DATASET_ID/metadata?replace=true"

 

The other Terms fields are in the same namespace: e,g, confidentialityDeclaration, specialPermissions, restrictions, citationRequirements, depositorRequirements, conditions, and disclaimer.

In general, if you look in the ore:describes object in the OAI_ORE export, the semantic APIs use the same identifiers and sub-structure (i.e. for compound fields in metadata blocks). Aside from also supporting terms and licenses (which will be maintained as the multi-license support PR is added) one of the nice things about the semantic API is that it has a flatter structure.

 

FWIW: The API is ‘experimental’ and listed in the developer guide for a couple reasons – json-ld and the potential to use an @context for readability can be confusing, the API is new and has had less breadth of use than the earlier APIs, and it may be that the API itself and/or identifiers used may change at some point. That said, both DANS and Sciences PO are developing with it now and the DVUploader has an experimental capability to recreate a Dataset from the OAI_ORE file in an exported Bag using the semantic APIs and it works. If you find issues with it and/or limitations, please report them so we can make fixes. If you have further questions, just let me know.

 

-- Jim

--
You received this message because you are subscribed to the Google Groups "Dataverse Users Community" group.
To unsubscribe from this group and stop receiving emails from it, send an email to dataverse-commu...@googlegroups.com.
To view this discussion on the web visit https://groups.google.com/d/msgid/dataverse-community/ce35580f-1cdb-4076-bb0f-d3016f25c1efn%40googlegroups.com.

[Lesack, Paul]

Hi Jim,

Thank you so much for this. It didn’t occur to me to look in that section of the user guide, and your additions were incredibly helpful. You have undoubtedly saved me much time and tedium.

For those who are reading this as it is relevant to their interests and flnd translating curl to Python painful, here’s a translated example that should help explain the process.

import requests #install requests with pip, not a std library
hdl = 'hdl:test/invalid' #can be a DOI, of course
headers = {'X-Dataverse-key': 'this is your api-key',
'Content-Type': 'application/ld+json'}
ltext = ('<h2>License</h2><p>This is an arbitrary license. '
'<h3>Disclaimer</h3><p>Not valid as a license</p>')
params = {'persistentId' : hdl, 'replace' : 'true'}
data = {'dvcore:termsOfUse' : ltext,
'@context' : {'dvcore' : 'https://dataverse.org/schema/core#'}}
req = requests.put('https://test.invalid/api/datasets/:persistentId/metadata',
headers=headers, params=params, json=data)

———
After that, you can check if it worked:
req.json()
{'status': 'OK', 'data': {'Version Updated': 'Dec 2, 2021'}}

Paul




> On Dec 1, 2021, at 5:06 PM, James Myers <qqm...@hotmail.com> wrote:
>
> [CAUTION: Non-UBC Email]

> You received this message because you are subscribed to a topic in the Google Groups "Dataverse Users Community" group.
> To unsubscribe from this topic, visit https://groups.google.com/d/topic/dataverse-community/WNHsWOwxtVw/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to dataverse-commu...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/dataverse-community/MN2PR07MB73433070EDD80E2ECF8D91DCBF699%40MN2PR07MB7343.namprd07.prod.outlook.com.

[Philip Durbin]

Yes, thank you, Jim.

As a side note, we're aware that API documentation is a bit scattered. We did recently update "Lists of Dataverse APIs" to include a link to that new semantic metadata API and other new APIs: https://guides.dataverse.org/en/5.8/api/intro.html#lists-of-dataverse-apis

Hmm, I just realized we should update the "Where is the Comprehensive List of All API Functionality?" FAQ because Swagger/OpenAPI is now working. That is, you can see a dump in YAML of all API endpoints at https://demo.dataverse.org/openapi . Here's a link to that FAQ: https://guides.dataverse.org/en/5.8/api/faq.html#where-is-the-comprehensive-list-of-all-api-functionality

To view this discussion on the web visit https://groups.google.com/d/msgid/dataverse-community/CB93F92A-111D-41D4-974C-B68B1B8C1961%40ubc.ca.

--

Philip Durbin
Software Developer for http://dataverse.org
http://www.iq.harvard.edu/people/philip-durbin