Upload
others
View
3
Download
0
Embed Size (px)
Citation preview
DOE DATA ID SERVICE
Announcing and Registering DOE’s Datasets via Announcement Notice (AN) 241.6
Manual Version 6.1, May 2018
www.osti.gov/dataexplorer/api/v1/docs#introduction
DOE Data ID Service Client Quick Start
Do you have an
OSTI test E-Link
account?
Login to test E-Link,
www.osti.gov/elink
test/2416api.
Contact OSTI at
or 865-576-6597.
Was your login
successful?
Do you have an
API software tool
for integration
with OSTI’s API?
Submit test records
in test E-Link.
Were submissions
successful?
Contact
to set up an E-Link
production account.
Check error codes.
Update XML.
Download client
software; see
legend below.*
*Client Software by Browser Chrome = Restlet Client Firefox = HTTP Requester IE = XML HTTP Requester
Yes
Yes
Yes
Yes
No
No
No
No
Contents 1.0 About AN 241.6 and the DOE Data ID Service ................................................................................................ 1
1.1 General Requirements ................................................................................................................................ 2
1.2 Understanding Key Components ................................................................................................................ 2
The Digital Object Identifier (DOI) ................................................................................................................ 3
The Landing Page .......................................................................................................................................... 4
2.0 Using the DOE Data ID Service API.................................................................................................................. 4
Introduction ...................................................................................................................................................... 4
2.1 Authentication ............................................................................................................................................ 4
2.2 HTTP Methods ............................................................................................................................................ 5
2.3 Response Headers....................................................................................................................................... 6
2.4 Pagination ................................................................................................................................................... 7
2.5 Record Model.............................................................................................................................................. 7
2.6 Collections Model ..................................................................................................................................... 20
2.7 Error Models ............................................................................................................................................. 23
2.8 Endpoints .................................................................................................................................................. 24
Frequently Asked Questions (FAQs) ............................................................................................................... 28
Appendices ......................................................................................................................................................... 32
Appendix A1: DOE Data ID Service Metadata ................................................................................................. 32
Appendix A2: Special Functionalities .............................................................................................................. 42
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 1
Changes and Additions from version 6.0 to 6.1
• DOE Data ID Service Client Quick Start Flow Chart
• Dataset type: Previously the <dataset type> tag contained SW or software as an option. Software is no
longer accepted in AN 241.6. To submit software for a DOI, please go to DOE CODE.
• API documentation examples with cURL and XML
1.0 About AN 241.6 and the DOE Data ID Service Announcement Notice (AN) 241.6 maintained the U.S. Department of Energy
(DOE) Office of Scientific and Technical Information (OSTI) provides the metadata
needed to identify/announce datasets resulting from work funded by DOE. The
submitted information allows the DOE Data ID Service, managed by OSTI, to
assign Digital Object Identifiers (DOIs) to datasets and register them with
DataCite. This value-added step facilitates visibility, ensures long-term
preservation, (re)usability and supports better linkage between DOE’s published
research results and the underlying data.
The DOE Data ID Service is the official name covering both the submission process
for metadata about datasets and the DOI registration process for those datasets.
The Data ID Service allows submission, edits and retrieval of dataset records. OSTI
offers an Application Programming Interface (API) for POST (submit) and GET
(retrieval) functions.
Testing in the API is required prior to receiving a production account. Please
contact OSTI: [email protected] to set up a test account with credentials.
Test E-link: https://www.osti.gov/elinktest/2416api
Prod E-Link: https://www.osti.gov/elink/2416api
A Graphics User Interface (GUI) for manual entry is available to low volume data
clients. Researchers should contact their site’s STI Manager to arrange for manual
submittal. Grantees can submit metadata for their datasets at:
https://www.osti.gov/elink/241-6.do?ostiid=0&action=load
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 2
1.1 General Requirements These general requirements have been established for data registration. The
Submitter must:
• Provide the required metadata to enable basic, bibliographic citation
• Have authority to make the data public, as data owner, PI, or other
designated submitter.
• Guarantee the persistence of registered data
o Ensuring that data are stored and managed for indefinite access and
usability
o Maintaining and updating all landing pages/URLs associated with the
DOI
OSTI does not currently provide a repository to store datasets.
1.2 Understanding Key Components Granularity is the level of depth represented by the data. High granularity means
a very focused detail, the most precision. Low granularity is a summary view of
data and transactions.
• Determining how DOIs should be applied to data is the first step in planning
data registration.
• DOIs can be assigned at varying granularity. The granularity of data is
dependent upon the type of data.
Datasets are not only numeric. A computer model/simulation, photographs,
graphics, interactive resources, and others, can also be datasets and therefore
receive DOIs.
Subject matter expertise and knowledge of how researchers recall data should
determine the appropriate level of granularity to assign the data.
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 3
The Digital Object Identifier (DOI) Each OSTI data client receives a numeric prefix from DataCite, which is specific to
that data client.
A DOI prefix begins with 10.XXXX, where XXXX is a series of numbers.
(See Figure Below)
The Infix is optional and can be incorporated by the submitter. The infix can add
intelligence to the DOI by incorporating project-specific identification. The infix
has to contain 3-50 characters. Characters may not be spaces or forward slashes
(/).
The suffix is assigned by OSTI and is the OSTI ID. Every record processed through
OSTI receives an OSTI ID.
A DOI never changes but the URL/landing page associated with the DOI can
change. All DOIs are to be persistent, which means submitting organizations
should manage and update landing pages/URLs as needed for the DOI to properly
resolve.
Type or paste a DOI Name into the text box at: https://dx.doi.org/
The browser will take you to a web page (URL) associated with that DOI.
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 4
The Landing Page A landing page is an introductory page. A DOI points to a landing page (URL),
which links out to the dataset. A landing page should contain the following
information:
• Full citation of the data (including the DOI)
• Access information
• Links to software needed to open, view, download or analyze the data
• Update and version information
• Contact information
2.0 Using the DOE Data ID Service API
Introduction The E-Link 241.6 API provides a REST service to both access existing E-Link
metadata, both individual datasets and collections and submit new records or
update existing records.
The API is built on a REST architecture, providing predictable URLs that make
wiring applications easy. The API is HTTP-based and can be accessed using a wide
variety of clients (Postman; HTTP Requestor; Restlet API, etc); most examples are
illustrated using the cURL command to demonstrate basic use cases. (Please see
below for examples).
2.1 Authentication The E-Link 241.6 API requires basic authentication to access and post records or
updates to the service. An existing E-Link account allows access to site records.
Please contact E-Link support for account set up. [email protected] or 865-
576-4070.
API authentication may be passed using the basic HTTP “Authentication” header,
or via the u-switch if using the command-line cURL tool.
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 5
2.2 HTTP Methods The E-Link 241.6 API uses the HTTP verb (method) associated with the incoming
request to identify the type of action being performed. GET requests obtain
information on existing metadata records, while POST is used to submit both new
records and updates to existing records in E-Link.
Request Methods
Method Description
GET Used for retrieving existing metadata records
POST Used for creating new metadata and updating existing
records
PUT Typically used for updating resources
Not currently used by E-Link API requests
DELETE Typically used for deleting resources
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 6
Not currently used by E-Link API requests
2.3 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 used, in RFC 1123 format
Content-Type The mime type in which the response data is formatted
X-Total-Count For responses containing data, the number of records
returned in the current response
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 7
2.4 Pagination Request that return multiple records will be paginated to 25 records by default;
the number of records per page can me modified by specifying a numerical value
for the ?rows parameter, and the specific page with the ?page parameter (default
0).
Query Parameter Values
Name Description
rows Maximum number of desired rows per page, default 25
page Page number of results, if maximum exceeds the rows parameter.
Numbering starts from 0
2.5 Record Model Responses returning data will return the same basic structure, formatted as
appropriate for the content type requested.
HTTP Status Codes
A successful response from the API will always return an HTTP status code of 200.
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 8
HTTP Success Status
Status Description
200 Ok
Record Fields—Highlighted Fields are Required
Results are always presented as a list of data defined as <record> elements
wrapped in a <records> container. The attributes start will indicated the index of
the first record in this set; rows indicates the number of rows per page, and
numfound represents the total number of rows found.
Record Fields
Field Name Description
osti_id The unique OSTI identifier for the record.
Required for updates
dataset_type Type of the main content of the dataset. Codes
listed below*
title Full title of the dataset with version numbers and
date ranges if applicable
creatorsblock Detailed set of information for person(s)
responsible for creation of the data set content.
Allows transmission of ORCID information and
more detailed affiliations
creators_detail Detail information about a single creator,
wrapped in the <creatorsblock> set above. (see
below)
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 9
product_nos The most important identifying numbers given to
the dataset by the host or originating
organization. Multiple values are separated by a
semicolon
contract_nos Primary DOE contract number(s), multiple values
may be separated by semicolon
originating_research_org If credited, the organization name primarily
responsible for conducting the research
publication_date The dataset publication date, in mm/dd/yyyy,
yyyy, or yyyyMonth format
language The primary language of the dataset
country The country of publication for this dataset
sponsor_org If credited, the organization name that
sponsored/funded the research
site_url Full URL to the “landing page” for the dataset
contact_name Name of a contact person for this dataset
contact_phone Phone number for the contact
contact_email Email address for the contact
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 10
site_input_code The Site code that owns this particular data set;
will default to logged-in user’s primary Site if not
set. User must have appropriate privileges in E-
Link to submit records for this Site
accession_num Site specific unique identifier for this dataset
contributors Set of contributor(s) to the dataset content, with
contribution roles
contributor Information about a particular contributor to the
dataset content, with attribute contributorType
specifying type of contribution (see below)
other_identifying_numbers Any alternative identifying numbers for this
dataset
subject_categories_code A two digit code and its controlled vocabulary
term(s) that indicated the main topic subject of
the dataset’s content. For codes, vocabulary and
detailed definitions, see Subject Categories
Authority at https://www.osti.gov/elink/authorities.jsp
keywords Words or phrases relevant to this data set.
Multiple values may be separated by a semicolon
and following a space
description A short description or abstract
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 11
doi Put a value in this field ONLY if the DOI has
already been assigned by an organization other
than OSTI
file_extension File format pertaining to the dataset
software_needed Any supplemental software programs needed to
view/analyze the dataset
ataset_size Indicated the approximate size in number of files,
megabytes or other appropriate metrics relevant
to the dataset
doi_infix If present, the site-selected DOI infix
“Intelligence” for a new DOI
set_reserved If a DOI is needed BEFORE the dataset and its
landing page are available on the host website,
use this tag to SAVE or RESERVE a DOI value. This
will not be transmitted to DataCite, nor will it be
resolvable until later updated without this tag
othnondoe_contract_nos Any non-DOE award numbers associated with this
dataset
relidentifierblock Set of related identifiers for this data (see below)
geolocations Set of geolocation data, if any, for the dataset
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 12
product_type The product type of the record (one of “DA” for
“dataset” or “DC” for “Collection”; (see below)
entry_date The date the record was added or last modified, in
ISO-8601 format, generated by the system
date_first_submitted Date first sent to OSTI, administrative purposes
only
date_last_submitted Date most recently submitted to OSTI,
administrative purposes only
Creators/Contributors
Creators and Contributors Fields
Field Name Description
first_name Author’s first, or given, name
middle_name Author’s middle name or initial
last_name Author’s last, or family, name
affiliation_name An affiliation, if entered
private_email Author’s email address
orcid_id Author’s ORCID, if supplied
contributorType The contribution type, attribute exclusive to contributors
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 13
Contributor Type Codes
Code Definition
ContactPerson Person with knowledge of how to access, troubleshoot,
or otherwise field issues related to the dataset
DataCollector Person/institution responsible for finding or gathering
data under the guidelines of the author(s) or Principal
Investigator
DataCurator Person tasked with reviewing, enhancing, cleaning or
standardizing metadata and the associated dataset
submitted
DataManager Person (or organization with a staff of data mangers,
such as a data center) responsible for maintaining the
finished resource
Distributor Institution tasked with responsibility to
generate/disseminate copies of the resource in either
electronic or print form
Editor A person who oversees the details related to the
publication format of the resource
HostingInstitution The organization allowing the resource to be available
on the internet
Producer Person or Organization responsible for the artistry and
form of media product
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 14
ProjectLeader Person officially designated as head of project team
instrumental in the work necessary to develop the
resource
ProjectManager Person officially designated as manager of a project.
Project may consist of one or many project teams and
sub-teams
RegistrationAgency Institution officially appointed by a Registration
Authority to handle specific tasks within a defined area
of responsibility
RegistrationAuthority A standards-setting body from which Registration
Agencies obtain official recognition and guidance
RelatedPerson Person with no specifically defined role in the
development of the resource, but who is someone the
author wishes to recognize
Researcher A person involved in analyzing data or the results of an
experiment or formal study
ResearchGroup Refers to a group of individuals with a lab, department
or division; the group has a particular, defined focus of
activity
RightsHolder Person or institution owning or managing property
rights, including intellectual property rights over the
resource
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 15
Sponsor Person or organization that issued a contract or under
the auspices of which a work has been performed
Supervisor Designated administrator over one or more groups
working to produce a resource or over one or more
steps of development process
WorkPackageLeader A Work Package is a recognized data product, not all of
which is included in publication
Other Any person or institution making a significant
contribution, but whose contribution does not “fit”
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 16
Dataset Type Codes
Code Definition
AS Animations/Simulations
GD Genome/Genetic Data (such as gene sequences)
IM Interactive data maps, such as GIS data and/or shape
files
ND Numeric Data
IP Still images or photos
FP Figures/Plots, charts and diagrams
SM Specialized Mix of differing data types
MM Multimedia, such as videos of experiments
Related Identifier Details
Tag Purpose/Description
relidentifier_detail Tag encapsulating a single related identifier value
related_identifier The DOI of the related source
relation_type A code specifying the type of relation between this
identifier and the parent dataset
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 17
related_identifier_type The type of identifier, usually a DOI
Related Identifier Types
Code Description
DOI The related identifier is a DOI
URL The related identifier is a URL
Relation Types
Code Description
Cites Indicates that A includes B in a citation
Compiles Indicates B is the result of a compilation or
creation event using A
Continues Indicates A is a continuation of the work B
Documents Indicates A is documentation about B
HasMetadata Indicates resource A has additional metadata B
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 18
HasPart Indicates A includes the part B
IsCitedBy Indicates that B includes A in a citation
IsCompiledBy Indicates B is used to compile or create A
IsContinuedBy Indicates A is continued by the work B
IsDerivedFrom Indicates B is a source upon which A is based
IsDocumentedBy Indicates B is documentation about A
IsIdenticalTo Indicates that A is the same as B; use when there
is a need to register tow separate instances of the
same resource
IsMetadataFor Indicates additional metadata A for a resource B
IsNewVersionOf Indicates A is a previous edition of B
IsOriginalFormOf Indicates A is the original form of B
IsPartOf Indicates A is a portion of B; may be used for
elements of a series
IsPreviousVersionOf Indicates A is a previous edition of B
IsReferencedBy Indicates A is used as a source of information by B
IsReviewedBy Indicates that A is reviewed by B
IsSourceOf Indicates that B is a source upon which B is based
IsSupplementedBy Indicates that B is a supplement to A
IsSupplementTo Indicates that A is a supplement to B
IsVariantFormOf Indicates A is a variant or different form of B, e.g.
calculated or calibrated form or different
packaging
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 19
References Indicates B is used as a source of information for A
Reviews indicates that A is a review of B
Geolocation Detail Information
Tag Purpose/Description
geolocations Wrapper tag for all geolocation data
geolocation Wrapper tag for each individual geolocation
dataset
place Optional description of geolocation data in text
form
polygon A set of points making up a closed arbitrary
polygon shape
boundingBox A square or rectangle shape defined by two sets
of latitude and longitude data points
point A single geolocation point, represented by latitude
and longitude values
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 20
2.6 Collections Model Collections are accumulations of already-existing dataset records at OSTI, grouped
together by specific project or purpose. While the submission type is similar,
fewer fields are required, and certain aspects of existing dataset records will be
accumulated.
In addition to specifying a <product_type>DC</product_type> tag, a collection is
expected to supply a set of <collection_items> as defined below.
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 21
Each <collection_item> will additionally be added to the Collection records as a
RELATED IDENTIFIER, of type “DOI,” with a relation type of “References.”
Note that when updating Collections records via API submission, any
<collection_items> specified will REPLACE the collection’s component items,
causing all field values to be re-calculated.
Field Description
product_type Value of “DC” indicates this record is a Data Collection
collection_items A set of <collection_item> values making up the
collection
collection_item Specify one of “DOI,” “osti_id” or “accession_num” as a
type attribute. The value of the <collection_item> will be
queried form existing OSTI data, and if found, will be
added to the collection
contributors As with dataset submissions, contributors may be
specified for this collection record, such as Researchers
or Data Managers
description An optional description of the collection, or its purpose
site_url A full URL to a landing page describing the collection,
with additional links to the other portions of relevant
data
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 22
Component datasets making up the collection will contribute itself as specified
here. Certain fields and values will be accumulated or calculated to make up the
information on the submitted collection record.
Field Use in the Collection Record
Publication Date The EARLIEST publication date found among the
collection items will be used as the publication date of
the collection.
Contract Numbers
Report Numbers
Sponsoring and
Research
Organizations These fields will be accumulated
Keywords and de-duplicated from the related
Languages fields in the collection items and
Authors used as the collection record’s
Country of Publication corresponding information.
Codes
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 23
2.7 Error Models If the API returns and 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 an XML parsing error or badly-formatted input
parameters or search query terms
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 24
401 Unauthorized
The user login supplied does not have sufficient privileges to access
the information requested, or to post records to E-Link.
404 Resource Not Found
Requested record or resource is not a file at OSTI
405 Method Not Allowed
PUT and DELETE methods are not currently implemented by E-Link
241.6 API
500 Internal Error
An internal software error or database failure has occurred
2.8 Endpoints
The E-Link 241.6 API currently supports a single endpoint, with the HTTP request
method (GET or POST) determining the appropriate action. GET requests are
information retrieval requests, while POST implies either new data creation or
updating of current datasets.
Record List (Search)
GET
The record list endpoint allows you to search for lists of records in E-
Link by a variety of criteria.
Record List Query Parameters
Parameter Description
osti_id The unique OSTI identifier for a record
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 25
title Searches within document titles
report_number Finds records based on report number
doi Search by a specific DOI
site_unique_id Search by site specific unique identifier, or
accession number value
status Status of the records; one of complete, pending or
saved
publication_date_from Starting publication date. All dates may be
expressed in YYYY-MM-DD or MM/DD/YYYY
format
publication_date_to Ending publication date
submit_date_from Starting last submission date of records
submit_date_to Ending last submission date
rows The number of rows per page to return (default
25)
page The specific page of records to return (default 1)
Data Submission
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 26
POST
Records may be submitted in XML format as defined above via a POST request
made to the same endpoint. Updates to existing records must include the
<osti_id> tag value of the record to be updated, while new records should omit
the tag to get a newly assigned ID.
If no DOI tag is specified for a dataset record, one will be assigned and posted to
the DataCite DOI registry based on the OSTI ID and any user-supplied <doi_infix>
tag optionally presented. DOIs will be of the form: {site-specific-prefix}/{user-
supplied-doi-infix}/{osti_id}
The service will respond with a summary of the submissions upon posting, with a
status of SUCCESS or FAILURE for each submitted record in the order they were
submitted.
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 27
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 28
Frequently Asked Questions (FAQs)
1. Can I submit more than one record at a time?
Yes, you may submit up to 25 records per POST.
2. What does the code look like for submitting more than 1 record per
POST?
Start the xml with the <records> tag. That parent folder will contain
<record> tag(s) for each record in the batch.
<?xml version="1.0" encoding="UTF-8"?>
<records>
<record>
<osti_id>{osti id}</osti_id>
<title>Blodgett Forest Warming Experiment 1</title>
<description>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam rhon
cus neque in molestie tempor. Integer in orci eu augue sodales semper. Sed fringilla q
uam nec velit sollicitudin fermentum. </description>
<authors>
<author>ac viverra mauris. Duis aliquam blandit nibh, ut maximus nisl congue
nec. (ORCID:00000000000)</author>
<author>ac viverra mauris</author>
<author>Duis lacus neque</author>
<author>faucibus arcu</author>
</authors>
<product_type>Dataset</product_type>
<doi>10.17040/ISCN/{osti id}</doi>
<publication_date>2017-03-24T04:00:00Z</publication_date>
<publisher />
<country_publication>United States</country_publication>
<format>Medium: ED</format>
<language>English</language>
<availability />
<research_orgs>
<research_org>ullamcorper lobortis augue. Cras convallis hendrerit nunc in pu
lvinar (tellus)</research_org>
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 29
</research_orgs>
<sponsor_orgs>
<sponsor_org>ex quis, ornare odio. Vivamus condimentum elit turpis, hendrerit
aliquet massa dignissim vitae (ABC) (123)</sponsor_org>
</sponsor_orgs>
<subjects />
<doe_contract_number>AC02-05CH11231</doe_contract_number>
<report_number>None</report_number>
<entry_date>2017-03-21T04:00:00Z</entry_date>
<links>
<link rel="citation" href="https://www.osti.gov/dataexplorer/biblio/{osti id}
" />
<link rel="fulltext" href="https://www.osti.gov/dataexplorer/servlets/purl/{o
sti id}" />
</links>
<dataset_content_type>
<type>Specialized Mix</type>
</dataset_content_type>
</record>
<record>
<osti_id>123456</osti_id>
<title>Blodgett Forest cooling Experiment1</title>
<description>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Etiam rhon
cus neque in molestie tempor. Integer in orci eu augue sodales semper. Sed fringilla q
uam nec velit sollicitudin fermentum. </description>
<authors>
<author>ac viverra mauris. Duis aliquam blandit nibh, ut maximus nisl congue
nec. (ORCID:00000000000)</author>
<author>ac viverra mauris</author>
<author>Duis lacus neque</author>
<author>faucibus arcu</author>
</authors>
<product_type>Dataset</product_type>
<publication_date>2017-03-24T04:00:00Z</publication_date>
<publisher />
<country_publication>United States</country_publication>
<format>Medium: ED</format>
<language>English</language>
<availability />
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 30
<research_orgs>
<research_org>ullamcorper lobortis augue. Cras convallis hendrerit nunc in pu
lvinar (tellus)</research_org>
</research_orgs>
<sponsor_orgs>
<sponsor_org>ex quis, ornare odio. Vivamus condimentum elit turpis, hendrerit
aliquet massa dignissim vitae (ABC) (123)</sponsor_org>
<subjects />
<doe_contract_number>AC02-05CH11231</doe_contract_number>
<report_number>None</report_number>
<entry_date>2017-03-21T04:00:00Z</entry_date>
<links>
<link rel="citation" href="https://www.osti.gov/dataexplorer/biblio/{osti id}
" />
<link rel="fulltext" href="https://www.osti.gov/dataexplorer/servlets/purl/{o
sti id}" />
</links>
<dataset_content_type>
<type>Specialized Mix</type>
</dataset_content_type>
</record>
</records>
3. If I submit multiple records together, will OSTI tell me the specific records
that have errors?
Yes, OSTI will return error codes attached to the OSTI IDs of the records.
You will have to perform a GET request using the OSTI ID to make edits to
those records.
4. What is the format for ORCIDs?
<orcid_id>1234567887654321</orcid_id>
Use the 16-digit number only. Do not use hyphens.
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 31
5. A DOI was minted for a dataset that already has a DOI (duplicate). Can the
new DOI be deleted?
No, because a DOI is a persistent identifier, it can never be deleted. OSTI
can “hide” the DOI so it will not appear in OSTI output products.
6. The dataset I submitted is no longer (publicly) available. What should I
do?
You should create a “tombstone” page. A “tombstone” page alerts the user
that the dataset did reside on the page, but is no longer (publicly) available.
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 32
Appendices
Appendix A1: DOE Data ID Service Metadata The following table lists the required and optional metadata fields, XML tags and
the related business rules. Records submitted without required fields will result in
a FAILURE notification.
*OSTI ID—an OSTI ID is given to a new record (POST). The OSTI ID is in the suffix
of the DOI. Use </osti_id> only when using GET function; when editing/updating
the existing record.
Metadata Schema
Required fields Shaded Field Name and XML Tag Additional Information
1* OSTI ID </osti_id>
New records are assigned an OSTI ID in the suffix. To edit/update records, you must include the </osti_id> tag
2 Dataset Type </dataset_type>
Main content of the dataset; AS—Animations/Simulations GD—Genome/Genetic Data IM—Interactive Data Map ND—Numeric Data IP—Still Images/Photos FP—Figures/Plots SM—Specialized Mix MM—Multimedia Ex: <dataset_type>ND</dataset_type>
3 Dataset Title </dataset_title>
Full title of the dataset
4 Creator(s)/Principal Investigator(s)/Authors <creatorsblock>
<creatorsblock> <creators_detail>
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 33
<creators_detail> <first_name></first_name> <middle_name></middle_name> <last_name></last_name> <affiliation_name></affiliation_name> <private_email></private_email> <orcid_id></orcid_id> </creators_detail> </creatorsblock>
<first_name>J.</first_name> <middle_name>Robert</middle_name> <last_name>Oppenheimer</last_name> <affiliation_name>UCBerkeley</affiliation_name> <private_email>[email protected]</private_email> <orcid_id>0000000000000000</orcid_id> </creators_detail> </creatorsblock>
5 Dataset Product Number(s) </product_nos>
Identifying number; “none” is acceptable
6 DOE Contract Number(s) </contract_nos>
Omit “DE” from contract number
7 Originating Research Organization </originating_research_org>
See: https://www.osti.gov/elink/authorities.jsp For a list of Originating Research Organizations. Multiple organizations can be listed, separated by a semicolon and a space.
8 Publication/Issue Date </publication_date>
Accepted formats:
• mm/dd/yyyy
• yyyy
9 Language </language>
Default to English. See: https://www.osti.gov/elink/authorities.jsp for other language values
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 34
10 Country of Origin/Publication </country>
Default to U.S.; See: https://www.osti.gov/elink/authorities.jsp for other values
11 Sponsoring Organization(s) </sponsor_org>
See: https://www.osti.gov/elink/authorities.jsp for values Multiple organizations can be listed, separated by a semicolon and a space.
12 Site URL </site_url>
URL that links to the landing page or dataset
13 Contact Name and Position </contact_name>
Internal tag for OSTI records only; will not display in public
14 Contact e-mail </contact_email>
Internal tag for OSTI records only; will not display in public
15 Contact phone </contact_phone>
Internal tag for OSTI records only; will not display in public
16 Site Code </site_input_code>
Identifies the program/project from where the data comes. <site_input_code>DRHUB</site_input_code>
17 Site Accession Number </accession_num>
18 Contributor(s) </contributors> </contributor> </first_name> </last_name> </affiliation_name> </contributorType> </private_email> </orcid_id>
Example: <contributors> <contributor> <first_name>J.</first_name> <last_name>Oppenheimer</last_name> <affiliation_name>UCBerkeley</affiliation_name> <contributorType>Researcher</contributorType> <private_email>[email protected] <orcid_id>0000-0000-0000-0000</orcid_id> </contributor>
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 35
</contributors> *See below for Contributor Types
19 Other Identifying Number(s) </other_identyfing_numbers>
Any numbers that identify the data. Separate multiple values by a semicolon and a space.
20 Subject Categories </subject_categories_code>
See : https://www.osti.gov/elink/authorities.jsp for values. Separate multiple values by a semicolon and a space.
21 Keywords </keywords>
Words or phrases to describe the dataset. Separate multiple values by a semicolon and a space.
22 Description </desctiption>
Define the content of the dataset.
23 DOI </doi>
Use only if dataset has a DOI.
24 Dataset File Extension </file_extension>
Ex. .txt; .csv; .ps…
25 Software needed to utilize the dataset </software_needed>
Software tools required to utilize the dataset.
26 Dataset Size </dataset_size>
Indicate file size.
27 DOI Infix </doi_infix>
Character string decided on by submitter. <50 characters; no spaces or / Ex: <doi_infix>Project1.3</doi_infix> Results in: 10.1234/Project1.3/123456
28 Set Reserve </set_reserve>
This puts DOI minting in SAVED status.
29 Other non-DOE Number(s) </non-doe_contract_nos>
Any numbers relevant but not associated with DOE. Separate multiple values by a semicolon and a space.
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 36
30 Related Identifier(s) <relidentifersblock> <relidentifer_detail> <related_identifier_type> <relation_type> </ relidentifer_detail> </ relidentifersblock>
DOI is used as the related identifier of the dataset. A controlled vocabulary list expresses the relationship. Please see Appendix for controlled vocabulary. Ex: <relidentifersblock> <relidentifer_detail> <related_identifier_type>DOI</related_identifier_type> <related_identifer>10.1234/Project1.3/123456</related_identifier> <relation_type>IsPreviousVersionOF</ relation_type> </ relidentifer_detail> </ relidentifersblock> In this example, the dataset being submitted is a previous version of another dataset that has received a DOI.
31 Geolocation Place Name <geolocations> <geolocation> <place></place> </geolocation> </geolocations>
Name of the place where the data were collected. Ex: <geolocations> <geolocation> <place>OakRidge</place> </geolocation> </geolocations>
32 Geolocation Point (longitude and latitude)
Ex: <geolocations>
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 37
<geolocations> <geolocation> <point latitude=”number”longitude= ”number”> </geolocation> </geolocations>
<geolocation> <point latitude= “36.0104”longitude=”84.2696”> </geolocation> </geolocations>
33 Geolocation Bounding Box <geolocations> <geolocation> <boundingBox> <northLatitude> <southLatitude> <eastLongitude> <westLongitude </geolocation> </geolocations>
Expressing 4 Points results in a square (box). Ex: <geolocations> <geolocation> <boundingBox> <northLatitude>+36.067428</northLatitude> <southLatitude>-35.849496</ southLatitude> <eastLongitude>+83.688549</ eastLongitude> <westLongitude>-84.161622</ westLongitude> </boundingBox> </geolocation> </geolocations>
34 Geolocation Polygon <polygon>
Irregular geolocation. 3 or more points. Ex: <geolocations> <geolocation> <polygon> <point latitude= “36.597”longitude=”-81.606”> <point latitude= “36.650”longitude=”-88.044”> <point latitude= “36.491”longitude=”-88.066”>
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 38
<point latitude= “36.456”longitude=”-89.450”> <point latitude= “34.994”longitude=”-90.353”> </polygon> </geolocation> </geolocations>
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 39
Appendix A2: Metadata Fields Controlled List Values
ContributorType is a mandatory field. The options for contributor
include all of the following:
• ContactPerson
• DataCollector
• DataCurator
• DataManager
• Distributor
• Editor
• HostingInstitution
• Producer
• ProjectLeader
• ProjectManager
• ProjectMember
• RegistrationAgency
• RegistrationAuthority
• RelatedPerson
• Researcher
• ResearchGroup
• RightsHolder
• Sponsor
• Supervisor
• WorkPackageLeader
• Other
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 40
Related Identifiers is an optional field, which is utilized to create collections
of Scientific and Technical Information (STI). The controlled vocabulary
below, is used to show the relation A ↔ B.
Related Identifier Controlled Vocabulary:
• IsCitedBy
• Cites
• IsSupplementTo
• IsSupplementedBy
• Continues
• HasMetadata
• IsMetadataFor
• IsNewVersionOf
• IsPreviousVersionOf
• IsPartOf
• HasPart
• IsReferencedBy
• References
• IsDocumentedBy
• Documents
• IsCompliedBy
• Compiles
• IsVariantFormOf
• IsOriginalFormOf
• IsIdenticalTo
• IsReviewedBy
• Reviews
• IsDerivedFrom
• IsSourceOf
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 41
*Definitions for the ContributorType and RelatedIdentifer controlled vocabulary
list can be found at:_https://schema.datacite.org/meta/kernel-4.1/doc/DataCite-
MetadataKernel_v4.1.pdf
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 42
Appendix A3: Special Functionalities Creating a Unique DOI Infix
Identifying a specific project/instrument/research group/etc., use the tag:
</doi_infix> with the specific identifier you would like to express.
Example:
<doi_infix>MyProjectName</doi_infix>
Added to the required metadata fields will result in a DOI like this:
10.1234/MyProjectName/123456
If no </doi_infix> is submitted, the same metadata submission will result in
a DOI like this:
10.1234/123456
Reserving a DOI
DOIs may be reserved for pre-publication reasons. To reserve a DOI, use the
tag:
</set_reserved>
This will give you a DOI but it will be placed in a “Saved” status, therefore it
will not resolve at https://dx.doi.org
Example: <set_reserved>true</set_reserved>
When the reserved DOI needs to be minted, simply resubmit the metadata,
including the OSTI ID and the DOI </doi> tag and omitting the
</set_reserved> tag
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 43
Versioning: Submitting Versions of Datasets
DataCite recommends that a new DOI be registered when a major version change
occurs. There are two ways to ways to ensure that users know which version of a
dataset is being retrieved.
1. Include the version number as a part of the dataset title.
2. Provide a version number/identifier in the infix of the DOI.
Using Related Identifiers fields in a metadata record enables versions, associated
software, journal articles, etc. to be associated with the retrieved dataset. Up to
20 related DOIs and their relationships can be included in the metadata record.
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 44
Example Record:
HTTP/1.1 200 OK
Content-Type: application/xml
<records start="0" rows="25" numfound="5334">
<record status="Pending" released="N">
<osti_id>1318659</osti_id>
<dataset_type>SM</dataset_type>
<title>Title of the data set</title>
<creatorsblock>
<creators_detail>
<first_name>Author</first_name>
<last_name>One</last_name>
<private_email>[email protected]</private_email>
</creators_detail>
<creators_detail>
<first_name>Author</first_name>
<last_name>Two</last_name>
</creators_detail>
<creators_detail>
<first_name>Author</first_name>
<last_name>Three</last_name>
</creators_detail>
</creatorsblock>
<contributors>
<contributor contributorType="DataCurator">
<first_name>Testing</first_name>
<last_name>Guy</last_name>
</contributor>
</contributors>
<related_resource>Related Resource information</related_resource>
<product_nos>product-001</product_nos>
<product_type>DA</product_type>
<contract_nos>DOE-CONTRACT-001</contract_nos>
<other_identifying_numbers>01234</other_identifying_numbers>
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 45
<originating_research_org>A Research University (United States)</originating_researc
h_org>
<availability>Direct paper publishing information</availability>
<contributor_organizations>Contributions Unlimited, LLC.</contributor_organizations>
<publication_date>2014</publication_date>
<language>English</language>
<country>US</country>
<site_input_code>OSTI</site_input_code>
<sponsor_org>USDOE Office of Science (SC)</sponsor_org>
<subject_categories_code>Testing; Software; Data</subject_categories_code>
<keywords>Data Sources; Measuring; Scientific Method</keywords>
<accession_num>123456789</accession_num>
<description>A simple abstract description of the data set and its research informat
ion.</description>
<relidentifiersblock>
<relidentifier_detail>
<related_identifier>10.5072/0007</related_identifier>
<related_identifier_type>DOI</related_identifier_type>
<relation_type>IsPreviousVersionOf</relation_type>
</relidentifier_detail>
<relidentifier_detail>
<related_identifier>10.5072/journal.2007.01529.x</related_identifier>
<related_identifier_type>DOI</related_identifier_type>
<relation_type>IsCompiledBy</relation_type>
</relidentifier_detail>
</relidentifiersblock>
<geolocations>
<geolocation>
<place>In the Australian Outback</place>
<point latitude="-22.839645" longitude="129.375000"/>
</geolocation>
</geolocations>
<date_first_submitted>2016-04-04</date_first_submitted>
<date_last_submitted>2016-04-04</date_last_submitted>
<doi status="PENDING">10.5072/DataScienceJournal/1318659</doi>
<doi_infix>DataScienceJournal</doi_infix>
<file_extension>xls</file_extension>
Manual Version 6.1, May 2018, www.osti.gov/dataexplorer/api/v1/docs#introduction 46
<software_needed>Excel or other spreadsheet software</software_needed>
<site_url>http://host.com/my_landing_page.html</site_url>
<dataset_size>50 GB</dataset_size>
<contact_name>Data User Services</contact_name>
<contact_org>OSTI</contact_org>
<contact_email>[email protected]</contact_email>
<contact_phone>888-241-5926</contact_phone>
<othnondoe_contract_nos>NonDOEAwardNumber001</othnondoe_contract_nos>
</record>
</records>