Citations (general)

Status: Published
Version: 1.0
License: this recommendation document is licensed under CC BY-ND 2.0 UK

Context

<ref>, <mixed-citation>, <element-citation>, <person-group>, <name>, <string-name>, <collab>, <article-title>, <data-title>, <source>, <year>, <pub-id>, <fpage>, <lpage>, <elocation-id>

@id, @publication-type, @person-group-type, @pub-id-type

Description

This recommendation contain best practices for tagging citations in general.

Note: For specific recommendations on tagging data citations, see the Data citations recommendation.

Additional reading

See the JATS tag library documentation for a collection of best practices for tagging citations.

Recommendation

<mixed-citation> / <element-citation>. Either of these elements could be used, depending on whether your practice is to include punctuation in your XML (<mixed-citation>) or to generate punctuation (<element-citation>).

1. <ref>. Use a separate <ref> element for each citation. Use a unique and internally consistent identifier for @id. Best practice is an alphanumeric sequence common to all citations in your document, followed by an incremental number matching the sequential order of citations.
2. @publication-type on <mixed-citation> or <element-citation>. Use “journal” or “book” as the value of @publication-type to indicate that the citation is to a journal or book, respectively. Other examples are: “letter”, “review”, “patent”, “report”, “standard”, “data”, or “working-paper”. This list is not exhaustive and is sourced from the JATS guidelines. This is not a limited field so others can be used as appropriate, for example, “website”. However, in the interests of standardisation, JATS4R requests publishers to contact JATS4R if using additional values so we can create a definitive list and reduce variation across XML sources. “Other” is not a preferred value..
   
   [[Validator tool result: if @publication-type is not present ERROR]]
   
   [[Validator tool result: if @publication-type is ‘other’ WARNING]]
3. <person-group> and @person-group-type. Use the <person-group> element to specify authors and other contributors in a citation. Use the @person-group-type attribute to specify the role of a contributor, when it is possible to identify them with a role. A separate <person-group> element should be used for each role. This attribute has a fixed list of allowed values in the Journal Publishing tag set:
   all-authors
   assignee
   author
   compiler
   curator
   director
   editor
   guest-editor
   inventor
   transed
   translator
   
   [[Validator tool result: if <element-citation> or <mixed-citation> does not contain a child <person-group> with a @person-group-type WARNING]]
4. <name> / <string-name> / <collab>. The <name> or <string-name> element should be used for an individual named author. Use <name> when the ancestor element is <element-citation>, and <string-name> when the parent is <mixed-citation>.
   
   [[Validator tool result: if <name> or <string-name> is not a child <person-group> WARNING]]
5. When groups of authors (consortia) are cited under a group name or an institution is cited as the contributor, the <collab> element should be used.
6. <article-title>. This is used for the article title for journal references. The journal title should be contained within <source>.
7. <data-title>. This newly added element (tag set version 1.1d2) should be used for the title of data citations; for tag set versions 1.1d1 and lower, use <source>.
8. <source>. This is used for the book title for book references and journal titles for journal references.
9. <year>. This should contain the 4-digit year of publication. If the element contains anything other than a single 4-digit year (such as, for example, “2012A”, “2005Q1”), then use the @iso-8601-date attribute to specify the 4-digit year.
   
   [[Validator tool result: if year is not a 4 digit year and there is no @iso-8601 date ERROR]]
10. <pub-id>. This text content of this element should be used to hold a formal identifier, such as a DOI, of the cited work. The @pub-id-type attribute must be used – see point 11.
    
    A note on DOIs: When specifying a DOI, in the contents of the element, use the DOI “name”, which is the non-URI form of the identifier (beginning with “10.”). If a URL for the work is known, that can be included in the @xlink:href attribute, for display purposes only. In other words, the machine-readable, canonical identifier should be given in the text content, and machines ingesting the metadata should look for the identifier there.
    
    A DOI should be tagged as follows:
    <pub-id pub-id-type=”doi” xlink:href=”http://doi.org/10.1234/1234321?>10.1234/1234321</pub-id>
11. @assigning-authority on <pub-id>. If the assigning authority is known, this can be added, e.g. assigning-authority=”crossref”
12. @pub-id-type on <pub-id>. Use this attribute to specify the type of the identifier. For example, a DOI would have the @pub-id-type value of “doi”. The value should be one of the valid values from the list in the Tag Library.
    
    [[Validator tool result: if <pub-id> does not have a @pub-id-type ERROR]]
13. <fpage>, <lpage> and <elocation-id>. The first and last page elements should be used for traditional print publications. The last page should always exceed the number used in the first page, ie editorial style of shortening the last page value should not be used as that is only useful for human readability and not for machine consumption. Many non-print products will not have first and last page values, but a unique number that is called the elocation-id; in these instances, the <fpage> and <lpage> values should not be used but replaced with an <elocation-id>.
    
    [[Validator tool result: if <elocation-id> and any combination of <fpage>, <lpage>, <page-range> ERROR]]
    
    [[Validator tool result: if no <page-range>, and <lpage> is greater than <fpage> ERROR]]

Example

 <ref id="bib13">
      <element-citation publication-type="journal">
           <person-group person-group-type="author">
                  <name>
                      <surname>Bradley</surname>
                      <given-names>RK</given-names>
                  </name>
                  <name>
                     <surname>Roberts</surname>
                     <given-names>A</given-names>
                 </name>
           </person-group>
           <year iso-8601-date="2009">2009</year>
           <article-title>Fast statistical alignment</article-title>
           <source>PLOS Computational Biology</source>
           <volume>5</volume>
           <elocation-id>e1000392</elocation-id>
           <pub-id pub-id-type="doi">10.1371/journal.pcbi.1000392</pub-id>
      </element-citation>
</ref>