CROSSREF by ATYPON

version 1.0
Author: Hisham Shahtout - atypon systems Click here to download sample source code for submission uploads and online queries.

Introduction

The CrossRef system is a citation database. CrossRef member publishers upload metadata submissions. These metadata submissions are processed (parsed, indexed and stored in the database) by the CrossRef system. In addition to metadata submissions, the CrossRef system accepts query submissions which allow CrossRef users to extract DOI and/or metadata from the citation database.
Submissions are in two flavors:
  1. Asynchronous submissions: Users upload metadata or queries via an HTTP post, once the data is received by CrossRef, a 200 OK HTTP response is returned to the user and the submission is scheduled for processing on the CrossRef system. The result is sent to the user at a later stage via an email to an address that was specified in the submission.
  2. Synchronous submissions: Users submit queries via and HTTP POST or GET. The query is processed and results are returned as an HTTP response. Note that this option is available for query submissions only.

Asynchronous submission upload

The system accepts three types of Asynchronous submissions:
  1. metadata submissions: XML files that are in the legacy XML format (doi_batch.dtd) or in the new XSD format (crossref2.0.5.xsd).
  2. Query submissions: Submissions to resolve pipelined queries into DOIs
  3. DOIQuery submissions: Submissions to resolve DOIs into metadata.
Submissions are submitted using HTTP post with the encType: multipart/form-data , The URL for all submissions is 
doi.crossref.org/servlet/deposit
. The following parameters are expected in the URL:

Form field Description possible
values		 mandatory Default
operation Depends on submission type
  • doMDUpload: For metadata (DTD and XSD) submissions
  • doXSDMDUpload: same as doMDUpload
  • doDOICitUpload: For DOI citations submissions
  • doQueryUpload: For Query (Piped and XML) submissions
  • doDOIQueryUpload: For DOI query submissions
  • Submit Batch File: same as doMDUpload (for backward compatibility)
NO doMDUpload
subType subtype for metadata submissions NO N/A
login_id CrossRef supplied login N/A N/A
login_passwd CrossRef supplied password N/A N/A
area Designated area for this submission
  • live
  • test
NO live
Content parts
fname Submission contents N/A N/A

Important: The type of the metadata submission is determined automatically. If the submission contains the string doi_batch.dtd or doi_journal_article_v0_3.dtd then it is considered a DTD submission. Otherwise, the submission is considered an XSD submission and validated accordingly.

Here is an example of a query upload submission: 


    [Request to doi.crossref.org]
    POST http://doi.crossref.org/servlet/deposit?operation=doMDUpload&login_id=atypon&login_passwd=_atypon_&area=live HTTP/1.1
    Accept: image/gif, image/x-xbitmap, image/jpeg, image/pjpeg, application/vnd.ms-powerpoint, application/vnd.ms-excel, application/msword, */*
    Accept-Language: en-us
    Content-Type: multipart/form-data; boundary=---------------------------7d22911b10028e
    User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; Q312461)
    Host: Myhost
    Content-length: 1304
    Pragma: no-cache

    -----------------------------7d22911b10028e
    Content-Disposition: form-data; name="fname"; filename="hisham.xml"

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE doi_batch SYSTEM "doi_journal_article_v0_3.dtd">
    <doi_batch version="0.3">
    <head>
    <doi_batch_id>10.1037.1</doi_batch_id>
    <timestamp>1001</timestamp>
    <depositor>
    <name>Hisham Shahtout</name>
    <email_address>hisham@atypon.com</email_address>
    </depositor>
    <registrant>Atypon test pubisher</registrant>
    </head>
    <body>
    <doi_record type="full_text">
    <doi_data>
    <doi>1737/myhome</doi>
    <url>http://www.atypon.com</url>
    </doi_data>
    <journal_article_metadata>
    <article>
    <author sequence="first">
    <given_name>Roine</given_name>
    <surname>Stolt</surname>
    </author>
    <date type="online">
    <month>12</month>
    <day>12</day>
    <year>2000</year>
    </date>
    <date type="print">
    <year>0000</year>
    </date>
    <enumeration>
    <volume>0</volume>
    <issue>0</issue>
    <first_page>1</first_page>
    <last_page>3</last_page>
    </enumeration>
    </article>
    <journal>
    <full_title>Space Resolver</full_title>
    <abbrev_title>space res.</abbrev_title>
    <issn type="print">1234-431X</issn>
    </journal>
    </journal_article_metadata>
    </doi_record>
    </body>
    </doi_batch>

    -----------------------------7d22911b10028e--
The system returns a "200 OK" response as soon as the submission is received. That means that the submission has been received by CrossRef and is scheduled to be processed. The submission is put in a queue that is visible to authorized users at crossref's site. The results of the submission processing are sent to the email address specified in the submission as follows:

Note:

For backward compatibility. The system accepts the login_id,login_passwd,operation and area parameters as part in the multi-part request as follows. However, the recommended way is to supply these parameters in the URL request as outlined above 

    -----------------------------7d22911b10028e
    Content-Disposition: form-data; name="login_id"

    atypon
    -----------------------------7d22911b10028e
    Content-Disposition: form-data; name="login_passwd"

    _atypon_
    -----------------------------7d22911b10028e
    Content-Disposition: form-data; name="fname"; filename="hisham.xml"

    ... file content ...

Batch queries

The system supports legacy "batch queries" through the following URL:
/servlet/query?usr=<username>&pwd=<password>&type=<queryType>&format=<resultFormat>&qdata=<x-www-form-urlencoded queries>
where:

request field Description possible
values		 mandatory Default
usr* CrossRef supplied login N/A NO N/A
pwd* CrossRef supplied password N/A NO N/A
type Type of query
  • q : Metadata query
  • d : DOI query
NO Metadata query (q)
area Area for this query
  • live
  • test
NO live
fuzzy Enable/Disable all fuzzy matching
  • true
  • false
NO true
format Result format
  • piped : Piped format
  • xml : XML format
  • xsd_xml : XSD conforming XML format.
  • unixref : (Unified) CrossRef XML format.
    (Available for ECT and DOI queries only)
NO piped
qdata x-www-form-urlencoded query data N/A N/A

x-www-form-urlencoded encoding rules are the following:


If you are using java you can use the URLEncoder class to encode your qdata.

Notes:

Submission areas

As you may have noticed. Submissions can be associated with an area for which that submission is intended. The live area is visible to all publishers and DOI submissions into the live area are also registered with handle. DOI submissions to the test area on the other hand are not submitted to handle. Each submitter has his own private test area that he is supposed to use to develop his code. Queries into the submitter's test area are matched against metadata previously submitted for that submitter only. The test area should be used by developers to develop their code and test it against CrossRef. After the code has been tested against the submitters private test area, he can point it to the live area.

Downloading mddb.xml

The system allows you to download mddb.xml using the following URL:
servlet/mddbxml?usr=<login>&&pwd=<password>&format=<old|new>
where:

request field Description possible
values		 mandatory Default
usr* CrossRef supplied login N/A NO N/A
pwd* CrossRef supplied password N/A NO N/A
format Format of the result
  • old: Same as old CrossRef system.
  • new: Newer XML format
NO old


Download metadata

The system allows you to download metadata using the following URL:
/servlet/download?usr=<username>&pwd=<password>&fromId=<submissionId>&toId=<submissionId>&doiPrefix=<doiPrefix>&format=<resultFormat><validate=>
where:

request field Description possible
values		 mandatory Default
usr* CrossRef supplied login N/A NO N/A
pwd* CrossRef supplied password N/A NO N/A
fromId Starting submission ID N/A NO N/A
toId Ending submission ID N/A NO N/A
doiPrefix Prefix of CrossRef supplied DOI N/A NO N/A
format Result format
  • xml : XML format
  • id : Submission IDs only
NO IDs Only (id)
Validate Validate the XML
(If XML is not valid and empty result will be returned)
  • true
  • false
NO true

Tracking ID

It is possible to retreive the result of submission processing or the contents of a submission at any time through the following URL:
/servlet/submissionDownload?usr=<username>&pwd=<password>&doi_batch_id=<doi_batch_id&file_name=<file_name>&type=<type>
where:

request field Description possible
values		 mandatory Default
usr* CrossRef supplied login N/A NO N/A
pwd* CrossRef supplied password N/A NO N/A
doi_batch_id The DOI batch id as supplied by the publisher in the submission XML. N/A NO N/A
file_name The file name under which the submission was submitted N/A NO N/A
type The type of data requested
  • result: Retreive the result of the submission processing.
  • contents: Retreive the contents of the submission.
N/A

You can track a submission by its doi_batch_id or by its file_name. In either case, only the first match is returned. So in order to use this feature effectively it is the publisher's responsibility to make sure that their tracking IDs ( doi_batch_id or file_name) is unique.
The main difference between using doi_batch_id and file_name is that doi_batch_id is inserted into the database after the submission has been parsed. This might be a problem for submissions that are non-parsable.

file_name is more superior in the sense that:

  1. Non parsable submissions can be tracked.
  2. Submissions that are in queue or in process can also be tracked.
when type='result' the result is returned in md_process_result1.0.dtd format.

Stored Queries

Users can retreive a list of stored queries that resolved within a date range using the following URL: 
/servlet/downloadStoredQueries?usr=<username>&pwd=<password>&startDate=<startDate>&endDate=<endDate>
where:

request field Description possible
values		 mandatory Default
usr* CrossRef supplied login N/A NO N/A
pwd* CrossRef supplied password N/A NO N/A
startDate The start date of a date range (inclusive). Must be formatted as yyyy-mm-dd. N/A NO N/A
endDate The end date of a date range (inclusive). Must be formatted as yyyy-mm-dd N/A NO N/A

The result is returned in XML format that conforms with the XSD for CrossRef's XML query output.


Forward Links

Users can retreive a list of DOIs that cite a specific DOI using the following URL 
/servlet/getForwardLinks?usr=<username>&pwd=<password>&doi=<doi>&startDate=<startDate>&endDate=<endDate>
where:

request field Description possible
values		 mandatory Default
usr* CrossRef supplied login N/A NO N/A
pwd* CrossRef supplied password N/A NO N/A
DOI The cited DOI N/A N/A
startDate The start date of a date range (inclusive, formatted as yyyy-mm-dd).
Only reference relationships created on or after this date are returned.		 N/A NO N/A
endDate The end date of a date range (inclusive, formatted as yyyy-mm-dd).
Only reference relationships created on or before this date are returned.		 N/A NO N/A

The result is returned in crossref_query_output2.0.xsd compliant XML format.


Downloading conflicts

Users can retreive a list of unresolved conflicts that belong to a certain prefix using the following URL: 
/servlet/downloadConflicts?usr=<username>&pwd=<password>&prefix=<prefix>&displayMD=<true|false>
where:

request field Description possible
values		 mandatory Default
usr* CrossRef supplied login N/A NO N/A
pwd* CrossRef supplied password N/A NO N/A
prefix Restrict conflicts for a specific DOI prefix N/A NO - if not supplied then all prefixes the user is authorized to submit metadata for are returned N/A
displayMD Display DOI <metadata> under the <doi_data> element
  • true
  • false
 NO false

The result is returned in XML which list the conflicts along with the DOIs in each conflict as follows:

<conflict_list> <conflict id="42061"> <doi_data> <doi>10.5555/test3</doi> <other_conflicts> <conflict id="42063" /> </other_conflicts> </doi_data> <doi_data> <doi>10.5555/test4</doi> </doi_data> </conflict> <conflict id="42063"> <doi_data> <doi>10.5555/test1</doi> </doi_data> <doi_data> <doi>10.5555/test2</doi> </doi_data> <doi_data> <doi>10.5555/test3</doi> <other_conflicts> <conflict id="42061" /> </other_conflicts> </doi_data> </conflict> </conflict_list>


Note:* that login/password are optional because CrossRef might have enabled you access through IP authentication.

© 2000-2003 PILA, Inc.
Software based on the LiteratumTM platform from Atypon systems