JSON schema for content negotiation

I’m currently retrieving CrossRef and DataCite metadata from doi org using content negotiation, as documented in the DOI content negotiation guide.

A couple of questions:

  • Is it possible to get the output from the REST API using content negotiation at doi org? The main advantage of using content negotiation is that I don’t have to do a preliminary test to see whether the doi I’m fetching the metadata for is registered with CrossRef or with DataCite.

  • I would like to see the schema used for the citeproc JSON output so I can write a generic parser. It doesn’t seem to be the schema used by the REST API; can you point me to the appropriate documentation?


1 Like

From further searching of documentation, gitlab, etc., it appears that the REST API does serve the JSON response when using content negotiation. However, the models documented in the swagger docs (at api_crossref_org/swagger-ui/index.html) don’t correspond to the data returned by the API. E.g. the works/{doi} endpoint returns content with award and project keys in the object under the message key, but those keys don’t exist in the Works model that you get if you click on the “Model” link in the example response.

Are the correct models available somewhere?

Hi @ialarmedalien ,

Thanks for your questions, and welcome to the community forum.

Information on the award filter should be available to you in the swagger documentation. Do you see it here: Swagger UI

Do you have an example of project that you could provide so I can take a closer look?

We do not have a JSON output schema, although the Swagger documentation is thorough. I can say that the JSON output does map to our input schema: Schema documentation for crossref5.3.1.xsd

I’ve also noted your request for a JSON output schema in the JIRA issue we’re using to prioritize this potential, future work: [CR-529] - Jira.

Looking forward to hearing back from you,

After talking with others on the support team, we believe you might be asking about a grants example, like this one: https://0-api-crossref-org.pugwash.lib.warwick.ac.uk/works/10.46936/cpcy.proj.2019.50733/60006578

message, award, and project are all present in this output.

This documentation - the grants markup guide - should be helpful: Grants markup guide - Crossref

Take a look and let me know if you have follow-up questions,

Hi @ifarley and thanks for the quick responses!

After talking with others on the support team, we believe you might be asking about a grants example, like this one: https //api crossref org/works/10.46936/cpcy.proj.2019.50733/60006578

The example you’ve given here is similar to what I’ve been looking at – a DOI representing a grant.
The data structure under message has keys including award (value: “50733”) and project (value: nested data structure that includes project-title and funding).

The documentation of the /works/{doi} endpoint has an example 200 response and the model (WorkMessage) for that response, with the value of the message key given as a Work model. If you expand the Work model to see the keys/values beneath it, neither the award key nor the project key exist, and several of the starred (presumably required) fields do not exist in the object under the message key from the API URL you provided.

I am writing a parser for the CrossRef API to map the output to my local schema. I have a list of DOIs to look up, and I won’t know in advance whether they represent grants, datasets, journal articles, etc., etc. I need to know what data structures the endpoint outputs so I can extract the appropriate information from the API response. If I build a parser that assumes that the output of the /works/{doi} endpoint is always structured as a Work, as documented at api crossref org/swagger-ui/index.html#model-Work, I’ll obviously miss all the funding info.

Thus my question is: how can a parser know, without human intervention, what schema the REST API output from /works/{doi} is using?

1 Like