DataCite Metadata Schema Documentation for the Publication and Citation of Research Data v4.0

## Purpose The [DataCite Metadata Store (MDS) API](http://gfffhf21b47e3e1694172svvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/reference/mds) allows users to register DataCite DOIs and associated metadata. The API requires authentication. To retrieve DOI metadata records users should use our [DataCite REST API](doc:api). To become a member, interested parties should contact the [DataCite support](mailto:support@datacite.org) team. [DataCite Fabrica](http://gfffhf21b47e3e1694172svvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/docs/doi-fabrica) provides an alternative for registering DataCite DOIs via a web interface. ## Authentication All requests to the MDS API require authentication. For this reason, only traffic via a secure connection (HTTPS) is supported. The DataCite Metadata Store (MDS) uses [HTTP Basic authentication](http://gfffh5dbbc47d98c945ddsvvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/wiki/Basic_access_authentication). > 📘 To create DOIs with the MDS API, you will need: > - Repository account credentials or a corresponding [API key](doc:api-keys). Only Repository accounts have the ability to create and update DOIs. For more information on account types and permissions, see [Accounts in DataCite](docs:datacite-account-types). > - Prefix. The prefix associated with your Repository account must be included in the API request. The request will fail with an error message if the prefix used is not associated with your Repository ID. ## How to Use The DataCite Metadata Store (MDS) API can be used directly by making HTTP requests with packages such as [cURL](http://gfffh24f241c295ec447fsvvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/docs/manpage.html). Besides using the API directly there are a number of integrations with the MDS API that allow the creation of DataCite DOIs. Please review the documentation of the respective package for installation instructions. ## Fetch a DOI Let's start by testing our setup. In this guide, the examples we will use would employ the _MDS Production endpoint_ (i.e., ) We will use the curl command-line tool. ### Fetch the URL Now, open up a command prompt and enter the following command: ```shell $ curl --user username:password http://gfffh640e0b3ca5fb476asvvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/doi/10.5438/0012 http://gfffh3e046cd3d7394825svvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/meta/kernel-4.0/index.html% ``` The response will be the URL registered for the DOI you requested. > 🚧 Warning > > If you got a wrong credentials error when retrieving the example DOI 10.5438/0012. Use a DOI name that belongs to your organization. ### Fetch the metadata Next, let's register the metadata associated with the DOI: ```shell # GET /metadata/doi $ curl --user username:password http://gfffh640e0b3ca5fb476asvvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/metadata/10.5438/0012 ``` ```xml 10.5438/0012 DataCite Metadata Working Group DataCite Metadata Schema Documentation for the Publication and Citation of Research Data v4.0 DataCite e.V. 2016 Starr, Joan Joan Starr 0000-0002-7285-027X California Digital Library Smaele, Madeleine de Madeleine de Smaele TU Delft Ashton, Jan Jan Ashton British Library Barton, Amy Amy Barton Purdue University Library Bradford, Tina Tina Bradford NRC/CISTI Ciolek‐Figiel, Anne Anne Ciolek-Figiel Inist‐CNRS Dietiker, Stefanie Stefanie Dietiker ETH Zürich Elliott, Jannean Jannean Elliot DOE/OSTI Genat, Berrit Berrit Genat TIB Harzenetter, Karoline Karoline Harzenetter GESIS Hirschmann, Barbara Barbara Hirschmann 0000-0003-0289-0345 ETH Zürich Jakobsson, Stefan Stefan Jakobsson SND Mailloux, Jean‐Yves Jean-Yves Mailloux NRC/CISTI Newbold, Elizabeth Elizabeth Newbold 0000-0002-8255-9013 British Library Nielsen, Lars Holm Lars Holm Nielsen 0000-0001-8135-3489 CERN Yahia, Mohamed Mohamed Yahia Inist-CNRS Ziedorn, Frauke Frauke Ziedorn 0000-0002-1143-781X TIB eng Documentation 10.5438/0013 10.5438/0010 45 pages application/pdf 4.0 1 Introduction
1.1 The DataCite Consortium
1.2 DataCite Community Participation
1.3 The Metadata Schema
1.4 Version 4.0 Update
2 DataCite Metadata Properties
2.1 Overview
2.2 Citation
2.3 DataCite Properties
3 XML Example
4 XML Schema
5 Other DataCite Services
Appendices
Appendix 1: Controlled List Definitions
Appendix 2: Earlier Version Update Notes ``` The response is metadata in DataCite XML format. Let's add the `-i` flag to include headers: ```shell # GET /metadata/doi $ curl --user username:password http://gfffh640e0b3ca5fb476asvvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/metadata/10.5438/0012 -i ``` ```shell HTTP/2 200 date: Mon, 06 Aug 2018 17:43:48 GMT content-type: application/xml; charset=utf-8 status: 200 OK cache-control: max-age=0, private, must-revalidate vary: Accept-Encoding, Origin etag: W/"3122a5d037aa7b46e5e9c60de67b6459" x-runtime: 0.053340 x-credential-username: xxx x-request-id: cb98f390-d65c-4b16-b7d4-7bb84e37bc22 x-powered-by: Phusion Passenger 5.3.4 server: nginx/1.14.0 + Phusion Passenger 5.3.4 ). An example of a DOI name would be `10.5438/0012`. If you don't want to pick a DOI name, the MDS API can generate a random DOI name for you. For details see below in section [Auto-generated DOI names](#section-auto-generated-doi-names). ### Register metadata To add metadata to a DOI, we need to `PUT` XML containing the metadata conforming to the [DataCite Metadata Schema](http://gfffh3e046cd3d7394825hvvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn). There you will find the preferred version and example XML documents. Please remember that all your documents must specify the correct schema location in the root element. > 📘 Metadata in other formats can also be registered via the MDS API. These formats include: > > - RIS > - BibTeX > - Schema.org (as JSON-LD or URL pointing to a web page with embedded schema.org) > - Citeproc JSON > - Codemeta > - Crossref XML The `identifier` in the DataCite XML metadata file can be left empty, as the value from the `PUT URL` will be used. The content type for the request must be `application/xml`. > 📘 Validating metadata > > The metadata you submit must include all of the mandatory metadata properties as outlined in the [DataCite Metadata Schema](http://gfffh3e046cd3d7394825hvvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn). The validation for MDS does not allow creation of drafts with no, incomplete, or invalid metadata. ```shell # PUT /metadata/10.5438/JQX3-61AT $ curl -H "Content-Type: application/xml;charset=UTF-8" -X PUT -i --user username:password -d @10.5438/JQX3-61AT.xml http://gfffh7bbab62299b040d2svvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/metadata/10.5438/JQX3-61AT ``` The response to this call will return a short explanation of status code e.g. CREATED, HANDLE_ALREADY_EXISTS etc. The response status can be one of: - `201 Created`: operation successful, - `401 Unauthorised`: no login, - `403 Forbidden`: login problem, , wrong prefix, - `415 Wrong Content Type`: Not including the correct content type in the header. - `422 Unprocessable Entity`: invalid XML Once you have created the record, you can fetch the metadata record as described earlier in this guide. ### Register the URL The next step is to register the DOI name and associated URL. We can `PUT` DOIs in a similar way to how we fetched DOI details earlier. A file with the DOI name for the new resource and the URL where the resource is located needs to be provided. Please note that the new lines specified in the payload are important to ensure whichever method you use keeps them intact. You can use the newline character (\\n) instead. ```text #Content-Type:text/plain;charset=UTF-8 doi= 10.5438/JQX3-61AT url= http://gfffha9a5e6af900343e1hvvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/ ``` ```shell # PUT /doi $ curl -H "Content-Type:text/plain;charset=UTF-8" -X PUT --user username:password -d "$(printf 'doi=10.5438/JQX3-61AT\nurl=http://gfffha9a5e6af900343e1hvvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/')" http://gfffh7bbab62299b040d2svvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/doi/10.5438/JQX3-61AT ``` This method will attempt to update the URL if you specify a DOI with an existing URL, otherwise, the DOI will be registered in the handle system, and will resolve via . The response is a short explanation of status code (e.g. CREATED, HANDLE_ALREADY_EXISTS etc). The response status can be one of: - `201 Created`: operation successful; - `400 Bad Request`: request body must be exactly two lines: DOI and URL; wrong domain, wrong prefix; - `401 Unauthorised`: no login; - `403 Forbidden`: login problem; - `412 Precondition failed`: metadata must be uploaded first. In the same way, we can fetch the URL for the DOI we just registered. There is a small delay (usually a few minutes) before a newly registered DOI becomes visible in the handle system. ```shell $ curl -X GET --user username:password http://gfffh7bbab62299b040d2svvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/doi/10.5438/JQX3-61AT http://gfffhbcd5f1a17ab241c4svvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/10.5438/JQX3-61AT ``` Now you know the basics of the DataCite Metadata Store (MDS) API. You learned: - Basic authentication - Fetching and registering DOI names and metadata records. - Register DOIs and metadata Keep learning with the [API Live Reference](http://gfffhf21b47e3e1694172svvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/reference/overview) where you can make requests directly to the MDS test service. ## Auto-generated DOI names If you want DataCite to generate a random DOI name for you, provide only the prefix when you register metadata: ```shell # PUT /metadata/10.5438 $ curl -H "Content-Type: application/xml;charset=UTF-8" -X PUT -i --user username:password -d @10.5438/JQX3-61AT.xml http://gfffh7bbab62299b040d2svvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/metadata/10.5438 ``` This will register metadata with a random DOI using the prefix you indicated (which in the above example is 10.5438). The DOI in the metadata file will be overwritten and can therefore be left empty. ## DOI States DOIs can exist in three states: **draft**, **registered**, and **findable**. The **draft** state is when metadata have been registered but are not public facing and will transition to the **findable** state when registering a URL. Findable DOIs can be transitioned to the **registered** state (the metadata are no longer included in the search index) using this command: ```shell # DELETE /metadata/10.5438/JQX3-61AT $ curl -H "Content-Type: application/plain;charset=UTF-8" -X DELETE -i --user username:password http://gfffh7bbab62299b040d2svvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/metadata/10.5438/JQX3-61AT ``` Send another `PUT /metadata` request to transition the DOI back to the **findable** state. Drafts can be deleted using this command: ```shell # DELETE /doi/10.5438/JQX3-61AT $ curl -H "Content-Type: application/plain;charset=UTF-8" -X DELETE -i --user username:password http://gfffh7bbab62299b040d2svvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/doi/10.5438/JQX3-61AT ``` Find out more about DOI states [here](http://gfffhf21b47e3e1694172svvfuxqfx6ppb6n9w.ffgi.yc2.bjmu.edu.cn/docs/doi-states). > 📘 Would you like to know more? > > If you have any questions, requests or ideas please [contact us!](doc:how-to-contact-datacite)