IAD API Documentation: Introduction

The IAD API allows users to register DOIs for data sets, collections, and other resources through DataCite, as well as query various previous submissions for status of the process.

The API is built on a REST architecture, providing predictable URLs that make writing applications easy. The API is HTTP-based, so it can be accessed using a wide variety of clients; most examples are illustrated using the cURL command to demonstrate basic use cases.

The list of resources available through the API, and their corresponding reference documentation, will always be made available at the API documentation endpoint (this document).

API Documentation Endpoint

https://www.osti.gov/iad2/docs

General Guidelines

Each resource endpoint in the API will vary slightly in some respects, such as what query parameters are valid for that type of request and how the expected output may be structured. These variations will be outlined in detail in the resource-specific sections below. There are, however, some general rules and expectations that are common to all interactions with the API.

Note that all interactions with the IAD API utilize basic HTTP authentication in order to identify the requesting user. Each IAD user is assigned a specific user ("login") name and password that should be used in all such requests.

HTTP Methods

The IAD API uses the HTTP verb (method) associated with the incoming request to identify the type of action being performed.

Request Methods
Method Description
GET Used for retrieving resources.
POST Used to send records in various formats for both new submissions and editing existing submissions. Since IAD API takes a mixture of update and new record submissions in the same submission, the POST verb is used for both such interactions.
PUT Used for updating resources.
Not currently valid for IAD API resource requests
DELETE Used by IAD for marking existing, registered DOIs as "inactive", meaning such DOIs should no longer resolve or be marked as unavailable.

Using the GET method, records may be retrieved as a list, filtered or complete sets, or particular single resources may be requested. Lists are generally returned a page at a time, with starting record offset and number of desired records configured in the request's query parameters ("start" and "rows" respectively). If no information is supplied, the first page of up to 25 records is assumed. Additionally, users may specify a "filter" query parameter containing desired specific record information.

To get a list of all records, a page at a time: (via basic HTTP authentication)

$ curl -u LOGINNAME https://www.osti.gov/iad2/api/records

To get details of a specific record by its unique ID:

$ curl -u LOGINNAME https://www.osti.gov/iad2/api/records/{id}

Response Formats

By default, results from the IAD API will be returned in JSON format. By specifying an expected mime type in the Accept header of the request, results can also be returned in JSON or XML.

Format Types and Accept Headers
Format Accept header
JSON application/json
XML application/xml

Specifying the Accept header in the request, you can retrieve results in a particular format.

To get a record's metadata in JSON format:

$ curl https://www.osti.gov/iad2/api/records/{id} \
	-H 'Accept: application/json'

To get a record's metadata in XML format:

$ curl https://www.osti.gov/iad2/api/records/{id} \
	-H 'Accept: application/xml'

Response Headers

Responses from the API will include certain common HTTP headers, providing details about the response or the included content.

Common Response Headers
Response Header Description
Date The date the response is issued, in RFC 1123 format
Content-Type The mime type in which the response data is formatted
X-Total-Count For reponses containing data, the number of records returned in the current response
Link If more matching records are available than are returned in the current response, this will contain links to more pages in RFC 5988 format

Example Response Headers

HTTP/1.1 200 OK

Date: Thu, 26 May 2016 16:25:04 GMT
Content-Type: application/json
X-Total-Count: 50
Link: <https://www.osti.gov/iad2/api/records?start=25>; rel="next", <https://www.osti.gov/iad2/api/records?start=25>; rel="last"
Content-Length: 3911

Pagination

Requests that return multiple records will be paginated to 25 records by default; the number of records per page can be modified by specifying a numerical value for the ?rows parameter, and the starting row number (from 0) with the ?start parameter (default 0). If more matching records exist, the Link response header will contain links to additional pages of data, in RFC 5988 format. The specific type of link is denoted by the "rel" value.

Link Header Rel Values
Name Description
next The link relation for the immediate next page of results
last The link relation for the last page of results
first The link relation for the last page of results
prev The link relation for the immediate previous page of results

Example Link Header Values


$ curl https://www.osti.gov/iad2/api/records?rows=20

HTTP/1.1 200 OK

...
X-Total-Count: 250
Link:
<https://www.osti.gov/iad2/api/records?start=20&rows=20>; rel="next",
<https://www.osti.gov/iad2/api/records?start=230&rows=20>; rel="last",
<https://www.osti.gov/iad2/api/records?start=0&rows=20>; rel="first",
<https://www.osti.gov/iad2/api/records?start=0&rows=20>; rel="prev"
...

Record Model

Responses returning data all return the same basic structure, formatted as appropriate for the content type requested. Fields indicated in red text are minimum required fields for data submissions.

Record Fields

Results are always presented as a list of Record objects, formatted according to the content type requested. For JSON, records are returned as an array of objects as "records", with "start" and "total" attributes representing the pagination information. For XML, records are returned as <record> elements with a "status" attribute, wrapped in a <records> container containing "start" and "total" as attributes.

Record Fields
Field Name Description
idThe unique identifier for the record (used for updates on submission)
accession_numberThe unique designation for the user's own reference to this content
titleA name or title by which the record is known
authorsContains a listing of person(s) responsible for the content, as object references.
site_codeThe site code assigned to the user account for grouping content.
descriptionA short description or abstract
publisherThe name of the entity that holds, archives, distributes, releases, or produces the resource
countryThe country in which this version of the record was published
publication_dateThe publication date
date_record_addedThe date the record was added
date_record_updatedThe date the record was last updated
date_first_registeredThe date the DOI was first minted, if present
date_last_registeredThe date the DOI was last updated, if present
doiThe Digital Object Identifier (DOI)
doi_infixOptional infix value used for unique DOI construction
site_urlThe URL containing the record content, which the DOI will redirect to
product_typeThe product type; usually one of "Dataset", "Text", or "Collection"
product_type_specificA short description of the record content type, or type of data
keywordsA listing of broad topics applying to the data or its subject matter
languageThe primary language of the resource
availabilityIf applicable, the office or organization to refer access requests to
research_organizationIf credited, the organization name that performed the research
sponsoring_organizationIf credited, the organzation name that sponsored / funded the research
contributorsContains a listing of persons or organizations that contributed to the content
related_identifiersContains a listing of related identifiers; usually DOIs or URLs related to the content in some specified manner
report_numbersThe report number associated with the entry
contract_numbersAny contract or funding numbers associated with this record
other_numbersAny additional identifying numbers associated with this record
doi_messageIf present, the error condition of the last failed DOI submission

Records may contain arrays of Author and/or Contributor information; in JSON, these are object arrays defined below. In XML format, these are returned as <author> or <contributor>elements wrapped in <authors> or <contributors> containers, respectively.

Author/Contributor Fields
Field Name Description
first_nameA person's first, or given, name
middle_nameA person's middle name or initial, if present
last_nameA person's last, or family, name
full_nameFor organizations, the listed name or description of the organization
orcidThe ORCID of this author/contributor, if any
emailA contact email address
affiliationsContains a listing of any affiliations for this author/contributor
contributor_type(Contributors only)The type of contribution made by this contributor

Records may contain arrays of related identifier information; in JSON, these are object arrays defined below. In XML format, these are returned as <related_identifier> elements wrapped in a <related_identifiers> container.

Related Identifier Fields
Field Name Description
identifier_valueThe DOI or URL value of the related identifier
identifier_typeOne of "DOI" or "URL" to identify the type of content
relation_typeOne of the recognized relation types description this identifier's relation to the record

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
{
    "records": [{
        "id": "221299",
        "title": "This is a test example of metadata",
        "description": "This is a document example containing all the relevant information fields for metadata.",
        "authors": [
            { "first_name":"Mister",
              "middle_name":"X.",
              "last_name":"Ample",
              "email":"just.a.test@someplace.com",
              "affiliations":[]
            },
            { "first_name":"Another",
              "last_name":"Guy",
              "email":"aguy@someplace.com",
              "orcid":"0000-0001-2222-5555",
              "affiliations":["ACME", "Testing Solutions, Inc."]
            }
        ],
        "contributors": [
            { "full_name":"Contributing Editors, Inc.",
              "contributor_type":"Editor",
              "affiliations":[] 
            }
        ],
        "doi": "10.5072/for-example-purposes/221299",
        "doi_infix":"for-example-purposes",
        "publisher": "ACME Examples, Inc., LLC",
        "country": "US",
        "product_type": "Dataset",
        "product_type_specific":"Short description of data specifics",
        "language": "English",
        "publication_date": "2017-11-02",
        "date_added":"2017-11-27",
        "date_updated":"2017-11-27",
        "sponsoring_organization":"US DOE",
        "research_organization":"Research Associates Corp.",
        "report_numbers": "98776",
        "contract_numbers": "DE-39043-2017",
        "other_numbers":"OtherIdentifyingNumbers",
        "availability": "Check with publisher website for document availability",
        "keywords":"Example, computer programs, FAQ",
        "related_identifiers": [
            { "identifier_value":"10.5072/23432",
              "identifier_type":"DOI",
              "relation_type":"Cites"
            }
        ]
    }],
    "start":0,
    "total":1
}
HTTP/1.1 200 OK
Content-Type: application/xml
<?xml version="1.0"?>
<records start="0" total="1">
    <record status="Pending">
        <id>221299</id>
        <site_code>TEST</site_code>
        <title>This is a test example of metadata</title>
        <sponsoring_organization>US DOE</sponsoring_organization>
        <research_organization>Research Associates Corp.</research_organization>
        <accession_number>AC2045</accession_number>
        <doi_infix>for-example-purposes</doi_infix>
        <doi>10.5072/for-example-purposes/221299</doi>
        <report_numbers>98776</report_numbers>
        <contract_numbers>DE-39043-2017</contract_numbers>
        <other_numbers>OtherIdentifyingNumbers</other_numbers>
        <publisher>ACME Examples, Inc., LLC</publisher>
        <availability>Check with publisher website for document availability</availability>
        <publication_date>2017-11-02</publication_date>
        <country>US</country>
        <description>This is a document example containing all the relevant information fields for metadata.</description>
        <site_url>http://example.domain.com/example.pdf</site_url>
        <product_type>Dataset</product_type>
        <product_type_specific>Short description of data specifics</product_type_specific>
        <date_record_added>2017-11-27</date_record_added>
        <date_record_updated>2017-11-27</date_record_updated>
        <keywords>Example, computer programs, FAQ</keywords>
        <authors>
          <author>
            <email>just.a.test@someplace.com</email>
            <first_name>Mister</first_name>
            <last_name>Ample</last_name>
            <middle_name>X.</middle_name>
            <affiliations/>
          </author>
          <author>
            <email>aguy@someplace.com</email>
            <orcid>0000-0001-2222-5555</orcid>
            <first_name>Another</first_name>
            <last_name>Guy</last_name>
            <affiliations>
              <affiliation>ACME</affiliation>
              <affiliation>Testing Solutions, Inc.</affiliation>
            </affiliations>
          </author>
        </authors>
        <contributors>
          <contributor>
            <full_name>Contributing Editors, Inc.</full_name>
            <contributor_type>Editor</contributor_type>
            <affiliations/>
          </contributor>
        </contributors>
        <related_identifiers>
          <related_identifier>
            <identifier_type>DOI</identifier_type>
            <identifier_value>10.5072/23432</identifier_value>
            <relation_type>Cites</relation_type>
          </related_identifier>
        </related_identifiers>
    </record>
</records>

Error Model

If for some reason the API returns an error response, it will be formatted as appropriate for the content type requested. All error responses have the same basic structure.

HTTP Status Codes

Errors will be returned with an HTTP error status code appropriate to the type of error encountered.

HTTP Error Status
Status Description
400 Bad request
Usually indicates a bad parameter or data was supplied with the request.
401 Unauthorized
Indicates that HTTP authentication is required to access.
403 Forbidden
Insufficient access for the requested operation.
404 Resource Not Found
ID or other resource is not on file.
405 Method Not Allowed
Requested method type is not available.
500 Internal Error
An internal service error has occurred.

Error Fields

Errors are always presented as a single object, formatted according to the content type requested.

Error Fields
Field Name Description
statusThe response error code, duplicated for convenience
errorsAn array containing more detailed descriptions of the specific error

Example Error

HTTP/1.1 404 Not Found
Content-Type: application/json
{
    "status": 404,
    "errors":["ID is not on file."]
}
HTTP/1.1 404 Not Found
Content-Type: application/xml
<?xml version="1.0"?>
<error_response>
    <status>404</status>
    <errors>
        <error>
        ID is not on file.
        </error>
    </errors>
</error_response>

Endpoints

The IAD API supports various endpoints, both for data retrieval via GET requests, and registration and updating of record information via POST requests.

API Root Endpoint

https://www.osti.gov/iad2/api/

Record List (Search)

GET /records

The record list endpoint allows you to search for lists of records in IAD by a variety of criteria via the filter options. Note that dates may be combined via separate query parameters to create ranges, and all dates may be yyyy-MM-dd, yyyy-MM, or yyyy.

Record List Query Parameters
Parameter Description
allText search within most metadata fields (title, description, authors, etc.)
idFind a specific record by its unique record ID
doiFind a record by its DOI value or prefix
titleSearch within record title
contributing_organizationSearch within contributing organization
sponsoring_organizationSearch within sponsoring organization
research_organizationSearch within research organization
contract_numbersSearch within contract numbers
report_numbersSearch within report numbers
other_numbersSearch within other identifying numbers
descriptionSearch within description/abstract of records
authors
contributors
Search within authors or contributor names, roles, or ORCID/email values
product_typeFind records of a particular given product type (Dataset, Collection, etc)
product_type_specificSearch within descriptive or specific product type value
related_identifiersSearch within related identifier values
keywordsSearch within keywords
accession_numberFind a record by its site-assigned accession number
published-beforeFind all records published BEFORE a date
published-afterFind all records published AFTER a date
added-beforeFind all records entered prior to a date
added-afterFind all records entered after a date
updated-beforeFind all records updated before a date
updated-afterFind all records updated after a date
first-registered-beforeFind all records registered before a date
first-registered-afterFind all records registered after a date
last-registered-beforeFind all records last registered before a date
last-registered-afterFind all records last registered after a date
statusFind records in a given status: one of Registered, Error, Pending, Deactivated, or Reserved
ever-registeredFind records that have ("true") or have not ("false") been successfully sent to DataCite (DOI is registered)
has-orcidFind records that do ("true") or do not ("true") have at least one author with an ORCID value
has-accession-numberFind records that do ("true") or do not ("false") have accession number values
has-related-identifiersFind records that do ("true") or do not ("false") have at least one related identifier
has-doi-infixFind records that do ("true") or do not ("false") have a DOI infix value
startThe starting row number of records (from 0)
rowsThe number of rows per page to return (default 25)
sortSpecifies a field name on which to sort (see below)
orderSpecifies the sort order (one of asc or desc; descending is the default)
includeList one or more fields to include in results, in comma-delimited list (e.g., include=id,doi,title)

Record List Endpoint

https://www.osti.gov/iad2/api/records

Sort Order Fields

Query Sort Fields
Value Description
idSort by IAD ID value
titleSort by document title
doiSort by DOI value
statusSort by Status (Registered,Deactivated,Reserved,Error, or Pending)
product_typeSort by the product type of the record
first-registeredSort by date record was first registered at DataCite
publishedSort by the publication date
addedSort by date entered into IAD
updatedSort by date last updated in IAD

Single Record by ID

GET /records/{id}

The single record by id endpoint allows you to retrieve details for a specific record by providing the appropriate ID value as the key in the request path.

Record List Query Parameters
Parameter Description
none

Single Record Endpoint

https://www.osti.gov/iad2/api/records/{id}

Submit records to IAD

POST /records

Multiple records may be submitted to IAD at once, and new submission records may be intermixed with record updates as desired. Records may be submitted in JSON format as an array of objects, as defined by the Record Model; or if XML, as a collection of individual <record> entities within a <records> container.

Updates require the IAD unique id value to be provided.

Each submission response will contain a status value, which should be Pending for accepted records, and Error for those with issues. Error conditions will be returned as an errors array of reasons in JSON, or a collection of <error> tags wrapped by <errors> wrapper in XML.

Submissions should include the HTTP headers Content-Type and Accept to inform the service what type of data is being submitted, and the desired return result format, respectively. If not specified, the record results will be returned in JSON format.

For submissions, the following elements are required:

  • Title
  • A publication date
  • A site URL (if NOT Reserving a DOI)
  • A product type
  • A specific product type for non-dataset items

POST responses contain additional field information pertaining to the records given, including index numbers and error messages if any. See the Examples section for more information.

Submission Query Parameters
Parameter Description
none

Record Submission Endpoint

https://www.osti.gov/iad2/api/records

Submit legacy XML records

POST /records/legacyxml

The IAD system support input of the older, legacy XML format previously used in IAD 1.0. This format is accepted for input only, and should be considered deprecated in preference of the newer Record Model. These records may only be submitted in XML format, and should be expressed as a collection of <record> entities contained within a <records> wrapper.

The format of these records have been previously defined in the IAD 1.0 Submissions Document. While the ingest will accept only XML input, you may request the results in JSON of your submission. Note that the submission results will be the newer Record Model format, and many of the previously-required data fields are no longer necessary.

This endpoint is intended for transitioning to the newer format, and for backward compatibility with existing IAD clients.

Submission Query Parameters
Parameter Description
none

Legacy XML Record Submission Endpoint

https://www.osti.gov/iad2/api/records/legacyxml

Examples

Several typical use-case examples for interacting with the IAD API are included in this section. Representative examples assume the use of the curl command-line tool for simplicity, and assume that XML or JSON files containing records to be posted have already been created separately.

Sending Records to IAD

Records may be formatted in either JSON or XML for submission to IAD. Each should include the required record fields, noted in the submission discussion above. Unless otherwise specified, records are given new minted DOI values by the IAD system, based on your assigned DOI prefix value, the record's unique ID value, and any provided DOI infix value.

Note that the response will include a status for each record posted, as well as a total count and number of errors encountered. Any errors on individual records will be noted in the "errors" JSON array or <errors> XML collection as appropriate to the response format chosen. Accepted submission records will be in status "Pending" indicating they have not yet minted a DOI, as well as the IAD-assigned unique "id" field. The minting process takes place periodically in the background, and will usually be finished within a few minutes of submission. The next example API interaction will show how to check the status of your submitted records, based on the IAD "id" field value returned.

In this example, the record posted successfully (status is "Pending") and received an ID of 251599, and a DOI to be minted based on the supplied infix value and ID of "10.5072/my-example-infix/251599". See the section on searching via GET to learn how to retrieve records based on ID value and other fields, such as accession number or status.

Also see below for further examples on how to reserve DOIs for pre-print or new data sets if desired.

Note that it is possible to submit records in XML and receive a JSON response (or vice versa) if desired, based on the values you supply in the Accept and Content-Type HTTP headers.

Record Submission Endpoint

https://www.osti.gov/iad2/api/records

Example Request Data

Sample JSON Content (sample.json)


          [{
	"accession_number": "EXAMPLE001",
	"availability": "Check with publisher website for document availability",
	"authors": [{
		"first_name": "Test",
		"last_name": "Guy",
		"email": "just.a.test@someplace.com"
	}],
	"contributors": [{
			"full_name": "Contributing Editors, Inc.",
			"contributor_type": "Editor"
		},
		{
			"first_name": "Researcher",
			"last_name": "Guy",
			"email": "research.associate@university.edu",
			"affiliations": ["Research Associates Corp."],
			"contributor_type": "Researcher"
		}
	],
	"contract_numbers": "Example-001-2017",
	"country": "US",
	"description": "This is a document example containing all the relevant information fields for metadata.",
	"doi_infix": "my-example-infix",
	"keywords": "Sample Data",
	"language_code": "English",
	"other_numbers": "OtherIdentifyingNumbers",
	"product_type": "Dataset",
	"product_type_specific": "Short description of data specifics",
	"publication_date": "2017-12-02",
	"publisher": "ACME Examples, Inc., LLC",
	"report_numbers": "EX-001-2017",
	"research_organization": "Research Associates Corp.",
	"site_url": "http://my.data.site.com/example-dataset.pdf",
	"sponsoring_organization": "Data Collection Resources",
	"title": "This is a test example of a record",
	"related_identifiers": [{
		"identifier_type": "DOI",
		"identifier_value": "10.5072/9991/2017/238943",
		"relation_type": "Cites"
	}]
}]

Sending Records with curl

$ curl -u LOGINNAME https://www.osti.gov/iad2/api/records -X POST -H "Content-Type: application/json" --data @sample.json -H "Accept: application/json"

Example Response


{
	"records": [{
		"id": 251599,
		"site_code": "SITECODE",
		"title": "This is a test example of a record",
		"sponsoring_organization": "Data Collection Resources",
		"research_organization": "Research Associates Corp.",
		"accession_number": "EXAMPLE001",
		"doi_infix": "my-example-infix",
		"doi": "10.5072/my-example-infix/251599",
		"authors": [{
			"email": "just.a.test@someplace.com",
			"first_name": "Test",
			"last_name": "Guy",
			"affiliations": []
		}],
		"contributors": [{
			"full_name": "Contributing Editors, Inc.",
			"affiliations": [],
			"contributor_type": "Editor"
		}, {
			"email": "research.associate@university.edu",
			"first_name": "Researcher",
			"last_name": "Guy",
			"affiliations": ["Research Associates Corp."],
			"contributor_type": "Researcher"
		}],
		"status": "Pending",
		"report_numbers": "EX-001-2017",
		"contract_numbers": "Example-001-2017",
		"other_numbers": "OtherIdentifyingNumbers",
		"publisher": "ACME Examples, Inc., LLC",
		"availability": "Check with publisher website for document availability",
		"publication_date": "2017-12-02",
		"country": "US",
		"description": "This is a document example containing all the relevant information fields for metadata.",
		"site_url": "http://my.data.site.com/example-dataset.pdf",
		"product_type": "Dataset",
		"product_type_specific": "Short description of data specifics",
		"related_identifiers": [{
			"identifier_type": "DOI",
			"identifier_value": "10.5072/9991/2017/238943",
			"relation_type": "Cites"
		}],
		"date_record_added": "2017-11-30",
		"date_record_updated": "2017-11-30",
		"keywords": "Sample Data",
		"index": 1
	}],
	"total": 1,
	"errors": 0
}

Sample XML Content (sample.xml)


<records>
  <record>
    <title>This is a test example of a record</title>
    <sponsoring_organization>Data Collection Resources</sponsoring_organization>
    <research_organization>Research Associates Corp.</research_organization>
    <accession_number>EXAMPLE001</accession_number>
    <doi_infix>my-example-infix</doi_infix>
    <report_numbers>EX-001-2017</report_numbers>
    <contract_numbers>Example-001-2017</contract_numbers>
    <other_numbers>OtherIdentifyingNumbers</other_numbers>
    <publisher>ACME Examples, Inc., LLC</publisher>
    <availability>Check with publisher website for document availability</availability>
    <publication_date>2017-12-02</publication_date>
    <country>US</country>
    <description>This is a document example containing all the relevant information fields for metadata.</description>
    <site_url>http://my.data.site.com/example-dataset.pdf</site_url>
    <product_type>Dataset</product_type>
    <product_type_specific>Short description of data specifics</product_type_specific>
    <date_record_added>2017-11-30</date_record_added>
    <date_record_updated>2017-11-30</date_record_updated>
    <keywords>Sample Data</keywords>
    <authors>
      <author>
        <email>just.a.test@someplace.com</email>
        <first_name>Test</first_name>
        <last_name>Guy</last_name>
        <affiliations/>
      </author>
    </authors>
    <contributors>
      <contributor>
        <full_name>Contributing Editors, Inc.</full_name>
        <contributor_type>Editor</contributor_type>
        <affiliations/>
      </contributor>
      <contributor>
        <email>research.associate@university.edu</email>
        <first_name>Researcher</first_name>
        <last_name>Guy</last_name>
        <contributor_type>Researcher</contributor_type>
        <affiliations>
          <affiliation>Research Associates Corp.</affiliation>
        </affiliations>
      </contributor>
    </contributors>
    <related_identifiers>
      <related_identifier>
        <identifier_type>DOI</identifier_type>
        <identifier_value>10.5072/9991/2017/238943</identifier_value>
        <relation_type>Cites</relation_type>
      </related_identifier>
    </related_identifiers>
  </record>
</records>

Example request with curl

$ curl -u LOGINNAME https://www.osti.gov/iad2/api/records -X POST -H "Content-Type: application/xml" --data @sample.xml -H "Accept: application/xml"

Example Response


<records total="1" errors="0">
  <record status="Pending" index="1">
    <id>251599</id>
    <site_code>SITECODE</site_code>
    <title>This is a test example of a record</title>
    <sponsoring_organization>Data Collection Resources</sponsoring_organization>
    <research_organization>Research Associates Corp.</research_organization>
    <accession_number>EXAMPLE001</accession_number>
    <doi_infix>my-example-infix</doi_infix>
    <doi>10.5072/my-example-infix/251599</doi>
    <report_numbers>EX-001-2017</report_numbers>
    <contract_numbers>Example-001-2017</contract_numbers>
    <other_numbers>OtherIdentifyingNumbers</other_numbers>
    <publisher>ACME Examples, Inc., LLC</publisher>
    <availability>Check with publisher website for document availability</availability>
    <publication_date>2017-12-02</publication_date>
    <country>US</country>
    <description>This is a document example containing all the relevant information fields for metadata.</description>
    <site_url>http://my.data.site.com/example-dataset.pdf</site_url>
    <product_type>Dataset</product_type>
    <product_type_specific>Short description of data specifics</product_type_specific>
    <date_record_added>2017-11-30</date_record_added>
    <date_record_updated>2017-11-30</date_record_updated>
    <keywords>Sample Data</keywords>
    <authors>
      <author>
        <email>just.a.test@someplace.com</email>
        <first_name>Test</first_name>
        <last_name>Guy</last_name>
        <affiliations/>
      </author>
    </authors>
    <contributors>
      <contributor>
        <full_name>Contributing Editors, Inc.</full_name>
        <contributor_type>Editor</contributor_type>
        <affiliations/>
      </contributor>
      <contributor>
        <email>research.associate@university.edu</email>
        <first_name>Researcher</first_name>
        <last_name>Guy</last_name>
        <contributor_type>Researcher</contributor_type>
        <affiliations>
          <affiliation>Research Associates Corp.</affiliation>
        </affiliations>
      </contributor>
    </contributors>
    <related_identifiers>
      <related_identifier>
        <identifier_type>DOI</identifier_type>
        <identifier_value>10.5072/9991/2017/238943</identifier_value>
        <relation_type>Cites</relation_type>
      </related_identifier>
    </related_identifiers>
  </record>
</records>

Reserving a DOI

It may be necessary to obtain a DOI prior to a data set's publication, or for other convenience purposes prior to its being publically available. In such cases, IAD provides the ability to get a DOI value without minting it to a permanent URL value.

Reservations are obtained in the same manner as usual record submissions, but the status of "Reserved" is requested, and the "site_url" value is NOT required. This will create a placeholder record in IAD's system and return a valid DOI value that will not yet resolve to its destination. Upon data set publication, an additional update request should be made providing the site_url value and a status of Pending in order to notify IAD that the DOI is ready to be minted. Up until that point, the DOI value may be changed by the user as desired; after successful minting, it may not be changed (although the destination site_url MAY change at any time via IAD API update).

For purposes of this example, a minimal set of data is provided. The example ID of 251899 and DOI value of 10.5072/251899 are obtained. This record will remain in the Reserved status until it is subsequently updated to Pending with a site_url value provided by the user. During that time, the DOI obtained will NOT resolve to a URL destination.

See the section on searching with GET to find more information about retrieving records in Reserved status, for example. Also, the section examples on updating records provides more information on changing the status and adding a site_url when the record is ready to publish and resolve. An additional example of releasing a record to receive a DOI is also provided below. Note that such updates require only the id and site_url values to be present.

Example Reservation Request

Example request with curl

$ curl -u LOGINNAME -X POST -H "Content-Type: application/json" --data ' [ { "title":"Unpublished Data Set #001", "authors":[ { "first_name":"Guy", "last_name":"Sample" }], "publication_date":"2018-12-15", "product_type":"Dataset", "status":"Reserved" } ]' https://www.osti.gov/iad2/api/records

Example Response

    
HTTP/1.1 200 OK
Date: Thu, 30 Nov 2017 15:53:20 GMT
Content-Type: application/json
Content-Length: 399

{
	"records": [{
		"id": 251899,
		"site_code": "SITECODE",
		"title": "Unpublished Data Set #001",
		"doi": "10.5072/251899",
		"authors": [{
			"first_name": "Guy",
			"last_name": "Sample",
			"affiliations": []
		}],
		"contributors": [],
		"status": "Reserved",
		"publication_date": "2018-12-15",
		"product_type": "Dataset",
		"related_identifiers": [],
		"date_record_added": "2017-11-30",
		"date_record_updated": "2017-11-30",
		"index": 1
	}],
	"total": 1,
	"errors": 0
}

                                    

Example request with curl

$ curl -u LOGINNAME -X POST -H "Accept: application/xml" -H "Content-Type: application/xml" --data ' <records> <record status="Reserved"> <title>Unpublished Data Set #001</title> <authors> <author> <first_name>Guy</first_name> <last_name>Sample</last_name> </author> </authors> <publication_date>2018-12-15</publication_date> <product_type>Dataset</product_type> </record> </records>' https://www.osti.gov/iad2/api/records

Example Response

    
HTTP/1.1 200 OK
Date: Thu, 30 Nov 2017 15:53:20 GMT
Content-Type: application/xml
Content-Length: 633

<records total="1" errors="0">
  <record status="Reserved" index="1">
    <id>251899</id>
    <site_code>SITECODE</site_code>
    <title>Unpublished Data Set #001</title>
    <doi>10.5072/251899</doi>
    <publication_date>2018-12-15</publication_date>
    <product_type>Dataset</product_type>
    <date_record_added>2017-11-30</date_record_added>
    <date_record_updated>2017-11-30</date_record_updated>
    <authors>
      <author>
        <first_name>Guy</first_name>
        <last_name>Sample</last_name>
        <affiliations/>
      </author>
    </authors>
    <contributors/>
    <related_identifiers/>
  </record>
</records>


                                    

Releasing a Reserved DOI

Once a reserved DOI has been published or made available to the public, the DOI must be registered to complete its processing. In order to accomplish this, a request should be made to update the record by its id value with the site_url to be associated with the DOI that was reserved earlier. Examples are provided to the right.

For purposes of this example, the content to be updated is sent in-line with the curl command, but one may also provide this information via a file upload in either XML or JSON as preferred.

Note that if successful, this will place the record in a Pending state, and the reserved DOI will be minted and resolvable usually within a few minutes of making the request. The status of the record may be queried using the GET request to obtain information from the API.

Example Release Request

Example update request with curl

$ curl -u LOGINNAME -X POST -H "Content-Type: application/json" --data ' [ { "id":251899, "site_url":"http://mysite.example.com/link/to/my-dataset.html" } ]' https://www.osti.gov/iad2/api/records

Example Response

    
HTTP/1.1 200 OK
Date: Thu, 30 Nov 2017 15:53:20 GMT
Content-Type: application/json
Content-Length: 470

{
    "records": [
        {
            "id": 251899,
            "site_code": "SITECODE",
            "title": "Unpublished Data Set #001",
            "doi": "10.5072/251899",
            "authors": [
                {
                    "first_name": "Guy",
                    "last_name": "Sample",
                    "affiliations": []
                }
            ],
            "contributors": [],
            "status": "Pending",
            "publication_date": "2018-12-15",
            "site_url": "http://mysite.example.com/link/to/my-dataset.html",
            "product_type": "Dataset",
            "related_identifiers": [],
            "date_record_added": "2017-11-30",
            "date_record_updated": "2017-12-01",
            "index": 1
        }
    ],
    "total": 1,
    "errors": 0
}


                                    

Example update request with curl

$ curl -u LOGINNAME -X POST -H "Content-Type: application/xml" -H "Accept: application/xml" --data ' <records><record><id>251899</id><site_url>http://mysite.example.com/link/to/my-dataset.html</site_url> </record></records>' https://www.osti.gov/iad2/api/records

Example Response

                              
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 972

<records total="1" errors="0">
  <record status="Pending" index="1">
    <id>251899</id>
    <site_code>SITECODE</site_code>
    <title>Unpublished Data Set #001</title>
    <doi>10.5072/251899</doi>
    <publication_date>2018-12-15</publication_date>
    <site_url>http://mysite.example.com/link/to/my-dataset.html</site_url>
    <product_type>Dataset</product_type>
    <date_record_added>2017-11-30</date_record_added>
    <date_record_updated>2017-12-01</date_record_updated>
    <authors>
      <author>
        <first_name>Guy</first_name>
        <last_name>Sample</last_name>
        <affiliations/>
      </author>
    </authors>
    <contributors/>
    <related_identifiers/>
  </record>
</records>

                                    

Getting Records from IAD

The provided example shows how one might look up a record by its unique ID value, in either JSON or XML format. Note that the section above on searching via GET provides further information on searchable data fields. Common uses might be to find all records based on status of Error, or Pending, in order to determine the state of a set of records. Also, it is possible to query a particular record by its DOI, even if the record is not yet minted, in order to determine its status.

Note that if format is not specified, the default return type is JSON. All requests should use basic HTTP authentication for identification purposes.

Example Query for Example Record

$ curl -u LOGINNAME https://www.osti.gov/iad2/api/records/241599


HTTP/1.1 200 OK
Date: Thu, 30 Nov 2017 15:53:20 GMT
Content-Type: application/json
Content-Length: 1450 
          
{
	"records": [{
		"id": 251599,
		"site_code": "SITECODE",
		"title": "This is a test example of a record",
		"sponsoring_organization": "Data Collection Resources",
		"research_organization": "Research Associates Corp.",
		"accession_number": "EXAMPLE001",
		"doi_infix": "my-example-infix",
		"doi": "10.5072/my-example-infix/251599",
		"authors": [{
			"email": "just.a.test@someplace.com",
			"first_name": "Test",
			"last_name": "Guy",
			"affiliations": []
		}],
		"contributors": [{
			"full_name": "Contributing Editors, Inc.",
			"affiliations": [],
			"contributor_type": "Editor"
		}, {
			"email": "research.associate@university.edu",
			"first_name": "Researcher",
			"last_name": "Guy",
			"affiliations": ["Research Associates Corp."],
			"contributor_type": "Researcher"
		}],
		"status": "Pending",
		"report_numbers": "EX-001-2017",
		"contract_numbers": "Example-001-2017",
		"other_numbers": "OtherIdentifyingNumbers",
		"publisher": "ACME Examples, Inc., LLC",
		"availability": "Check with publisher website for document availability",
		"publication_date": "2017-12-02",
		"country": "US",
		"description": "This is a document example containing all the relevant information fields for metadata.",
		"site_url": "http://my.data.site.com/example-dataset.pdf",
		"product_type": "Dataset",
		"product_type_specific": "Short description of data specifics",
		"related_identifiers": [{
			"identifier_type": "DOI",
			"identifier_value": "10.5072/9991/2017/238943",
			"relation_type": "Cites"
		}],
		"date_record_added": "2017-11-30",
		"date_record_updated": "2017-11-30",
		"keywords": "Sample Data"
	}],
	"start": 0,
	"total": 1
}

                                    

$ curl -u LOGINNAME https://www.osti.gov/iad2/api/records/241599 -H "Accept: application/xml"

          
HTTP/1.1 200 OK
Date: Thu, 30 Nov 2017 15:58:06 GMT
Content-Type: application/xml
Content-Length: 2372

                                    

<records total="1" start="0">
  <record status="Pending">
    <id>251599</id>
    <site_code>SITECODE</site_code>
    <title>This is a test example of a record</title>
    <sponsoring_organization>Data Collection Resources</sponsoring_organization>
    <research_organization>Research Associates Corp.</research_organization>
    <accession_number>EXAMPLE001</accession_number>
    <doi_infix>my-example-infix</doi_infix>
    <doi>10.5072/my-example-infix/251599</doi>
    <report_numbers>EX-001-2017</report_numbers>
    <contract_numbers>Example-001-2017</contract_numbers>
    <other_numbers>OtherIdentifyingNumbers</other_numbers>
    <publisher>ACME Examples, Inc., LLC</publisher>
    <availability>Check with publisher website for document availability</availability>
    <publication_date>2017-12-02</publication_date>
    <country>US</country>
    <description>This is a document example containing all the relevant information fields for metadata.</description>
    <site_url>http://my.data.site.com/example-dataset.pdf</site_url>
    <product_type>Dataset</product_type>
    <product_type_specific>Short description of data specifics</product_type_specific>
    <date_record_added>2017-11-30</date_record_added>
    <date_record_updated>2017-11-30</date_record_updated>
    <keywords>Sample Data</keywords>
    <authors>
      <author>
        <email>just.a.test@someplace.com</email>
        <first_name>Test</first_name>
        <last_name>Guy</last_name>
        <affiliations/>
      </author>
    </authors>
    <contributors>
      <contributor>
        <full_name>Contributing Editors, Inc.</full_name>
        <contributor_type>Editor</contributor_type>
        <affiliations/>
      </contributor>
      <contributor>
        <email>research.associate@university.edu</email>
        <first_name>Researcher</first_name>
        <last_name>Guy</last_name>
        <contributor_type>Researcher</contributor_type>
        <affiliations>
          <affiliation>Research Associates Corp.</affiliation>
        </affiliations>
      </contributor>
    </contributors>
    <related_identifiers>
      <related_identifier>
        <identifier_type>DOI</identifier_type>
        <identifier_value>10.5072/9991/2017/238943</identifier_value>
        <relation_type>Cites</relation_type>
      </related_identifier>
    </related_identifiers>
  </record>
</records>
                                            

Updating Records

Records may be modified at any time, and can in fact be sent in batches of both updates and new records via the usual submission API endpoint. These updates may be as detailed or simple as desired, and may even specify a single field to be altered. All existing data will remain unchanged. Note however that once a DOI value has been minted, it may NOT be changed via this API. Update requests that would remove required field information will similarly be rejected with error messages as to the validation failures. Note the status of the returned update information to ensure that your submission completed successfully. If accepted, the record status should be "Pending", showing that it has been accepted and will update the DOI database authority usually within minutes of submission.

For purposes of this example, we will change the title and report number values of the submitted record. As with any submission, you may send and receive data in any desired format, based on the HTTP headers Accept and Content-Type. The data being changed is sent in-line on the curl command, but may also be submitted via a file containing the same data.

The ID value should be supplied to indicate the record to be edited. Note that the response will contain the entire record, including any edits made. Also, edits to authors or contributors should include ALL such data, as they will be replaced as a unit by updates. If you wish to remove all contributor data from a record, for example, send an empty array (JSON) or <contributors> collection (XML) as appropriate.

As with all submissions, JSON is the default response format unless XML is requested via the Accept HTTP header.

Example Update API

Example JSON Update Request

$ curl -u LOGINNAME -H "Content-Type: application/json" --data '[{ "id":251599, "title":"Updated Title" }]' https://www.osti.gov/iad2/api/records

Example Response

          
  {
	"records": [{
		"id": 251599,
		"site_code": "SITECODE",
		"title": "Updated Title",
		"sponsoring_organization": "Data Collection Resources",
		"research_organization": "Research Associates Corp.",
		"accession_number": "EXAMPLE001",
		"doi_infix": "my-example-infix",
		"doi": "10.5072/my-example-infix/251599",
		"authors": [{
			"email": "just.a.test@someplace.com",
			"first_name": "Test",
			"last_name": "Guy",
			"affiliations": []
		}],
		"contributors": [{
			"full_name": "Contributing Editors, Inc.",
			"affiliations": [],
			"contributor_type": "Editor"
		}, {
			"email": "research.associate@university.edu",
			"first_name": "Researcher",
			"last_name": "Guy",
			"affiliations": ["Research Associates Corp."],
			"contributor_type": "Researcher"
		}],
		"status": "Pending",
		"report_numbers": "EX-001-2017",
		"contract_numbers": "Example-001-2017",
		"other_numbers": "OtherIdentifyingNumbers",
		"publisher": "ACME Examples, Inc., LLC",
		"availability": "Check with publisher website for document availability",
		"publication_date": "2017-12-02",
		"country": "US",
		"description": "This is a document example containing all the relevant information fields for metadata.",
		"site_url": "http://my.data.site.com/example-dataset.pdf",
		"product_type": "Dataset",
		"product_type_specific": "Short description of data specifics",
		"related_identifiers": [{
			"identifier_type": "DOI",
			"identifier_value": "10.5072/9991/2017/238943",
			"relation_type": "Cites"
		}],
		"date_record_added": "2017-11-30",
		"date_record_updated": "2017-11-30",
		"keywords": "Sample Data",
		"index": 1
	}],
	"total": 1,
	"errors": 0
}

                                    

Example XML Update Request

$ curl -u LOGINNAME -H "Content-Type: application/xml" -H "Accept: application/xml" --data '<records><record><id>251599</id><title>Updated Title</title></record></records>' https://www.osti.gov/iad2/records

Example Response


<records total="1" errors="0">
  <record status="Pending" index="1">
    <id>251599</id>
    <site_code>SITECODE</site_code>
    <title>Updated Title</title>
    <sponsoring_organization>Data Collection Resources</sponsoring_organization>
    <research_organization>Research Associates Corp.</research_organization>
    <accession_number>EXAMPLE001</accession_number>
    <doi_infix>my-example-infix</doi_infix>
    <doi>10.5072/my-example-infix/251599</doi>
    <report_numbers>EX-001-2017</report_numbers>
    <contract_numbers>Example-001-2017</contract_numbers>
    <other_numbers>OtherIdentifyingNumbers</other_numbers>
    <publisher>ACME Examples, Inc., LLC</publisher>
    <availability>Check with publisher website for document availability</availability>
    <publication_date>2017-12-02</publication_date>
    <country>US</country>
    <description>This is a document example containing all the relevant information fields for metadata.</description>
    <site_url>http://my.data.site.com/example-dataset.pdf</site_url>
    <product_type>Dataset</product_type>
    <product_type_specific>Short description of data specifics</product_type_specific>
    <date_record_added>2017-11-30</date_record_added>
    <date_record_updated>2017-11-30</date_record_updated>
    <keywords>Sample Data</keywords>
    <authors>
      <author>
        <email>just.a.test@someplace.com</email>
        <first_name>Test</first_name>
        <last_name>Guy</last_name>
        <affiliations/>
      </author>
    </authors>
    <contributors>
      <contributor>
        <full_name>Contributing Editors, Inc.</full_name>
        <contributor_type>Editor</contributor_type>
        <affiliations/>
      </contributor>
      <contributor>
        <email>research.associate@university.edu</email>
        <first_name>Researcher</first_name>
        <last_name>Guy</last_name>
        <contributor_type>Researcher</contributor_type>
        <affiliations>
          <affiliation>Research Associates Corp.</affiliation>
        </affiliations>
      </contributor>
    </contributors>
    <related_identifiers>
      <related_identifier>
        <identifier_type>DOI</identifier_type>
        <identifier_value>10.5072/9991/2017/238943</identifier_value>
        <relation_type>Cites</relation_type>
      </related_identifier>
    </related_identifiers>
  </record>
</records>

Handling Submission Errors

Submission errors return specific information to the user when particular records fail to validate. Examples of these elements, and how to interpret them, are presented to the left.

While some errors will return a non-200 HTTP status code response, as detailed above, submission errors usually will respond with 200-OK, but will detail in the body of each record response the condition and error messages. The response for each record will contain a status tag or attribute; any of these in "Error" state should also contain either an "errors" array (JSON) or <errors> container (XML) containing information about the errors.

In this example, two sample incomplete records are provided, and the results for each are shown. Note that each record contains the status "Error", and an index number referencing its position in the submission. Additionally, the total number of records and number of errors are provided.

It should be noted that these submission errors are distinct from existing records in "Error" status; such records indicate the metadata itself is valid, but an issue occurred with DOI registration. Reasons for this are detailed in the "doi_message" field of the records, which can be returned via performing a GET request for the status of Error.

Example of Validation Errors

Incomplete Record Example

$ curl -u LOGINNAME -X POST -H "Content-Type: application/json" --data '[{ "description":"One" },{ "description":"Two" }]' -u LOGINNAME https://www.osti.gov/iad2/api/records

Example Response

          
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 610

{
    "records": [
        {
            "site_code": "SITECODE",
            "status": "Error",
            "description": "One",
            "index": 1,
            "errors": [
                "Title is required.",
                "At least one Author is required.",
                "A publication date is required.",
                "A site URL is required.",
                "A product type is required.",
                "A specific product type is required for non-dataset types."
            ]
        },
        {
            "site_code": "SITECODE",
            "status": "Error",
            "description": "Two",
            "index": 2,
            "errors": [
                "Title is required.",
                "At least one Author is required.",
                "A publication date is required.",
                "A site URL is required.",
                "A product type is required.",
                "A specific product type is required for non-dataset types."
            ]
        }
    ],
    "total": 2,
    "errors": 2
}

                                    

Incomplete Records Example

$ curl -u LOGINNAME -X POST -H "Content-Type: application/xml" -H "Accept: application/xml" --data '<records> <record> <description>One</description> </record> <record> <description>Two</description> </record> </records>' -u LOGINNAME https://www.osti.gov/iad2/api/records

Example Response

    
HTTP/1.1 200 OK
Content-Type: application/xml
Content-Length: 972

<records total="2" errors="2">
  <record status="Error" index="1">
    <site_code>SITECODE</site_code>
    <description>One</description>
    <errors>
      <error>Title is required.</error>
      <error>At least one Author is required.</error>
      <error>A publication date is required.</error>
      <error>A site URL is required.</error>
      <error>A product type is required.</error>
      <error>A specific product type is required for non-dataset types.</error>
    </errors>
  </record>
  <record status="Error" index="2">
    <site_code>SITECODE</site_code>
    <description>Two</description>
    <errors>
      <error>Title is required.</error>
      <error>At least one Author is required.</error>
      <error>A publication date is required.</error>
      <error>A site URL is required.</error>
      <error>A product type is required.</error>
      <error>A specific product type is required for non-dataset types.</error>
    </errors>
  </record>
</records>


                                    

Deactivating DOIs

While a DOI is intended to be a persistent reference to a URL, there may be occasion to prevent its resolution, should it no longer be valid. It is generally recommended to redirect the DOI to a "tombstone" page with an explanation as to its state, however if such a solution is not viable, use the DELETE endpoint to mark a data set as unavailable.

It should be noted that the record itself will not be removed, but marked with a status value of Deactivated, and its DOI, if any, will be rendered inoperable.

This endpoint will return any such record in its Deactivated state, in the format specified by the HTTP Accept header (defaulting to JSON). The response code should be either 200 OK if successful, or 404 NOT FOUND if the record is not on file or is unavailable.

Example Record Deactivation

$ curl -X DELETE -u LOGINNAME https://www.osti.gov/iad2/api/records/251599

Example Response

          
HTTP/1.1 200 OK
Content-Type: application/json

{
	"records": [{
		"id": 251599,
		"site_code": "SITECODE",
		"title": "Updated Title",
		"sponsoring_organization": "Data Collection Resources",
		"research_organization": "Research Associates Corp.",
		"accession_number": "EXAMPLE001",
		"doi_infix": "my-example-infix",
		"doi": "10.5072/my-example-infix/251599",
		"authors": [{
			"email": "just.a.test@someplace.com",
			"first_name": "Test",
			"last_name": "Guy",
			"affiliations": []
		}],
		"contributors": [{
			"full_name": "Contributing Editors, Inc.",
			"affiliations": [],
			"contributor_type": "Editor"
		}, {
			"email": "research.associate@university.edu",
			"first_name": "Researcher",
			"last_name": "Guy",
			"affiliations": ["Research Associates Corp."],
			"contributor_type": "Researcher"
		}],
		"status": "Deactivated",
		"report_numbers": "EX-001-2017",
		"contract_numbers": "Example-001-2017",
		"other_numbers": "OtherIdentifyingNumbers",
		"publisher": "ACME Examples, Inc., LLC",
		"availability": "Check with publisher website for document availability",
		"publication_date": "2017-12-02",
		"country": "US",
		"description": "This is a document example containing all the relevant information fields for metadata.",
		"site_url": "http://my.data.site.com/example-dataset.pdf",
		"product_type": "Dataset",
		"product_type_specific": "Short description of data specifics",
		"related_identifiers": [{
			"identifier_type": "DOI",
			"identifier_value": "10.5072/9991/2017/238943",
			"relation_type": "Cites"
		}],
		"date_record_added": "2017-11-30",
		"date_record_updated": "2017-11-30",
		"keywords": "Sample Data"
	}],
	"total": 1,
	"start": 0
}

                                    

$ curl -X DELETE -H "Accept: application/xml" -u LOGINNAME https://www.osti.gov/iad2/api/records/251599

Example Response

            
<records total="1" start="0">
  <record status="Deactivated">
    <id>251599</id>
    <site_code>SITECODE</site_code>
    <title>Updated Title</title>
    <sponsoring_organization>Data Collection Resources</sponsoring_organization>
    <research_organization>Research Associates Corp.</research_organization>
    <accession_number>EXAMPLE001</accession_number>
    <doi_infix>my-example-infix</doi_infix>
    <doi>10.5072/my-example-infix/251599</doi>
    <report_numbers>EX-001-2017</report_numbers>
    <contract_numbers>Example-001-2017</contract_numbers>
    <other_numbers>OtherIdentifyingNumbers</other_numbers>
    <publisher>ACME Examples, Inc., LLC</publisher>
    <availability>Check with publisher website for document availability</availability>
    <publication_date>2017-12-02</publication_date>
    <country>US</country>
    <description>This is a document example containing all the relevant information fields for metadata.</description>
    <site_url>http://my.data.site.com/example-dataset.pdf</site_url>
    <product_type>Dataset</product_type>
    <product_type_specific>Short description of data specifics</product_type_specific>
    <date_record_added>2017-11-30</date_record_added>
    <date_record_updated>2017-11-30</date_record_updated>
    <keywords>Sample Data</keywords>
    <authors>
      <author>
        <email>just.a.test@someplace.com</email>
        <first_name>Test</first_name>
        <last_name>Guy</last_name>
        <affiliations/>
      </author>
    </authors>
    <contributors>
      <contributor>
        <full_name>Contributing Editors, Inc.</full_name>
        <contributor_type>Editor</contributor_type>
        <affiliations/>
      </contributor>
      <contributor>
        <email>research.associate@university.edu</email>
        <first_name>Researcher</first_name>
        <last_name>Guy</last_name>
        <contributor_type>Researcher</contributor_type>
        <affiliations>
          <affiliation>Research Associates Corp.</affiliation>
        </affiliations>
      </contributor>
    </contributors>
    <related_identifiers>
      <related_identifier>
        <identifier_type>DOI</identifier_type>
        <identifier_value>10.5072/9991/2017/238943</identifier_value>
        <relation_type>Cites</relation_type>
      </related_identifier>
    </related_identifiers>
  </record>
</records>     

                                    

Appendix

Related Identifiers: Relationship Types

Codes used to define inter- and intra-work relationships between this record (A) and another record (B). Often there are reciprocal relationships between A and B defined separately by each work.

Relationship Types
Code Description
IsCitedBy Indicates A is listed as a citation by B.
Cites Indicates A lists B as a citation.
IsSupplementTo Indicates A is a supplemental work to B.
IsSupplementedBy Indicates B is a supplement to A.
IsContinuedBy Indicates A is continued by B.
Continues Indicates A is a continuation of B.
Describes Indicates that A describes B.
IsDescribedBy Indicates that A is described by B.
HasMetadata Indicates B has metadata about A.
IsMetadataFor Indicates A contains the metadata for B.
HasVersion Indicates B has a version of A.
IsVersionOf Indicates A is a version of B.
IsNewVersionOf Indicates A is a newer version of B.
IsPreviousVersionOf Indicates B is a newer version of A.
IsPartOf Indicates A is a portion of B, as in a series.
HasPart Indicates A includes the part B, for series or containers.
IsReferencedBy Indicates A is referenced by B.
References Indicates A references B.
IsDocumentedBy Indicates B contains documentation about A. (e.g., software documentation, user manual)
Documents Indicates A is the documentation for B.
IsCompiledBy Indicates B is used to compile or create A.
Compiles Indicates B is result of compilation or creation of A.
IsVariantFormOf Indicates A is a variation or different version of B.
IsOriginalFormOf Indicates A is the original version of B.
IsIdenticalTo Indicates A and B are identical.
IsReviewedBy Indicates B contains review information of A.
Reviews Indicates A contains a review of B.
IsDerivedFrom Indicates B is the source on which A is based.
IsSourceOf Indicates A is the source on which B is based.
IsRequiredBy Indicates A is required by B.
Requires Indicates A requires B.
Obsoletes Indicates A replaces or renders B obsolete.
IsObsoletedBy Indicates A is replaced by or obsoleted by B.

Example Related Identifiers

          
		"related_identifiers": [
                {
                    "identifier_type": "DOI",
                    "identifier_value": "10.5072/9991/2017/238943",
                    "relation_type": "IsCitedBy"
		},
                { 
                    "identifier_type": "ISBN",
                    "identifier_value": "0761964312",
                    "relation_type": "Cites"
                },
                {
                    "identifier_type": "URN",
                    "identifier_value": "urn:nbn:de:bsz:21-opus-4966",
                    "relation_type": "Continues"
                },
                {
                    "identifier_type": "URL",
                    "identifier_value": "https://github.com/software-package/samples/v2",
                    "relation_type": "IsVersionOf"
                },
                {
                    "identifier_type": "DOI",
                    "identifier_value": "10.1234/7836",
                    "relation_type": "Documents"
                },
                {
                    "identifier_type": "DOI",
                    "identifier_value": "10.1234/V7/2893",
                    "relation_type": "Obsoletes"
                }
                ]

                                    
            
    <related_identifiers>
      <related_identifier>
        <identifier_type>DOI</identifier_type>
        <identifier_value>10.5072/9991/2017/238943</identifier_value>
        <relation_type>IsCitedBy</relation_type>
      </related_identifier>
      <related_identifier>
        <identifier_type>ISBN</identifier_type>
        <identifier_value>0761964312</identifier_value>
        <relation_type>Cites</relation_type>
      </related_identifier>
      <related_identifier>
        <identifier_type>URN</identifier_type>
        <identifier_value>urn:nbn:de:bsz:21-opus-4966</identifier_value>
        <relation_type>Continues</relation_type>
      </related_identifier>
      <related_identifier>
        <identifier_type>URL</identifier_type>
        <identifier_value>https://github.com/software-package/samples/v2</identifier_value>
        <relation_type>IsVersionOf</relation_type>
      </related_identifier>
      <related_identifier>
        <identifier_type>DOI</identifier_type>
        <identifier_value>10.1234/7836</identifier_value>
        <relation_type>Documents</relation_type>
      </related_identifier>
      <related_identifier>
        <identifier_type>DOI</identifier_type>
        <identifier_value>10.1234/V7/2893</identifier_value>
        <relation_type>Obsoletes</relation_type>
      </related_identifier>
    </related_identifiers>

                                    

Related Identifiers: Identifier Types

Codes for supported types of identifier values for defining related identifiers.

Identifier Types
Code Description
ARK Archival Resource Key; URL designed to support long-term access to information objects. In general, ARK syntax is of the form (brackets indicate [optional] elements: [http://NMA/]ark:/NAAN/Name[Qualifier]
arXiv arXiv identifier; arXiv.org is a repository of pre-prints of scientific papers in the fields of mathematics, physics, astronomy, computer science, quantitative biology, statistics, and quantitative finance.
bibcode Astrophysics Data System bibliographic codes; a standardized 19 character identifier according to the syntax yyyyjjjjjvvvvmppppa. See http://info-uri.info/registry/OAIHandler?verb=GetRecord&metadataPrefix=reg&identifier=info:bibcode/
DOI Digital Object Identifier; a character string used to uniquely identify an object. A DOI name is divided into two parts, a prefix and a suffix, separated by a slash.
EAN13 European Article Number, now renamed International Article Number,but retaining the original acronym, is a 13-digit barcoding standard which is a superset of the original 12-digit Universal Product Code (UPC) system.
EISSN Electronic International Standard Serial Number; ISSN used to identify periodicals in electronic form (eISSN or e-ISSN).
Handle A handle is an abstract reference to a resource.
IGSN International Geo Sample Number; a 9-digit alphanumeric code that uniquely identifies samples from our natural environment and related sampling features.
ISBN International Standard Book Number; a unique numeric book identifier. There are 2 formats: a 10-digit ISBN format and a 13-digit ISBN.
ISSN International Standard Serial Number; a unique 8-digit number used to identify a print or electronic periodical publication.
ISTC International Standard Text Code; a unique “number” assigned to a textual work. An ISTC consists of 16 numbers and/or letters.
LISSN The linking ISSN or ISSN-L enables collocation or linking among different media versions of a continuing resource.
LSID Life Science Identifiers; a unique identifier for data in the Life Science domain. Format: urn:lsid:authority:namespace:identifier:revision
PMID PubMed identifier; a unique number assigned to each PubMed record.
PURL Persistent Uniform Resource Locator.A PURL has three parts: (1) a protocol, (2) a resolver address, and (3) a name.
UPC Universal Product Code is a barcode symbology used for tracking trade items in stores. Its most common form, the UPC-A, consists of 12 numerical digits.
URL Uniform Resource Locator, also known as web address, is a specific character string that constitutes a reference to a resource. The syntax is:schema://domain:port/path?query_string#fragment_id
URN Uniform Resource Name; is a unique and persistent identifier of an electronic document. The syntax is: urn:<NID<:<NSS> The leading urn:sequence is case-insensitive, <NID> is the namespace identifier, <NSS> is the namespace-specific string.
w3id Permanent identifier for Web applications. Mostly used to publish vocabularies and ontologies. The letters ‘w3’ stand for “World Wide Web”.

IAD-to-DataCite Schema Mapping

The table below defines the data schema mapping from IAD input fields to the DataCite DOIs registration schema defined in the DataCite Metadata Schema. Currently, IAD supports the DataCite schema version 4.4.

DataCite Field Mapping
IAD Data Element DataCite Schema Element
doi Identifier identifierType="DOI"
id alternateIdentifier alternateIdentifierType="IAD ID"
authors: name or first_name/last_name, orcid, affiliation creators: creatorName or givenName/familyName, nameIdentifier nameIdentifierScheme="ORCID", affiliation
contributors: name or first_name/last_name, orcid, affiliation, contributor_type contributors: contributorName, nameIdentifier nameIdentifierScheme="ORCID", affiliation, contributorType
title Titles: title
publisher publisher
publication_date publicationYear (year-only)
product_type resourceType resourceTypeGeneral attribute
product_type_specific resourceType value
keywords subjects
related_identifier: identifier_type, relation_type relatedIdentifier: relatedIdentifierType, relationType
report_numbers alternateIdentifier alternateIdentifierType="Report Numbers"
contract_numbers alternateIdentifier alternateIdentifierType="Contract Numbers"
accession_number alternateIdentifier alternateIdentifierType="Site ID"
other_numbers alternateIdentifier alternateIdentifierType="Other Numbers"
description description descriptionType="Abstract"
site_url DOI landing page URL value

Example Translation


    {
      "id": 29999,
      "site_code": "OSTI",
      "title": "Example IAD to DataCite Mapping documentation",
      "sponsoring_organization": "Department of Energy, OSTI",
      "doi_infix": "2021-docs",
      "doi": "10.80282/2021-docs/29999",
      "authors": [
        {
          "email": "iad@osti.gov",
          "full_name": "OSTI Data Team: IAD",
          "affiliations": []
        },
        {
          "email": "ensorn@osti.gov",
          "orcid": "https://orcid.org/0000-0001-5166-5705",
          "first_name": "Neal",
          "last_name": "Ensor",
          "affiliations": [
            "OSTI",
            "DOE"
          ]
        }
      ],
      "contributors": [
        {
          "full_name": "Editors Anonymous, Inc.",
          "affiliations": [],
          "contributor_type": "Editor"
        },
        {
          "email": "research.associate@university.edu",
          "first_name": "Research",
          "last_name": "Guy",
          "affiliations": [
            "Research Associates Group"
          ],
          "contributor_type": "Researcher"
        }
      ],
      "status": "Registered",
      "report_numbers": "EXAMPLE-DOCS-2021-002",
      "contract_numbers": "Example-FS-2021-IAD",
      "other_numbers": "docs-2021-revision-032",
      "publisher": "Office of Scientific and Technical Information",
      "publication_date": "2021-07-12",
      "country": "US",
      "description": "IAD API documentation information regarding DataCite schema mappings, revised appendix.",
      "site_url": "https://www.osti.gov/iad2/docs#appendix",
      "product_type": "Text",
      "product_type_specific": "Link to online documentation URL",
      "related_identifiers": [
        {
          "identifier_type": "DOI",
          "identifier_value": "10.5072/9991/2018/3892",
          "relation_type": "Cites"
        }
      ],
      "date_first_registered": "2021-07-12",
      "date_last_registered": "2021-07-12",
      "date_record_added": "2021-07-12",
      "date_record_updated": "2021-07-12",
      "keywords": "Online Documentation; Reference Materials"
    }      

                                    
            
    <?xml version="1.0" encoding="UTF-8"?>
<resource
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns="http://datacite.org/schema/kernel-4" xsi:schemaLocation="http://datacite.org/schema/kernel-4 http://schema.datacite.org/meta/kernel-4/metadata.xsd">
    <identifier identifierType="DOI">10.80282/2021-DOCS/29999</identifier>
    <creators>
        <creator>
            <creatorName nameType="Organizational">OSTI Data Team: IAD</creatorName>
        </creator>
        <creator>
            <creatorName nameType="Personal">Ensor, Neal</creatorName>
            <givenName>Neal</givenName>
            <familyName>Ensor</familyName>
            <nameIdentifier nameIdentifierScheme="ORCID" schemeURI="">https://orcid.org/0000-0001-5166-5705</nameIdentifier>
        </creator>
    </creators>
    <titles>
        <title>Example IAD to DataCite Mapping documentation</title>
    </titles>
    <publisher>Office of Scientific and Technical Information</publisher>
    <publicationYear>2021</publicationYear>
    <resourceType resourceTypeGeneral="Text">Link to online documentation URL</resourceType>
    <contributors>
        <contributor contributorType="Editor">
            <contributorName nameType="Organizational">Editors Anonymous, Inc.</contributorName>
        </contributor>
        <contributor contributorType="Researcher">
            <contributorName nameType="Personal">Guy, Research</contributorName>
            <givenName>Research</givenName>
            <familyName>Guy</familyName>
        </contributor>
    </contributors>
    <alternateIdentifiers>
        <alternateIdentifier alternateIdentifierType="IAD ID">29999</alternateIdentifier>
        <alternateIdentifier alternateIdentifierType="Report Numbers">EXAMPLE-DOCS-2021-002</alternateIdentifier>
        <alternateIdentifier alternateIdentifierType="Contract Numbers">Example-FS-2021-IAD</alternateIdentifier>
        <alternateIdentifier alternateIdentifierType="Other Numbers">docs-2021-revision-032</alternateIdentifier>
    </alternateIdentifiers>
    <relatedIdentifiers>
        <relatedIdentifier relatedIdentifierType="DOI" relationType="Cites">10.5072/9991/2018/3892</relatedIdentifier>
    </relatedIdentifiers>
    <sizes/>
    <formats/>
    <version/>
</resource>

                                    

The IAD API is actively in development; the documentation should be kept up to date with the functionality of the current release. If you have any questions or suggestions, please let us know.

IAD Version 2.0.16