Content Comparison

...

It should be possible for a Portal administrator to 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/.

...

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

DOI URL: https://repo-prod.prod.sagebase.orgGiven 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.syn123

The locate API backend 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 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?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": "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": "ForThe unique OptimisticID Concurrencyof Control (OCC). Required to successfully update a DOI."
		},
		"doiUri": {
			"description": "The unique URI of this DOI to which the resource can be resolvedthis 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 of the portal the DOI is associated withThe unique URI of this DOI to which the resource can be resolved. Provided by Synapse.",
			"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."
		},
		"objectIdportalId": {
			"description": "Required.If The IDpresent, the id of the digital object in Synapse for which thisportal the DOI is associated createdwith.",
			"type": "string"
		},
		"objectTypeobjectId": {
			"description": "Required. The typeID 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 in for which this DOI is created. When a portalId is supplied it is treated as an opaque identifier for the portal resource.",
			"type": "integerstring"
		},
		"associatedByobjectType": {
			"description": "Required. The IDtype of the user that creates this DOI. Provided by Synapse.",
digital object. If a portalId is supplied this can only be PORTAL_RESOURCE.",
			"type$ref": "stringorg.sagebionetworks.repo.model.doi.v2.ObjectType"
		},
		"associatedOnobjectVersion": {
			"typedescription": "string",
			"format": "date-time",
			"description": "The date time this DOI is first created. Provided by Synapse."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"
		},
		"updatedByassociatedBy": {
			"description": "The ID of the user that last updatedcreates this DOI. Provided by Synapse.",
			"type": "string"
		},
		"updatedOnassociatedOn": {
			"type": "string",
			"format": "date-time",
			"description": "The date time this DOI is lastfirst updatedcreated. 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:

Code Block

language	json

{
		"updatedBy": {
			"description": "JSONThe ID schemaof forthe metadatauser that islast submittedupdated tothis DataCiteDOI. and can later be retrieved via DOI in Synapse, with the DataCite REST API, or with external citation servicesProvided by Synapse.",
			"type": "interfacestring"
		},
		"propertiesupdatedOn": {
			"creatorstype":{ "string",
			"typeformat": "arraydate-time",
			"description": "Required. The maindate researcherstime involvedthis inDOI producingis thelast data,updated. orProvided the authors of the publication, in priority orderby Synapse.",
			"items":{
				"$ref":"org.sagebionetworks.repo.model.doi.v2.DoiCreator"
		}
	}
		},
		"titles": {
			}

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:

Code Block

language	json

{
	"description": "Required.JSON Aschema namefor ormetadata titlethat byis whichsubmitted ato resourceDataCite is knownand can later be retrieved via DOI in Synapse, with the DataCite REST API, or with external citation services.",
			"type": "arrayinterface",
	"properties": {
		"itemscreators": {
				"$reftype": "org.sagebionetworks.repo.model.doi.v2.DoiTitle""array",
			}
		},
		"publicationYear": {
			""description": "Required. The year that this resource became publicly accessible. Must be in YYYY format main researchers involved in producing the data, or the authors of the publication, in priority order.",
			"typeitems":{
"integer"
		},
		"resourceType$ref": {
			"description": "Required. Describes the type of media that the DOI Metadata refers to.",
			"$ref": "org.sagebionetworks.repo.model.doi.v2.DoiResourceTypeDoiCreator"
			}
		},
		"publishertitles": {
			"description": "The publisher of the DOI, forRequired. A name or title by which a portalresource DOI matches the Portal name",
is known.",
			"type": "array",
			"items": {
				"type$ref": "stringorg.sagebionetworks.repo.model.doi.v2.DoiTitle"
			}
		}
}

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):

Code Block

language	json

{
	"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"
			}
		},
		...
	}
},
		"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 allow the optional portalId property as explained above. The only other change required for this API is that if a 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 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, 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 5	New Version Current
Changes made by	John Hill	Marco Marasca
Saved on	Feb 06, 2025	Feb 17, 2025

Versions Compared

Key

DOI Association Model

DataciteMetadata Model

DataciteMetadata Model

POST /doi/async/start

GET /doi/locate API

GET /doi

GET /doi/association

Entity Bundle API

POST /doi/async/start

GET /doi/locate API

GET /doi

GET /doi/association