Status: Published
Version: 1.1
License: this recommendation document is licensed under CC BY-ND 2.0 UK
Provenance
Version 1.0 reworked by Jeff Beck based on NISO taking CreDiT taxonomy. This was then reviewed by the JATS4R Steering Committee.
Change history
Version 1.0 can be found here here.
- Validator tool messages added
- URLs updated to new NISO site
Context
<contrib-group>, <contrib>, <role>
JATS 1.1 Attributes: @content-type
JATS 1.2 Attributes: @vocab, @vocab-identifier, @vocab-term, @vocab-term-identifier
Description
The CreDiT taxonomy provides a way to encode contribution information inside article XML files. The taxonomy identifies the specific nature of an individual’s contribution with respect to the research material at hand. The purpose of CRediT is to provide transparency in contributions to scholarly published work, to enable improved systems of attribution, credit, and accountability. The objective of this recommendation is to promote transparency of contribution information in article XML and to ensure that contribution types are encoded in a manner that is machine readable and optimized for reuse.
As of the publication of this recommendation, there are 14 types of contributions that can be applied to an individual contributor:
Table 1: CRediT terms and URLs
Multiple terms can be applied to a single contributor. For more information about the CreDiT taxonomy as well as the individual terms, please see: http://credit.niso.org/.
The <role> element may include information unrelated to CRediT, such as an individual’s position at work or job title. In such cases the decision of how to include that information should be left to individual organizations, however, care should be taken to ensure that no potential conflicts exist between the use of <role> for carrying CRediT information and its use otherwise (see XML example 5). Finally, it should be noted that this recommendation is specific to capturing CRediT information through the use of the <role> element. For guidance on capturing information about authors and their affiliations in article metadata, please refer to the JATS4R Authors and Affiliations recommendation. Also note that this recommendation does not address all possible uses of <role>, which will be addressed in a separate recommendation if warranted by sufficient interest. If you would be interested in participating in a subgroup dedicated to the use of <role> please email info@jats4r.org.
Additional reading
- NISO JATS 1.1 library
- NISO JATS 1.2d1 library
- NISO JATS Standing Committee recommended changes between NISO/JATS 1.1 and JATS 1.2d1
- ANSI/NISO Standard Z39.96-2015:
- CReDiT contributor roles
- Samples document (Google drive)
Recommendation
It is recommended that when including CrediT information in JATS XML, the JATS 1.2 DTD be used as it provides a more robust way of supporting the taxonomy, as demonstrated in the following recommendations. However, it is JATS4R’s mandate to be as inclusive as possible in order to accommodate the constraints of DTD versioning. Therefore, this recommendation defines two ways of tagging CRediT taxonomy in article XML, one using the JATS 1.1 DTD and the second using the JATS 1.2 DTD.
There may be a difference between the term inside the <role> element content, which is intended for display, and the term as it appears inside @vocab-term (JATS 1.2) or @content-type (JATS 1.1) and related attributes. In such cases JATS4R does not take a position on what is in the human readable display, as long as the taxonomy usage in the attribute(s) is correct as per the above recommendations.
- <role>. Each CRediT term must be included inside the <role> element, and each <role> element must only include one term. In cases where more than one CRediT term needs to be applied, the <role> element should be repeated. The <role> element must carry attributes as described below
JATS 1.2 and above - @vocab on <role> must always carry the value “credit”.
[[Validator tool result: if a @vocab-term or @vocab-term-identifier has a CRediT value (as specified above) and there is no @vocab= ‘credit’ ERROR]]
[[Validator tool result: if role element has none of the required attributes, but its value is one of the CRediT terms WARNING]] - @vocab-identifier on <role> must point to the URL for the general CRediT taxonomy
[[Validator tool result: if role with @vocab=’credit’ does not have a @vocab-identifier=’http://credit.niso.org/’ ERROR]] - @vocab-term on <role> must identify the particular CRediT term.
[[Validator tool result: if @vocab= ‘credit’ and @vocab-term value is not one of the CRediT terms specified above ERROR]] - @vocab-term-identifier on <role> must point to the URL of the specific CRediT term.
[[Validator tool result: if @vocab= ‘credit’ and @vocab-term-identifer value is not one of the CRediT URIs specified above ERROR]]
[[Validator tool result: if @vocab= ‘credit’ and @vocab-term-identifer value does not correspond to the @vocab-term value ERROR]]
1.2 DTD and below: - @content-type must point to the URL of the specific CRediT term.
[[Validator tool result: if @content-type value containing ‘credit.niso.org’ does not match one of the CRediT term URIs specified above ERROR]]
[[Validator tool result: if no @content-type and role element value is one of the CRediT taxonomy terms WARNING]]
Examples
Example 1: Value of the <role> element is identical to the value of the @vocab_term attribute (JATS 1.2 DTD and above)
<contrib-group>
<contrib>
<string-name>
<given-names>Dan</given-names>
<surname>Green</surname>
</string-name>
<role vocab="credit" vocab-identifier="http://credit.niso.org/"
vocab-term="Conceptualization"
vocab-term-identifier="http://credit.niso.org/contributor-roles/conceptualization/"
> Conceptualization</role>
</contrib>
<contrib>
<string-name>
<surname>Valanciunas</surname>
<given-names>Jonas</given-names>
</string-name>
<role vocab="credit" vocab-identifier="http://credit.niso.org/"
vocab-term="Writing - Original Draft"
vocab-term-identifier="http://credit.niso.org/contributor-roles/writing-original-draft/"
>Writing - Original Draft</role>
</contrib>
</contrib-group>
Example 2: Value of the <role> element different from value of the @vocab_term attribute (JATS 1.2 DTD and above)
<contrib-group>
<contrib>
<string-name>
<given-names>Patrick</given-names>
<surname>McCaw</surname>
</string-name>
<role vocab="credit" vocab-identifier="http://credit.niso.org/"
vocab-term="Investigation"
vocab-term-identifier="http://credit.niso.org/contributor-roles/investigation/"
>Data Collection</role>
</contrib>
<contrib>
<string-name>
<given-names>Fred</given-names>
<surname>Vanvleet</surname>
</string-name>
<role vocab="credit" vocab-identifier="http://credit.niso.org/"
vocab-term="Investigation"
vocab-term-identifier="http://credit.niso.org/contributor-roles/investigation/"
>Data Collection</role>
</contrib>
</contrib-group>
Example 3: Value of the <role> element when same value of the @content-type attribute (JATS 1.1 DTD and below)
<contrib-group>
<contrib>
<string-name>
<surname>Leonard</surname>
<given-names>Kawhi</given-names>
</string-name>
<role content-type="http://credit.niso.org/contributor-roles/conceptualization/"
>Conceptualization</role>
<role content-type="http://credit.niso.org/contributor-roles/data-curation/"
>Data curation</role>
<role content-type="http://credit.niso.org/contributor-roles/formal-analysis/"
>Formal analysis</role>
<role content-type="http://credit.niso.org/contributor-roles/investigation/"
>Investigation</role>
<role
content-type=" http://credit.niso.org/contributor-roles/writing-original-draft/"
>Writing – original draft</role>
</contrib>
</contrib-group>
Example 4: Value of the <role> element different from value of the @vocab_term attribute (JATS 1.1 DTD and below)
<contrib-group>
<contrib>
<string-name>
<surname>Boucher</surname>
<given-names>Chris</given-names>
</string-name>
<role content-type="http://credit.niso.org/contributor-roles/conceptualization/"
>Study Designer</role>
</contrib>
</contrib-group>
Example 5: Use of <role> for non-CRediT term
<contrib-group>
<contrib>
<string-name>
<given-names>Green</given-names>
<surname>Dan</surname>
</string-name>
<role vocab="credit" vocab-identifier="http://credit.niso.org/"
vocab-term="Conceptualization"
vocab-term-identifier="http://credit.niso.org/contributor-roles/conceptualization/"
> Conceptualization</role>
<role>Section Editor</role>
</contrib>
</contrib-group>
History
Committee working: September 2020
Published: September 21, 2020
The JATS validator at https://validator.jats4r.org/ returns an error (just the string “There was an error”) for all file uploads, including copies of the valid examples from this page.
Hi Lisa
Thank you for your feedback. Please can you send us an example XML file you were using to info@jats4r.org.
The validator requires a valid JATS document, it does not work for snippets of XML.
Thank you!
Melissa
Hello,
There seems to be issues with capitalisation of the credit terms (discrepancy between example and niso terminology).
also the use of space in the credit term, and “-” in the url makes it all (unnecessarily?) complicated.
As the term is only used for machine readability, I wonder if it should not be all lowcase, and without space. Or maybe it should simply disappear, and we keep only a PID. But then, we would indeed need a persistent identifier, not a (new) URL, right.
Julien
The URIs defined by NISO for each term should be the actionable part used for “machine readability”. Like many JATS elements, (especially with the vocabulary attributes added in JATS 1.1) is intended to serve both machine and human readers.
Machines get an unambiguous indicator of both the vocabulary being used (@vocab-identifier) and an unambiguous indicator of the term (@vocab-term-identifier). Both of these attributes should have URIs as content.
The element content allows the journal publisher to include whatever display text should be shown for the role of the given author. See Example 2
Data Collection
The journal wants to use/display the role for this author as “Data Collection” but wants to bind this to the standard vocabulary term for “Investigation”.
This is similar to how the HTML <a> element allows you to display “link text” that is different from the URL in the @href
Best Practices for applying JATS
Differences in punctuation or capitalization between the terms and the element content are just less severe cases of this.
I am curious about how people perceive the importance of the ndash or hyphen in the @vocab-term and the value of the role itself.
Niso site clearly has these as ndash, and the table of terms at the top of the recommendation have ndash also, but examples in JATS4R samples (JATS1.2 and above) use hyphen only. Does this mean there is flexibility in @vocab-term and the value of the content of ? If so, presumably if @vocab-term-identifer URL is set and @vocab=”credit” that is all that is required?
Also to be clearer it would also be useful to see an example of Writing – review & editing
Mike
The vocabulary terms were defined by NISO and CRediT with N-dashes in them. This is not something that JATS4R can change.
Fortunately we use the term URIs to identify (and disambiguate) them and do not have to rely on string matches (and worry about normalizing dashes, spaces, and capitalization).
There is plenty of “flexibility” between the @vocab-term and the value of the element content. See the response to Julien above.
These URLs are all older protocol http://credit.niso.org/, should they not be https://credit.niso.org/ secure protocol now?
I’ve only just noticed that credit website is now https. Does this affect this recommendation?
Hi Dorothy and Mike
We’ve updated the recommendation to reflect the secure urls.
Thanks for the feedback!
Melissa