Content Comparison

...

It should be possible for a Portal administrator to mind mint 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). ← We decided to remove this constraint since the link between a portal resource and a Synapse entity is just an artifact and not always followed (e.g. some resources do not have a specific entity representation)
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/.

...

URL	Request	Response	Description
POST /portals	CreateOrUpdatePortalRequest	Portal	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}	CreateOrUpdatePortalRequest	Portal	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?		ListPortalPageResponse	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}		Portal	Fetches a portal with the id in the path. Any user can invoke this operation
GET /portals/{id}/acl		AccessControlList	Fetches the ACL for the portal with the id in the path. An ACL will always exist for a portal. Any user can invoke this operation.
PUT /portals/{id}/acl	AccessControlList	AccessControlList	Updates the ACL for the portal with the id in the path. Only users with CHANGE_PERMISSIONS permission can update the ACL.

...

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 will treat it as if referring to the default Synapse.org portal and will have a special bootstrapped internal value (e.g. 1).

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 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.2Given that for each minted DOI we generate a unique identifier (the associationId), going forward we will be using that id instead which is opaque and not bound to a specific entity or portal.

For example, suppose that portal 456 points to https://portal.synapse.org and we want to mint a DOI for STUDY syn123, the client would issue a request with portalId=456 and objectId=STUDY.syn123 (note that the objectId is opaque to synapse for a portal) and the DOI would look like:

DOI URI: 10.5072/1234567

DOI URL: https://repo-prod.prod.sagebase.org/repo/v1/doi/locate?portalId=456&portalResourceTypeid=STUDY&id=syn123&version=2&type=ENTITY

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

The backend would resolve the URL above to:

https://adknowledgeportalportal.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 doi?id=STUDY.syn123

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 propertiesproperty. The portalId will become part of the primary unique key of the association. Note that a DOI for an entity in a portal can be associated at most with one resourceType.

...

language	json

when a portalId is supplied the objectId is treated as an opaque identifier and the objectType will be PORTAL_RESOURCE. Additionally, the objectVersion is ignored.

Additionally, we change the objectType enumeration from https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/ObjectType.html to a dedicated https://rest-docs.synapse.org/rest/org/sagebionetworks/repo/model/doi/v2/DoiObjectType.html that will have as possible values ENTITY or PORTAL_RESOURCE.

Code Block

language	json

{
	"description": "TheAll uniquefields IDthat of this DOI stored inassociate a Synapse. Provided by Synapse.",
			"type": "string"
		},
		"etag": {
			"type": "string",
			"description": "For Optimistic Concurrency Control (OCC). Required to successfully update a DOI."
		},
		"doiUriobject 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 URIID of this DOI to which the resource can be resolved DOI stored in Synapse. Provided by Synapse.",
			"type": "string"
		},
		"doiUrletag": {
			"type": "string",
			"description": "TheFor DOIOptimistic URLConcurrency that will pointControl (OCC). Required to thesuccessfully Synapseupdate object.  Provided by Synapsea DOI."
		},
		"portalIddoiUri": {
			"description": "If present, the id ofThe unique URI of this DOI to which the portalresource can thebe DOIresolved. isProvided associatedby withSynapse.",
			"type": "string"
		},
		"portalResourceTypedoiUrl": {
			"descriptiontype": "string"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,
			"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"
		},
		"objectId": {
			"description": "Required. The ID of the digital object in Synapse for which this DOI is created. When a portalId is supplied it is treated as an opaque identifier for whichthe this DOI is createdportal resource.",
			"type": "string"
		},
		"objectType": {
			"description": "Required. The type of the digital object. If a portalId is supplied this can only be PORTAL_RESOURCE.",
			"$ref": "org.sagebionetworks.repo.model.doi.v2.ObjectType"
		},
		"objectVersion": {
			"description": "Optional. The version of the digital object. When null, the DOI is associated with the current version of the object. If portalId is supplied this value is ignored.",
			"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."
		}
	}
}

...

The DOI association model in the request will contain allow the optional portalId and portalResourceType properties property as explained above. The only other change required for this API is that if a portalId is included portalId is included and it is different than the internal Synapse portal id, 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

...

doi

We add the optional portalId parameter to the get association API. If omitted will API, so that the portal can 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. It is not clear if the portal DOIs should be shown on synapse.orginformation, in this case the only value allowed for the type parameter is PORTAL_RESOURCE. If portalId is 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.

Version	Old Version 2	New Version Current
Changes made by	Marco Marasca	Marco Marasca
Saved on	Feb 05, 2025	Feb 17, 2025

Versions Compared

Key

DOI Association Model

DOI Association Model

GET /doi/locate API

GET /doi

GET /doi/association

doi

GET /doi/association