Status: Published
Version: 1.1
License: this recommendation document is licensed under CC BY-ND 2.0 UK
Provenance
Version 1.0 can be found here.
Version 1.0 corrected by Kevin Lawson based on feedback from Nikos Markantonatos. This was then reviewed by the JATS4R Steering Committee.
Subgroup members (listed in alphabetical order):
Jeff Beck, NCBI; Julie Blair, SAGE; Franziska Buehring, De Gruyter; David Haber, American Society for Microbiology; Kevin Lawson, Sheridan; Vincent Lizzi, Taylor & Francis; Nikos Markantonatos, Atypon; Charles O’Connor, Aries Systems; Ken Rawson, IEEE; Mary Seligy, Canadian Science Publishing (Chair); Caroline Webber, Aries Systems
Change history
Remove citations to Examples 5A and 5B, which do not exist.
Context
<front>, <contrib-group>, <contrib>, <aff>, <xref>, <label>, <institution>, <institution-id>, <city>, <state>, <country>, <postal-code>, <string-name>, <contrib-id>, <collab>, <author-notes>, <author-comments>, <on-behalf-of>
@id, @ref-type, @country, @contrib-type, @corresp, @initials
Description
This document contains best-practice recommendations for capturing authors and their affiliations in article metadata using JATS XML. The recommendations comprise the following three parts:
- Author-affiliation associations
- Affiliations (and that within the scope of affiliations, such as institutions, institutional IDs, etc)
- Authors (and that within the scope of authors, such as IDs, roles, etc)
Recommendation
Part A: Author-affiliation associations
Note: There are three commonly used patterns of associating authors to their affiliations. It is the content-provider’s choice which to use. These are as follows:
- <aff> is contained directly within <contrib> (see Example 1A)
- <aff> is contained outside of <contrib> but within <contrib-group> (see Example 1B)
- <aff> is contained outside of both <contrib> and <contrib-group> (see Example 1C)
- Linking authors to affiliations. For each affiliation, the relevant
must contain an that references @id on the <aff> . Use @ref-type=”aff”. The element may be empty (see Example 1B). - Exception 1. If <aff> is contained directly within <contrib> (see Example 1A), then using <xref>/@id on <aff> is not required.
- Exception 2. If <aff> is contained within the parent <contrib-group> of <contrib> and all contributors (<contrib>) within that <contrib-group> share a single affiliation, then using <xref>/@id on <aff> is best but not required.
[[Validator tool result: if <aff> is contained outside of both <contrib> and <contrib-group> and <xref> is missing ERROR]]
[[Validator tool result: if there is more than one <aff> in the <contrib-group> with no descendant::xref[@xref-type=”aff”], unless there is only one <contrib> ERROR]]
- Exception 1. If <aff> is contained directly within <contrib> (see Example 1A), then using <xref>/@id on <aff> is not required.
- @ref-type (on <xref>). When linking a <contrib> to its <aff> use @ref-type=”aff” on <xref>
[[Validator tool result: if @ref-type on <xref> != “aff” if @rid references an <aff> element ERROR]]
Part B: Affiliations
- <aff>. Each
must contain a single and complete affiliation. Do not include a string that represents more than one affiliation or that contains parts of affiliations, such as “Dept. of Biology and Dept. of Chemistry, University of Something”, since each department of an institution is itself an affiliation, which may be assigned its own institutional ID, if such IDs are being used. See Examples 3A and 3B. For further discussion, see recommendations 5 and 6, below, concerning institutions and institution IDs, respectively. - Note: If a publisher wishes to follow this recommendation but has a requirement to represent the original affiliation comprising two or more partial affiliations, then see Rendering affiliation strings comprising partial affiliations, at the bottom of this document.
- Note: If a publisher wishes to follow this recommendation but has a requirement to represent the original affiliation comprising two or more partial affiliations, then see Rendering affiliation strings comprising partial affiliations, at the bottom of this document.
- <label>. If a label (such as a letter or number or combination thereof, often superscripted, which precedes the actual affiliation; e.g. “a”) is required for an affiliation, then capture the content of the label within a <label> element, and not directly within <aff> (see Example 1B).
[[Validator tool result: if <xref> is present within <contrib> and contains content AND the corresponding <aff> does not contain a <label> WARNING]]
[[Validator tool result: if an aff starts with a <sup> (not in a <label>) that is only one character ERROR]] - <institution>. This element should be used to contain the name of an institution, whether that “institution” is a university, a department, office, laboratory, etc. It is up to the publisher to determine how granularly to capture institutional information, and to ensure that each institution (whether a university, department, or laboratory) is accurately contained within its own <institution> element. See further comment in the next recommendation for <institution-id> (see Examples 3A and 3B).
- <institution-id>. Capturing the institutional ID is not mandatory at this time. However, if the publisher does capture it, they should make every effort to ensure that it is accurate. Use <institution-id> to contain the ID, and @institution-id-type to indicate the type of ID; e.g., “grid” or “ringgold” the <institution-id> and <institution> elements within <institution-wrap>
(see Examples 3A and 3B). - Note 1: Each institution name/institution ID pair (whether the institution is a university, a department, a lab, or an office, etc.) should be contained within its own element (see Example 3B).
- Note 2: The <institution-id> element is only available in JATS 1.1 and forward. Given that there is no effective or legitimate way of capturing this information in JATS 1.0 and backward, publishers who wish to capture institution IDs in article XML should upgrade to use JATS 1.1.
[[Validator tool result: if @institution-id-type is missing from <institution-id> ERROR]]
- <city>, <state>, <country>, and <postal-code>. If the publisher wishes to capture any of city, state/province, country, or postal/zip codes, they should use the specific elements provided for these.
Note: Since these elements are only available in JATS 1.1 and forward, publishers who wish to capture this information and are in JATS 1.0 or backward should consider moving to a more recent version of JATS. - @country. If <country> is used, then @country must also be used and must be set to the 2-digit country code, as specified in ISO 3166-1 (recommended in the JATS tag library).
[[Validator tool result: if @country is not present when <country> is present and if the value of @country is not on the ISO 3166-1 list of 2 letter country codes ERROR]]
Part C: Authors
- <contrib>, @contrib-type. Contain each author within a <contrib> element. If a <contrib> contains an author, then @contrib-type must be set to “author”.
- @corresp. Use the corresp attribute on <contrib>, set to value “yes”, to identify the corresponding author(s).
- <string-name>. It is at the publisher’s discretion whether to use <name> or <string-name> to capture an author’s name, though note that <string-name> is not allowed in <contrib> in JATS Blue. However, if a name is not easily broken down into a surname and given names (e.g. names such as “Prince” or “Prince Charles”), then if the publisher is using JATS Green, they should contain the entire string of the name in <string-name> to facilitate retrieval, per the JATS tag library guidelines.
- <contrib-id>. Use this element to contain an author’s ORCID ID, or alternative identifier, with @contrib-id-type set to the ID-assigning authority; e.g. contrib-type=â€orcidâ€.Â
[[Validator tool result:Â if @contrib-id-type is missing and <contrib-id> is present ERROR]] - <collab>. When an “author” is actually a collaborative group with its own name, use <collab> to contain the name.
Note: @contrib-type=”author” should be applied to the <contrib> containing the <collab>, and not to the individual child <contrib> elements within <collab> (see Examples 4A and 4B).
[[Validator tool result: if <contrib> contains a <string-name> that has neither <surname> nor <given-names> in it WARNING]] - <author-notes>. Author notes should be used to contain footnotes on authors, correspondence information, and any other information that applies to the group of authors as a whole.
- <author-comments>. Do not use this element to indicate that an author is anonymous or to indicate that an author is acting on behalf of a group. Instead, use, respectively, <anonymous> and <on-behalf-of>. Do not use this element to contain author footnotes or author correspondence information; see <author-notes>, above.
- <on-behalf-of>. Use this element to contain the name of the organisation or group on whose behalf an author is working.
- @initials. If a contributor’s initials are to be captured (either surname or given name initials), use @initials on <contrib> for this purpose. However, if the contributor only has initials, then contain the initials within the elements <surname> or <given-names>, as appropriate (see Example 1A).
[[Validator tool result: if the content of @initials is not 1-5 letters WARNING]]
Examples
See XML examples within the JATS4R Github repository.
Note: Examples 1A through 1C comprise the three most commonly used models of associating authors to their affiliations. It is the publisher’s choice which to use.
Example 1A: Affiliations associated to authors via position (i.e. within <contrib>)
<contrib-group> <contrib contrib-type="author"> <name> <surname initials="AP">Mitchell</surname> <given-names initials="AP">Aaron P.</given-names> </name> <aff>Carnegie Mellon University</aff> </contrib> </contrib-group>
Example 1B: Affiliations are outside of <contrib>, but within <contrib-group>
<contrib-group> <contrib contrib-type="author"> <name> <surname>Juretschko</surname> <given-names>Stefan</given-names> </name> <xref ref-type="aff" rid="aff1"><sup>a</sup></xref> </contrib> <aff id="aff1"><label><sup>a</sup></label>Northwell Health Laboratories, Pathology and Laboratory Medicine, Lake Success, New York, USA</aff> </contrib-group>
Example 1C: Affiliations are outside of both <contrib> and <contrib-group>
<contrib-group> <contrib contrib-type="author"> <name> <surname>Kosaki</surname> <given-names>Mika</given-names> </name> <xref ref-type="aff" rid="aff1"><sup>1</sup></xref> </contrib> <contrib contrib-type="author"> <name> <surname>Duchesneau</surname> <given-names>Audrey</given-names> </name> <xref ref-type="aff" rid="aff1"><sup>1</sup></xref> </contrib> </contrib-group> <aff id="aff1"><label>1</label> Department of Biology, McGill University, Montréal, QC </aff>
Example 2: Using a different model of association for different contrib types
<contrib-group> <contrib contrib-type="editor"> <name> <surname>Robichaud</surname> <given-names>Monique</given-names> </name> <aff>Simon Fraser University</aff> </contrib> </contrib-group> <contrib-group> <contrib contrib-type="author"> <name> <surname>Juretschko</surname> <given-names>Stefan</given-names> </name> <xref ref-type="aff" rid="aff1"><sup>a</sup></xref> </contrib> <aff id="aff1"><label>a</label>Northwell Health Laboratories, Pathology and Laboratory Medicine, Lake Success, New York, USA</aff> </contrib-group>
Example 3A: Complete and separate affiliations
<contrib-group content-type="authors"> <contrib contrib-type="author"> <name> <surname>Mitchell</surname> <given-names>Glenn</given-names> </name> <xref ref-type="aff" rid="aff1 aff2"><sup>a,b</sup></xref> </contrib> <contrib contrib-type="author"> <name> <surname>Ahearn</surname> <given-names>Susan</given-names> </name> <xref ref-type="aff" rid="aff2"><sup>b</sup></xref> </contrib> <aff id="aff1"><label>a</label><institution>Department of Education, Memorial University of Newfoundland</institution>, <city>St. John's</city>, <state>NF</state> <postal-code>A0J 1W0</postal-code>, <country country="ca">Canada</country></aff> <aff id="aff2"><label>b</label><institution>Department of Psychology, Memorial University of Newfoundland</institution>, <city>St. John's</city>, <state>NF</state> <postal-code>A0J 1W0</postal-code>, <country country="ca">Canada</country></aff> </contrib-group>
Example 3B: Complete and separate affiliations, including institutional IDs and more granular institutional mark-up
<contrib-group content-type="authors"> <contrib contrib-type="author"> <name> <surname>Voth</surname> <given-names>Irma</given-names> </name> <xref ref-type="aff" rid="aff1 aff2"><sup>a,b</sup></xref> </contrib> <contrib contrib-type="author"> <name> <surname>Von Risen</surname> <given-names>Lottie</given-names> </name> <xref ref-type="aff" rid="aff2"><sup>b</sup></xref> </contrib> <aff id="aff1"><label>a</label> <institution-wrap><institution-id institution-id-type="ringgold">1812</institution-id><institution>Harvard University</institution></institution-wrap> <institution-wrap><institution-id institution-id-type="ringgold">2188</institution-id><institution>Harvard Law School</institution></institution-wrap> <city>Cambridge</city>, <state>MA</state> <postal-code>02138</postal-code>, <country country="us">United States</country> </aff> <aff id="aff2"><label>b</label> <institution-wrap><institution-id institution-id-type="ringgold">89611</institution-id><institution>Dalhousie University Faculty of Agriculture</institution></institution-wrap> <institution-wrap><institution-id institution-id-type="ringgold">468452</institution-id><institution>Dalhousie University Department of Plant Food</institution></institution-wrap> <city>Halifax</city>, <state>NS</state> <postal-code>B3H 4R2</postal-code>, <country country="ca">Canada</country> </aff> </contrib-group>
Example 4A: A group of authors with affiliations, in which one of the authors is a collaborative group
Variation 1: Author-affiliation associations are implied by position
<contrib-group> <contrib contrib-type="author"> <collab>The authors and affiliations working group </collab> <aff id="aff3">Dept. Of Philosophy, University of XML</aff> </contrib> <contrib contrib-type="author"> <string-name>Prince Charles </string-name> <aff id="aff1">Buckingham Palace, England</aff> </contrib> </contrib-group>
Variation 2: Author-affiliation associations are made via <xref>
<contrib-group> <contrib contrib-type=”author”> <collab>The authors and affiliations working group</collab> <xref ref-type=”aff” rid=”aff1”/> </contrib> <contrib contrib-type=”author”> <string-name><surname>Cooke</surname><given-names>James </given-names></string-name> <xref ref-type=”aff” rid=”aff2”/> </contrib> <aff id=”aff1”>Buckingham Palace, England</aff> <aff id=”aff2”>Royal Navy, London, UK</aff> </contrib-group>
Example 4B: A collaborative author group in which the group itself has an affiliation and each author in the group also has an affiliation
Note: The following mark-up is not necessarily the only way to capture constituent contributors within a collaborative group. The purpose of the example here is to show how affiliations would be included. Please see the bottom of this document for an alternative mark-up of a collaborative group as another example.
Variation 1: Author-affiliation associations are implied by position
In this model, the collaborative group itself has an affiliation, which is located within its <contrib> element (association by position). The constituent contributors also each have affiliations, and each of these <aff> elements is located within the relevant <contrib> elements (also associated by position).
<contrib-group> <contrib-group> <contrib contrib-type=”author”> <collab>The authors and affiliations working group <contrib-group> <contrib><string-name>Prince Charles </string-name> <aff id=”aff1”>Buckingham Palace, England</aff></contrib><contrib> <string-name><surname>Cooke</surname><given-names>James</given-names></string-name> <aff id=”aff2”>Royal Navy, London, UK</aff></contrib> </contrib-group> </collab> <aff id=”aff3”>Dept. Of Philosophy, University of XML</aff> </contrib> </contrib-group>
Variation 2: Author-affiliation associations are made via <xref>
In this model, the collaborative group links to its own affiliation via an <xref> element located within its parent <contrib> element; the <aff> is located outside of this <contrib>.
The constituents of the collab group also have affiliations, and these are associated via <xref> elements within each <contrib>; the <aff> elements for each of these is located outside of the <contrib> elements but within their parent <contrib-group>.
<contrib-group><contrib-group> <contrib contrib-type=”author”> <collab>The authors and affiliations working group <contrib-group> <contrib> <string-name>Prince Charles </string-name> <xref ref-type=”aff” rid=”aff1”/> </contrib><contrib> <string-name><surname>Cook</surname><given-names>James</given-names></string-name> <xref ref-type=”aff” rid=”aff2”/></contrib> <aff id=”aff1”>Buckingham Palace, England</aff><aff id=”aff2”>Royal Navy, London, UK</aff> </contrib-group> </collab> <xref rid=”aff3” ref-type=”aff3”/> </contrib> <aff id=”aff3”>Dept. Of Philosophy, University of XML</aff> </contrib-group>
Appendix
Rendering affiliation strings comprising partial affiliations
It is JATS4R’s recommendation that each <aff> element must only contain a single and complete affiliation (see Part B, Affiliations). Publishers who wish to follow this recommendation but also have a requirement to display a string of concatenated partial affiliations (such as in the PDF or on a web page) may consider using one of the approaches listed below for rendering that string. Note that these methods are not to be considered as alternatives to following the single-affiliation-per-aff recommendation; please note the caveats for each concerning interoperability/reuse.
Method 1: Capture the string within XML by using @specific-use and @content-type on <aff> within <aff-alternatives>.
Contain the string in an <aff> element of its own (i.e. in addition to the <aff> elements that contain the single and complete affiliations). Use @specific-use=”display” and @content-type=”combined-aff”. This <aff> is placed within an <aff-alternatives> element to indicate that it is an alternative representation of the affiliations.
- To keep as close to best practices as possible, consider using this method only for PDF composition, and not for delivery online or storing affiliation information
- Many systems ignore attributes, and the <aff> containing the string required for display may be treated as another ‘real’ affiliation. Ideally, it would be best to avoid including this <aff> in XML destined for exchange (e.g. in deposits to aggregators, indexers, archives, etc)
- Strictly speaking, <aff-alternatives> is an element that is meant to contain another version of a single affiliation, and not a combination of one or more affiliations. See the description of usage in the JATS tag library. Therefore, the use of this element might be confusing to systems and people outside of the publisher’s shop.
Example: Using <aff> within <aff-alternatives> with attributes to capture a string of concatenated affiliation parts for display
<contrib-group content-type="authors"> <contrib contrib-type="author"> <name> <surname>Mitchell</surname> <given-names>Glenn</given-names> </name> <xref ref-type="aff" rid="aff1 aff3"><sup>a</sup></xref> </contrib> <contrib contrib-type="author"> <name> <surname>Ahearn</surname> <given-names>Susan</given-names> </name> <xref ref-type="aff" rid="aff2 aff3"><sup>b</sup></xref> </contrib> <aff id="aff1"><label>a</label>Department of Education, Memorial University of Newfoundland, St. John’s, NF A0J 1W0, Canada</aff> <aff id="aff2"><label>b</label>Department of Psychology, Memorial University of Newfoundland, St. John’s, NF A0J 1W0, Canada</aff> <aff-alternatives> <aff id="aff3" specific-use="display" content-type="combined-aff" rid="aff1 aff2"><label>a,b</label> Depts. Of Education and Psychology, Memorial University of Newfoundland</aff> </aff-alternatives> </contrib-group>
Method 2: Use XSLT processing
For this to work easily, a couple of pre-conditions must be met. First, the affiliations should be internally parsed so that institutions and addresses are tagged. Second, affiliations should be arranged to group those that share institutions and addresses, even if that causes the numbers or letters used to indicate links to appear out of order in the author line.
Example
<contrib-group> <contrib contrib-type="author"> <name name-style="western"><surname>Panda</surname><given-names>Ankit</given-names></name> <xref rid="aff1" ref-type="aff"><sup>1</sup></xref> <xref rid="aff4" ref-type="aff"><sup>4</sup></xref> </contrib> <contrib contrib-type="author"> <name name-style="western"><surname>Hanham</surname><given-names>Melissa</given-names></name> <xref rid="aff2" ref-type="aff"><sup>2</sup></xref> <xref rid="aff3" ref-type="aff"><sup>3</sup></xref> </contrib> <contrib contrib-type="author"> <name name-style="western"><surname>Lewis</surname><given-names>Jeffrey</given-names></name> <xref rid="aff2" ref-type="aff"><sup>2</sup></xref> </contrib> <aff id="aff1"><label>1</label>Department of Medicine, <institution>University of Toronto</institution>, <addr-line><city>Toronto</city>, <state>ON</state></addr-line>, <country>Canada</country></aff> <aff id="aff2"><label>2</label>Institute of Medical Science, <institution>University of Toronto</institution>, <addr-line><city>Toronto</city>, <state>ON</state></addr-line>, <country>Canada</country></aff> <aff id="aff3"><label>3</label>Dalla Lana School of Public Health, <institution>University of Toronto</institution>, <addr-line><city>Toronto</city>, <state>ON</state></addr-line>, <country>Canada</country></aff> <aff id="aff4"><label>4</label>Toronto Rehabilitation Institute, <institution>University Health Network</institution>, <addr-line><city>Toronto</city>, <state>ON</state></addr-line>, <country>Canada</country></aff> </contrib-group>
An XSLT could recognize that the first three affiliations are identical starting at the <institution> element. It could then create a single affiliation paragraph by
- deleting all but the last instance of repeated information (important: the repeated information must start with the <institution> to avoid collapsing affiliations that share only location information)
- transforming <label> elements to <sup>
- inserting generated punctuation and connectors (e.g. “and”) depending on the number of affiliations with repeated institutions, etc
This would yield:
<aff specific-use="display"><sup>1</sup>Department of Medicine, <sup>2</sup>Institute of Medical Science, and <sup>3</sup>Dalla Lana School of Public Health, <institution>University of Toronto</institution>, <addr-line><city>Toronto</city>, <state>ON</state></addr-line>, <country>Canada</country>; <sup>4</sup>Toronto Rehabilitation Institute, <institution>University Health Network</institution>, <addr-line><city>Toronto</city>, <state>ON</state></addr-line>, <country>Canada</country></aff>
(The generated text is highlighted. If there had been only two affiliations with repeated institutions, then the comma after the first department would have had to be removed before adding ‘and’.)
If your affiliations do not have institutions and addresses parsed, it may be possible to achieve the same effect by adding processing instructions just before the repeated information. However, you should check with those that handle and host your XML before doing so.
Strictly speaking, the collapse of affiliations into a single paragraph would be achieved via XSLT even without the input affiliations first being arranged so that those that share an institution are grouped. The processing would be somewhat more complex and would result in superscripted numbers/letters that are out of order in the affiliation paragraph rather than in the author line.
An alternative mark-up structure for collaborative groups with constituent contributors
Since it is not common to see collaborative groups with constituent contributors listed, the following mark-up is offered as a suggested alternative to those given in Example 4B. Neither the following mark-up nor that in Example 4B is preferred for any particular reason.
<contrib-group><contrib-group> <contrib contrib-type="author" id="collab1"> <collab>The MARS Group</collab><xref ref-type="other" rid="fn1-35378645">*</xref> </contrib></contrib-group><contrib-group content-type="collab-list"> <contrib contrib-type="non-byline-author" rid="collab1"><name><surname>Wright</surname><given-names>Rick W.</given-names></name><degrees>MD</degrees></contrib> <contrib contrib-type="non-byline-author" rid="collab1"><name><surname>Huston</surname><given-names>Laura J.</given-names></name><degrees>MS</degrees></contrib> <contrib contrib-type="non-byline-author" rid="collab1"><name><surname>Spindler</surname><given-names>Kurt P.</given-names></name><degrees>MD</degrees></contrib> <contrib contrib-type="non-byline-author" rid="collab1"><name><surname>Dunn</surname><given-names>Warren R.</given-names></name><degrees>MD, MPH</degrees> </contrib> <contrib contrib-type="non-byline-author" rid="collab1"><name><surname>Haas</surname><given-names>Amanda K.</given-names></name><degrees>MA</degrees> </contrib></contrib-group><author-notes> <fn fn-type="other" id="fn1-35378645"><label>*</label><p>The writing committee for this article consisted of Rick W. Wright, MD; Laura J. Huston, MS; Kurt P. Spindler, MD; Warren R. Dunn, MD, MPH; Amanda K. Haas, MA. Members of the MARS Group are listed in the Contributing Authors section at the end of this article.</p></fn></author-notes>