What

At the moment of writing, OJS2 is a hopelessly obsolete version of Open Journal Systems CMS. Unfortunately, some people are stuck with it. In turn, Crossref is most likely the agency you register your DOIs with. Crossmark is their version of the "version control" for the digital documents such as articles. Through Crossmark, the major changes such as corrections/retractions can be tracked.

In this article, I explain how to correct the xml exported from OJS2 for depositing to Crossref, and also how to add the Crossmark information to the said xml.

Here is an example of the journal and article deposit xml (without Crossmark elements).

Let's assume you have your Crossref export plugin turned on and configured (there isn't much to configure anyway, basically just the contact name and email address), and that you've exported the issue xml via the plugin interface at 

https://OJS-ADDRESS/index.php/JOURNAL-NAME/manager/plugin/importexport/CrossRefExportPlugin/issues

Let's also assume that you've read all the official documentation on the Crossref website. This is not a complete guide, but rather a very brief description of my own experience of doing these things.

In the following sections, I will review in brief what's wrong with OJS2-generated xmls and how to deal with it. The later sections are devoted to the Crossmark peculiarities.

Title unescaping

Since some version of the Crossref schema, <sub>, <sup>, <i>, etc. tags are all supported by the Crossref, which fact has escaped the OJS2 plugin. The latter html-escapes all the tags in the titles. As a consequence, the titles should be unescaped, with &lt; converted to <, etc., etc.

Publisher items

If the journal is using the article numbering scheme as opposed to the traditional "first page - last page" one, Crossref recommends not to use the <first_page> tag (that OJS2 uses by default) to capture the article number, and to use something like

<publisher_item>
  <item_number item_number_type="article_number">...</item_number>
</publisher_item>

Hence the need to correct the original xml by removing the <pages> element altogether and replacing it with the above.

Citation lists

OJS2 doesn't support exporting and importing citation lists, like, at all. Even the import/export articles and issues plugin, which, if I'm not mistaken, even exports the graphical abstracts in the xml, has no capability of exporting citations. This is, to put it mildly, irritating. I ended up just grabbing the reference lists from the website, and pasting them in the xml below </doi_data> in, perhaps, the simplest way as

<citation_list>
  <citation key="ref1">
    <doi>...</doi>
  </citation>
  <citation key="ref2">
    <unstructured_citation>...</unstructured_citation>
  </citation>
  ...
</citation_list>

depending on whether the doi is present in or absent from the original citation. There are more complex <citation> formats (see here), but they require more extensive parsing of the original reference texts.

Timestamps

Yeah, this is why your perfectly (syntactically) valid xml could get rejected by Crossref. In order for the doi record to be updated, the integer inside the <timestamp> in the <head> of the <doi_batch> should be more than it was when the previous record with this particular doi was deposited. The easiest way of ensuring that is just by writing the unix time integer into the <timestamp> each time the xml is updated.

Adding Crossmark

There's a description of what is Crossmark and a step-by-step guide on how to participate in it. Regarding the latter, here I'm going to talk about steps two (here) and three (in the following section). The other ones are pretty straightforward; I can only mention that I found it convenient to use the free and crossplatform exiftool to update the pdf metadata.

Before we begin:

The basic <crossmark> element is, well, very basic:

<crossmark>
  <crossmark_version>1</crossmark_version>
  <crossmark_policy>...</crossmark_policy>
  <custom_metadata>
    <program xmlns="http://www.crossref.org/AccessIndicators.xsd">
      <free_to_read/>
      <license_ref applies_to="vor" start_date="YYYY-MM-DD">https://creativecommons.org/licenses/by/4.0/</license_ref>
    </program>
  </custom_metadata>
</crossmark>

Here, you only need to modify the crossmark policy doi (not the full url, just doi), YYYY-MM-DD that is basically the online-first date, license type, if you're using something else, and perhaps <free_to_read/> if you're with the greedy people. In the latter case, however, you wouldn't be reading this as you'd have a team of overpaid people at your beck and call solving all your problems and an office in, let's say, Switzerland) but enough of that. Only the date should be modified for each article, the others are journal-specific.

Maintaining Crossmark

This issue arises when an update to the already existing record should be registered. The "recommended way" of doing a major update of the article is by issuing an additional update note with its separate doi, and then link the update note to the original article via Crossmark. There are some examples on Crossref's website on registering updates with Crossmark.

I did the following. First, I limited the types of updates that we will implement to, perhaps, the most common ones: correction and retraction. Next, as the basic xml remains the same as shown above, the <crossmark> elements of the corrections and retractions should contain additional <updates> elements. For example,

for a correction, the whole <crossmark> would look like

<crossmark>
  <crossmark_version>1</crossmark_version>
  <crossmark_policy>...</crossmark_policy>
  <updates>
    <update type="correction" date="YYYY-MM-DD">DOI_OF_SOURCE_ARTICLE</update>
  </updates>
  <custom_metadata>
    <program xmlns="http://www.crossref.org/AccessIndicators.xsd">
      <free_to_read/>
      <license_ref applies_to="vor" start_date="YYYY-MM-DD">https://creativecommons.org/licenses/by/4.0/</license_ref>
    </program>
  </custom_metadata>
</crossmark>

and for a retraction - like

<crossmark>
  <crossmark_version>1</crossmark_version>
  <crossmark_policy>...</crossmark_policy>
  <updates>
    <update type="retraction" date="YYYY-MM-DD">DOI_OF_SOURCE_ARTICLE</update>
  </updates>
  <custom_metadata>
    <program xmlns="http://www.crossref.org/AccessIndicators.xsd">
      <free_to_read/>
      <license_ref applies_to="vor" start_date="YYYY-MM-DD">https://creativecommons.org/licenses/by/4.0/</license_ref>
    </program>
  </custom_metadata>
</crossmark>

I suppose that's all that is required. However, I went a bit further and added more links between the original articles and the notes. To the very beginning of <custom_metadata> elements, i.e. as their first children, the following elements could be added:

to either correction or retraction note:

<assertion group_name="associated_articles" group_label="ASSOCIATED ARTICLES" name="related_article" label="CrossRef DOI Link to Originating Article:" href="https://doi.org/DOI_OF_SOURCE_ARTICLE">https://doi.org/DOI_OF_SOURCE_ARTICLE</assertion>

to the source article (in case of correction):

<assertion group_name="associated_articles" group_label="ASSOCIATED ARTICLES" name="related_article" label="CrossRef DOI Link to Correction:" href="https://doi.org/DOI_OF_CORRECTION">https://doi.org/DOI_OF_CORRECTION</assertion>

to the source article (in case of retraction):

<assertion group_name="associated_articles" group_label="ASSOCIATED ARTICLES" name="related_article" label="CrossRef DOI Link to Retraction:" href="https://doi.org/DOI_OF_RETRACTION">https://doi.org/DOI_OF_RETRACTION</assertion>

Above, DOI_OF_SOURCE_ARTICLE, DOI_OF_CORRECTION and DOI_OF_RETRACTION are just dois, not urls.

And here's one more thing: the official guidelines state that in order to update the already deposited Crossmark, the xml deposition should be performed in two steps:

  1. the record in question should be deposited with the empty Crossmark element, <crossmark/>;
  2. the empty <crossmark/> should be replaced with the one containing the updated metadata, and the resulting xml record should then be deposited.

In my (quite limited though) experience, updating just in one step (skipping the 1st) works just as well. So, actually, Crossmark metadata seems to be updated just as any other Crossref metadata - by uploading the updated xml record with the most up-to-date data.

Metadata examples

Here are some Crossref API requests that allow you to see how the other people structure their (rather complex) doi records and Crossmark metadata. In order for the requests to work properly, you have to so that Crossref could identify the users and, for example, block the requests if they become problematic.

The API request results will appear here
Reference dump

Below are the unsorted related references