Related JIRA
PLFM-8536 - Getting issue details... STATUS
PLFM-8734 - Getting issue details... STATUS
DESIGN-807 - Getting issue details... STATUS
Introduction
Today Synapse allows to mint a DOI for any entity in Synapse (project, folder, dataset, file etc.). DOI support in Synapse was introduced early on and went through (at least one) revision and we have a dedicated API that allows users that have UPDATE permission on an entity to mint a DOI.
The ecosystem of Synapse expanded with the introduction of dissemination portals that are focused on specific research areas, examples are the https://adknowledgeportal.synapse.org/ and the https://cancercomplexity.synapse.org/. The portals are built on top of Synapse and expand the context in which an entity might be viewed by a data consumer, for example a study in the AD Knowledge Portal uses a Synapse entity folder to store its raw content and it is rendered in the portal with additional context (e.g. https://adknowledgeportal.synapse.org/Explore/Studies ).
The portals are central to the dissemination of knowledge and while Synapse is listed as a generalist repository by NIH (https://www.nlm.nih.gov/NIHbmic/generalist_repositories.html ), we now have at least two portals (ADKP and Cancer Complexity) that are listed as domain-specific repositories by NIH (https://www.nlm.nih.gov/NIHbmic/domain_specific_repositories.html ).
While the data is actually hosted in Synapse, the main way to present the data to the consumer should go through the selected domain-specific repositories. This implies that it should be possible to have DOIs that point to the dissemination portal resources. For example, to cite a study from ADKP we should be able to mint a DOI for the specific study in the ADKP, rather than the underlying synapse folder that the study uses as part of its representation.
Requirements
It should be possible for a Portal administrator to mind a DOI that points to a portal resource directly from the Portal
We only support portal resources that rely on a Synapse entity. For example, Studies, Grants etc; Example of resources that might not be represented by a synapse entity are Portal Programs, Projects and Publications).
Existing DOIs that already point to the Synapse.org landing page do not need to be updated to point to a Portal
A DOI minted from a portal can have its own publisher, currently we hardcode the Synapse publisher that is registered in the https://ror.org/.
Existing API
The existing DOI API uses an async job to mint or update a DOI, the request body has a doi property defined with the following properties:
"properties": {
"creators": {
"type": "array",
"items": {
"$ref": "#/components/schemas/org.sagebionetworks.repo.model.doi.v2.DoiCreator",
"description": "JSON schema for DOI Metadata Creator."
},
"description": "Required. The main researchers involved in producing the data, or the authors of the publication, in priority order."
},
"titles": {
"type": "array",
"items": {
"$ref": "#/components/schemas/org.sagebionetworks.repo.model.doi.v2.DoiTitle",
"description": "JSON schema for DOI Metadata Title."
},
"description": "Required. A name or title by which a resource is known."
},
"publicationYear": {
"type": "integer",
"format": "int32"
},
"resourceType": {
"$ref": "#/components/schemas/org.sagebionetworks.repo.model.doi.v2.DoiResourceType",
"description": "Required. Describes the type of media that the DOI Metadata refers to."
},
"associationId": {"type": "string"},
"etag": {"type": "string"},
"doiUri": {"type": "string"},
"doiUrl": {"type": "string"},
"objectId": {"type": "string"},
"objectType": {"type": "string"},
"objectVersion": {
"type": "integer",
"format": "int32"
},
"associatedBy": {"type": "string"},
"associatedOn": {"type": "string"},
"updatedBy": {"type": "string"},
"updatedOn": {"type": "string"}
}
An example of minted DOI is as follows:
URI: 10.5072/syn123.2
URL: https://repo-prod.prod.sagebase.org/repo/v1/doi/locate?id=syn123&version=2&type=ENTITY
Note that the URL for the DOI points to the synapse backend API and on a GET request will issue a redirect to:
https://www.synapse.org/#!Synapse:123/version/2
In simple terms the API takes in input the synapse entity id (and optional version) plus the DOI metadata and creates a handler that points to the backend /locate API with the necessary parameters to resolve the entity page in the Synapse.org portal.
Proposed API Changes
In order to support the portals scenario, we propose to introduce a new set of APIs to manage a portal, a Portal object will have its own ACL.
Portals API:
URL | Request | Response | Description |
|---|---|---|---|
POST /portals | Register a new Portal with Synapse, only synapse administrators can invoke this API. The user will be automatically assigned all the ACL for the portal (update, permissions etc). | ||
PUT /portals/{id} | Updates the metadata of the portal with the id in the path. Only users with UPDATE permissions are allowed to perform this operation. | ||
GET /portals? | Allows to fetch a page of portals, any user can invoke this operation. We might want to add filters by url, or name. | ||
GET /portals/{id} | Fetches a portal with the id in the path. Any user can invoke this operation | ||
GET /portals/{id}/acl | Fetches the ACL for the portal with the id in the path. An ACL will always exist for a portal. | ||
PUT /portals/{id}/acl | Updates the ACL for the portal with the id in the path. Only users with CHANGE_PERMISSIONS permission can update the ACL. |
Models:
Portal
{
"description": "JSON schema for a Synapse Portal.",
"properties": {
"id": {
"description": "The unique ID issued for this Portal. Generated by Synapse",
"type": "integer"
},
"etag": {
"type": "string",
"description": "For Optimistic Concurrency Control (OCC)."
},
"name": {
"description": "The name of the portal, must be unique.",
"type": "string"
},
"url": {
"description": "The base URL of the portal, must be unique.",
"type": "string"
},
"createdBy": {
"description": "The ID of the user that created the portal.",
"type": "string"
},
"createdOn": {
"type": "string",
"format": "date-time",
"description": "The date time this Portal was first created"
},
"updatedBy": {
"description": "The ID of the user that updated the portal.",
"type": "string"
},
"updatedOn": {
"type": "string",
"format": "date-time",
"description": "The date time this POrtal was last updated."
}
}
}
CreateOrUpdatePortalRequest
{
"description": "JSON schema for a request to create or update a Portal.",
"properties": {
"etag": {
"type": "string",
"description": "For Optimistic Concurrency Control (OCC)."
},
"name": {
"description": "The name of the portal, must be unique.",
"type": "string"
},
"url": {
"description": "The base URL of the portal, must be unique.",
"type": "string"
}
}
}
ListPortalPageResponse
{
"description": "JSON schema for a list of Portals",
"properties": {
"page": {
"type": "array",
"description": "A page of portals that match the request filters.",
"items": {
"$ref": "org.sagebionetworks.repo.model.portals.Portal"
}
},
"nextPageToken": {
"type": "string",
"description": "Forward this token to get the next page of results."
}
}
}
DOI API
In order to support a portal in the DOI API operations we can introduce a new portalId property in all the models and API parameters that are used throughout the API, this allows to specify a portal that the DOI operation refers to. For backward compatibility if a portalId parameter is omitted the backend treats it as if referring to the default Synapse.org portal.
Additionally, we need to introduce a new URI scheme for DOIs that are minted for a portal, currently minting a DOI for an entity references the synapse id:
DOI URI: 10.5072/syn123.2
DOI URL: https://repo-prod.prod.sagebase.org/repo/v1/doi/locate?id=syn123&version=2&type=ENTITY
When minting a DOI for a synapse entity in a portal we can build a DOI that looks like the following:
DOI URI: 10.5072/p456-syn123.2
The locate API would read the association with the given portal id and issue a redirect to a URL crafted for the specific portal.
For example, if the portal 456 URL is https://adknowledgeportal.synapse.org/ and the DOI for 10.5072/p456-syn123.2 was registered with the portalResourceType=STUDY then a potential URL could be:
https://adknowledgeportal.synapse.org/doi?resourceType=STUDY&id=syn123.2
This allows the portal to locate the right page.
We might consider randomly generating a DOI URI suffix going forward rather than referencing the portal id and syn id.
DOI Association Model
A DOI Association is used when minting or updating a DOI, in particular it contains the reference to the entity id/version that the DOI is minted for, we add the optional portalId and portalResourceType properties. The portalId will become part of the primary key of the association. Note that a DOI for an entity in a portal can be associated at most with one resourceType.
{
"description": "All fields that associate a Synapse object with a DOI. The objectId and objectType are required to create or mint a DOI in all circumstances.",
"type":"object",
"properties": {
"associationId": {
"description": "The unique ID of this DOI stored in Synapse. Provided by Synapse.",
"type": "string"
},
"etag": {
"type": "string",
"description": "For Optimistic Concurrency Control (OCC). Required to successfully update a DOI."
},
"doiUri": {
"description": "The unique URI of this DOI to which the resource can be resolved. Provided by Synapse.",
"type": "string"
},
"doiUrl": {
"type": "string",
"description": "The DOI URL that will point to the Synapse object. Provided by Synapse."
},
"portalId": {
"description": "If present, the id of the portal the DOI is associated with.",
"type": "string"
},
"portalResourceType": {
"description": "If portalId is present this is required and defines the type of resource in the portal that objectId represents.",
"$ref": "org.sagebionetworks.repo.model.portals.PortalResourceType"
},
"objectId": {
"description": "Required. The ID of the digital object in Synapse for which this DOI is created.",
"type": "string"
},
"objectType": {
"description": "Required. The type of the digital object.",
"$ref": "org.sagebionetworks.repo.model.ObjectType"
},
"objectVersion": {
"description": "Optional. The version of the digital object. When null, the DOI is associated with the current version of the object.",
"type": "integer"
},
"associatedBy": {
"description": "The ID of the user that creates this DOI. Provided by Synapse.",
"type": "string"
},
"associatedOn": {
"type": "string",
"format": "date-time",
"description": "The date time this DOI is first created. Provided by Synapse."
},
"updatedBy": {
"description": "The ID of the user that last updated this DOI. Provided by Synapse.",
"type": "string"
},
"updatedOn": {
"type": "string",
"format": "date-time",
"description": "The date time this DOI is last updated. Provided by Synapse."
}
}
}
DataciteMetadata Model
We expose the publisher property, historically we minted DOIs using the Synapse publisher (registered in the research organization registry), but for a portal we will use the Portal.name property instead:
{
"description": "JSON schema for metadata that is submitted to DataCite and can later be retrieved via DOI in Synapse, with the DataCite REST API, or with external citation services.",
"type": "interface",
"properties": {
"creators":{
"type":"array",
"description":"Required. The main researchers involved in producing the data, or the authors of the publication, in priority order.",
"items":{
"$ref":"org.sagebionetworks.repo.model.doi.v2.DoiCreator"
}
},
"titles": {
"description": "Required. A name or title by which a resource is known.",
"type": "array",
"items": {
"$ref": "org.sagebionetworks.repo.model.doi.v2.DoiTitle"
}
},
"publicationYear": {
"description": "Required. The year that this resource became publicly accessible. Must be in YYYY format.",
"type": "integer"
},
"resourceType": {
"description": "Required. Describes the type of media that the DOI Metadata refers to.",
"$ref": "org.sagebionetworks.repo.model.doi.v2.DoiResourceType"
},
"publisher": {
"description": "The publisher of the DOI, for a portal DOI matches the Portal name",
"type": "string"
}
}
}
POST /doi/async/start
The DOI association model in the request will contain the optional portalId and portalResourceType properties as explained above. The only other change required for this API is that if a portalId is included the user invoking the operation needs to have CREATE permission on the portal with the given id. This allows to assign multiple users permissions to mint DOIs from a portal, without the users being able to edit the portal or portal ACL.
GET /doi/locate API
We add the portalId and portalResourceType parameters to the locate API that when present will trigger the resolution to the portal URL. If omitted will generate the current URL to the synapse.org portal.
GET /doi
We add the optional portalId parameter to the get API, so that the portal can fetch the DOI information. Note that this implies that for a single entity there might exist multiple DOIs. If omitted will fetch the DOI information for the synapse.org portal.
GET /doi/association
Similarly to the previous APIs, we add the optional portalId parameter to the get association API. If omitted will fetch the DOI association for the synapse.org portal.
Note: The GET /doi and /doi/association only allow to fetch a single DOI/Associations for an entity in the context of a portal or synapse.org, we might need a new set of API to fetch all the minted DOIs/Associations given just an entity since the current API is not compatible with a list of DOI/Associations. Note however that an entity bundle includes DOI association information (see below).
Entity Bundle API
The entity API bundle API can include in the response the DOI association, if includeDOIAssociation is set to true in the request body then the response will include a property doiAssociation with the potential DOI association information. To support the multiple DOIs we should include a new doiAssociations that is a list of all the DOI associations (the doiAssociation property will contain the Synapse.org association if any):
{
"description": "Bundle to transport an Entity and related data objects",
"properties": {
...
"doiAssociation": {
"description": "Contains the DOI association with Synapse.org if any."
"$ref": "org.sagebionetworks.repo.model.doi.v2.DoiAssociation"
},
"doiAssociations": {
"description": "All the DOI associations for the entity, including Synapse.org and any portal specific DOI."
"type": "array",
"items": {
"$ref": "org.sagebionetworks.repo.model.doi.v2.DoiAssociation"
}
},
...
}
}