Send a mention of a software in a scientific publication#
API/CLI reference
This page will help you send a COAR Notification without getting into too much details, the Protocol reference and the Payload reference are available to explain all the technical specifications.
It is possible to deposit metadata on an already existing software origin or SWHID by using the Announce Relationship pattern.
Checklist#
You have access to your account credentials
You have your own COAR Notify Inbox running
You have a tool to make API calls, we will use curl here, but commands could be easily adapted to another application
Prepare the notification payload#
To announce that the scientific paper https://your-organization.tld/item/12345/
mentions the software parmap. The notification
will look like:
{
"@context": [
"https://www.w3.org/ns/activitystreams",
"https://coar-notify.net"
],
"actor": {
"id": "https://your-organization.tld",
"name": "Your Organization",
"type": "Organization"
},
"context": {
"id": "swh:1:dir:ec88e5b901c034d5a91aa133e824d65cff3788a3;origin=https://github.com/rdicosmo/parmap;visit=swh:1:snp:25490d451af2414b2a08ece0df643dfdf2800084;anchor=swh:1:rev:db44dc9cf7a6af7b56d8ebda8c75be3375c89282",
"type": [
"sorg:SoftwareSourceCode"
]
},
"id": "urn:uuid:6908e2d0-ab41-4fbf-8b27-e6d6cf1f7b95",
"object": {
"as:subject": "https://your-organization.tld/item/12345/",
"as:relationship": "https://w3id.org/codemeta/3.0#citation",
"as:object": " swh:1:dir:ec88e5b901c034d5a91aa133e824d65cff3788a3;origin=https://github.com/rdicosmo/parmap;visit=swh:1:snp:25490d451af2414b2a08ece0df643dfdf2800084;anchor=swh:1:rev:db44dc9cf7a6af7b56d8ebda8c75be3375c89282",
"id": "urn:uuid:74FFB356-0632-44D9-B176-888DA85758DC",
"type": "Relationship"
},
"origin": {
"id": "https://your-organization.tld/repository",
"inbox": "https://inbox.your-organization.tld",
"type": "Service"
},
"target": {
"id": "https://www.softwareheritage.org",
"inbox": "https://inbox.staging.swh.network",
"type": "Service"
},
"type": [
"Announce",
"coar-notify:RelationshipAction"
]
}
Check the full Payload reference for an explanation of the keys in use.
Save the file as notification.json
.
Send the notification#
curl -H 'Authorization: Token <TOKEN>' \
-H 'Content-Type: application/ld+json' \
-i --data @notification.json \
https://inbox.staging.swh.network
Will return a 201 created
HTTP response containing a location
header with the
url to your notification:
https://inbox.staging.swh.network/6908e2d0-ab41-4fbf-8b27-e6d6cf1f7b95
Please note that a 201 created
response does not mean we were able to properly
archive this mention, only that we were able to validate its structure.
Now that we have stored your notification we’ll process it and send you a reply following the COAR Notify protocol.
Handle the reply#
If something went wrong you’ll receive either a UnprocessableNotification
or a
Reject
with a summary
key explaining the reason why we were not able to
archive this mention.
Otherwise you will receive an Accept
notification which indicates that your mention
was sent to our metadata storage.
The InReplyTo
key of these notifications will contain the id
of your initial
Notification.