<resource schema="voidoi">
	<meta name="title">VO in DOI</meta>
	<meta name="schema-rank">500</meta>
	<meta name="description">
		The services offered here allow the assignment of DOIs to VO
		resources; they also maintain the landing pages.
	</meta>
	<meta name="creationDate">2016-01-18T12:20:00</meta>

	<meta name="subject">DOI</meta>
	<meta name="subject">virtual-observatories</meta>

	<meta name="creator">Demleitner, M.</meta>

	<meta name="type">Other</meta>

	<!-- configuration -->
	<meta name="oai_endpoint">http://dc.g-vo.org/rr/q/pmh/pubreg.xml</meta>

	<meta name="_longdoc" format="rst">
		VOiDOI (“VO in DOI”) lets you mint a Digital Object Identifier
		for a registered VO service.

		Why would I want a DOI?
		-----------------------

		The main purpose of obtaining a DOI for a VO resource is to enhance
		its citability.  Many popular citation styles let you give DOIs, which in
		turn facilitates later identification of the service, even if the
		service's URL changes, the service is operated by a different data
		center, or the service disappears.

		The IVOID (the ivo-URI you get when registering with the VO) could, in
		principle, work almost as well for citation purposes, but few people know
		what to do with it, and few citation styles let you use IVOIDs
		meaningfully.  Also, the IVOID changes when the publisher changes; a DOI
		can remain constant (although VOiDOI right now doesn't support that yet;
		ask us if this becomes an issue for you).

		All DOIs are resolvable to “landing pages” (giving metadata and
		access options) when you prepend http://dx.doi.org/ to them; that is
		true for VOiDOI-generated DOIs as well.

		Current practice in the VO is to preferably cite a paper associated
		with a resource if there is such a paper.  Hence, VOiDOI is
		targeted mainly at services that either are not closely associated
		with a paper (e.g., observatory collections) or that collect data
		emerging from multiple papers (thing Simbad-like services).


		How do I operate VOiDOI?
		------------------------

		You first have to register your service.  Once your service has
		propagated from your publishing registry to the searchable
		registries (this may take up to a day), you can paste its IVOID (the
		URI starting with ivo:// you get with registration) into
		\RSTservicelink{voidoi/q/ui}{the registration service}.  The service
		will then send an e-mail with a registration URL to the contact
		address given in the registry record (in the ``contact/email``
		element).  Once you retrieve the URL, the service will tell you your
		new DOI.

		You should then include that DOI in citation advice, and also
		in an ``altIdentifier`` element in the registry record
		itself (in DaCHS, set a ``doi`` meta to do that).  Be sure to re-publish
		your service once you have added the DOI.

		What happens if my service dies?
		--------------------------------

		First, DOI minting is irreversible, and you should not obtain a DOI for
		a service you do not expect to be permanent.

		Still, bad things happen. If your service dies and the registry record
		goes away, VOiDOI will keep its metadata in a “tombstone”; this will
		include all existing metadata – technically, it is that metadata, the
		registry record, what the DOI really refers to –, and some notice what
		happened to the service as far as we know.

		Also, other VO resources can still reference the dead service in
		``relationship`` elements.  We hope that through the ``Continues``
		relationship, users can be pointed to resources taking up the data
		published if these exist.

		How do I register to the VO?
		----------------------------

		That's a longer story, and there are multiple answers.  See
		`getting into the Registry`_ on the IVOA wiki for details.

		.. _getting into the Registry: http://wiki.ivoa.net/twiki/bin/view/IVOA/GettingIntoTheRegistry
	</meta>

	<execute id="update" every="40000" 
		title="Fetch updated records" debug="False">
		<job>
			<doc>
				This pulls updated records from the registry and hands
				them on to datacite.
			</doc>
			<code>
				execDef.spawnPython("res/update_records.py")
			</code>
		</job>
	</execute>

	<table id="dois" onDisk="true" primary="ivoid"
			dupePolicy="overwrite">
		<meta name="description">
			Metadata for managing resource records for which we produced
			a DOI.
		</meta>
		<column name="ivoid" type="text"
			ucd="meta.id;meta.main"
			tablehead="IVOID"
			description="IVO identifier of the record in question"/>
		<column name="date_reg" type="timestamp"
			ucd="time.epoch"
			tablehead="Registred"
			description="Date/time on which registration was first performed (UTC)."/>
		<column name="doi" type="text"
			ucd="meta.id"
			tablehead="DOI"
			description="DOI assigned to IVOID using this service."/>
		<column name="full_record" type="unicode"
			tablehead="Registry record"
			description="The full registry record as it has last been
				harvested.  For deleted records this is the state of the last
				harvest before deletion."
			displayHint="type=ellipsis"/>
		<column name="last_confirmation_code" type="text"
			description="Last confirmation code sent out"
			displayHint="type=hidden"/>
	</table>

	<data id="nuke_them_all" auto="False">
		<make table="dois"/>
	</data>

	<service id="ui" allowed="custom,static"
			customPage="res/registration" defaultRenderer="custom">
		<publish render="custom" sets="local,ivo_managed"/>
		<property key="staticData">static</property>
		<meta name="shortName">DOI registration</meta>
		<meta name="title">VOiDOI DOI registration web service</meta>
		<meta name="description">This service lets VO data publishers
			assign Digital Object Identifiers to their services, greatly
			enhancing their citability.  Since technically, the DOI references
			the registry record, this service can only be used on properly
			registered services.
			</meta>
		<nullCore/>
	</service>

	<service id="lp" allowed="custom"
		customPage="res/landingpage">
		<meta name="shortName">DOI landingpage</meta>
		<meta name="title">VOiDOI landing page generator</meta>
		<nullCore/>
	</service>

	<regSuite id="voidoi basics">
		<regTest title="Voidoi invalid record has helpful hints">
			<url parSet="form" ivoid="ivo://org.gavo.dc/test/invalid"
				httpMethod="POST">ui/custom</url>
			<code><![CDATA[
				self.assertHasStrings("h2>Hints on fixing the problem",
					"<pre>&lt;string&gt;",
					"'description': This element is not expected",
					"Field ivoid: The resource record is invalid -- you need to fix it")
			]]></code>
		</regTest>

		<regTest title="Voidoi 404 landingpage">
			<url>lp/custom/10.0001/invalid</url>
			<code><![CDATA[
				self.assertEqual(self.status, 404)
				self.assertHasStrings("The DOI 10.0001/invalid is unknown here.</div>")
			]]></code>
		</regTest>
	</regSuite>

</resource>
