Documentation

Content negotiation

Through content negotiation you can request a single metadata record in a specified format. It is a service offered by several DOI registrations agencies (currently Crossref, DataCite, and mEDRA) through the DOI Foundation. It means that you don’t need to know where a DOI is registered in order to retrieve its associated metadata.

How to use content negotiation

Content negotiation is an API request where the format of the metadata returned is specified in the Accept header, for example (using cURL in a terminal):

curl -LH "Accept: application/rdf+xml" "https://doi.org/10.1126/science.1157784"

At Crossref, the following formats are available:

FormatAccept header value
Resource Description Framework (RDF)application/rdf+xml
Terse RDF Triple Language (Turtle)text/turtle
Citation style language (CSL)application/vnd.citationstyles.csl+json
Formatted citationtext/x-bibliography
Research Information Systems (RIS)application/x-research-info-systems
BibTeX citationapplication/x-bibtex
Crossref Deposit XML (UNIXREF)application/vnd.crossref.unixref+xml
Crossref Output XML (UNIXSD)application/vnd.crossref.unixsd+xml

The formatted citation format uses two additional headers to define the citation style and locale. A full list of citation styles, taken from the CSL repository, is available. Here is an example query: curl -LH "Accept: text/x-bibliography; style=bibtex; locale=en-US" "https://doi.org/10.1126/science.169.3946.635"

How does it work?

The DOI foundation runs an API that accepts content negotiation requests. It determines which registration agency holds the metadata and redirects the request (which is why -L is included in the examples above, to ensure that redirects are followed).

At Crossref, requests are handled by the transform route of the REST API, so

curl -LH "Accept: application/rdf+xml" "https://api.crossref.org/v1/works/10.1126/science.1157784/transform"

and

curl -LH "Accept: application/rdf+xml" "https://doi.org/10.1126/science.1157784"

give the same result. Using 10.23719/1531731, however, will not return a result in the first case because the DOI is registered with DataCite and not Crossref.

Advantages and limitations

Content negotiation is useful if you want to retrieve metadata in a commonly used format, such as BibTeX or RIS. It is also convenient for compiling references in a bibliography in accordance with a publisher style. The other big advantage of content negotiation is that it can retrieve metadata from several DOI registration agencies.

Note that content negotiation maps from multiple schema to multiple schema, which may use different field names and vocabularies and the mapping is not always direct. Sometimes several types are matched to a single field, or differ between registration agencies. For example, the Crossref types book, edited-book, and monograph map to the single RIS type book.

Only one record at a time is returned by content negotiation. For filtering and queries that return multiple metadata records, use the REST API.

Page owner: Martyn Rittman   |   Last updated 2025-March-17