Silverchair logo

Document Revision History
Date Description Version
See consolidated revision history page

Introduction

Silverchair has created SCJATS, a custom XML specification for loading content into SCM6. SCJATS is based on the Journal Publishing Tag Library NISO JATS version 1.0 (JATS tag set)—successor to the NLM Journal Publishing Tag Set Tag Library version 3.0. New features from JATS 1.1, 1.2, and subsequent versions are considered, as needed. XML content must be valid against the SCJATS XML Schema and additional rules stated herein.

The Journal Publishing Tag Set defines elements and attributes that describe the content and metadata of journal articles, including research and non-research articles, letters, editorials, and book and product reviews. The Tag Set allows for descriptions of the full article content or just the article header metadata.

The philosophy of this Publishing Tag Set is to prefer a single structural form whenever possible. The Publishing Tag Set is optimized for regularizing an archive or establishing a sequence of elements to aid print and web production. Elements and tagging choices are limited to produce consistent data structures to enable output products and to provide a single location of information for searching.

Source: http://dtd.nlm.nih.gov/publishing/

Due to the size of the JATS tag set, SCJATS does not accommodate all features available in the JATS tag set. This document describes SCJATS—the SCM6 implementation of the JATS tag set. Content that is valid against this specification will also be valid against the JATS tag set, but the reverse is not necessarily true.

The documentation provided by the NLM at http://jats.nlm.nih.gov/publishing/tag-library/1.0/index.html is an excellent resource to supplement the information contained in this document. The key to transforming data to conform to the SCJATS specification is using the correct elements to tag consistently. Transforming correctly and consistently will ensure a smooth and accurate load of content to the platform.

Silverchair staff are available to answer questions about any of the elements discussed herein or to help handle any situations not covered by this document.

Guidelines appearing here address two areas: (1) tagging requirements for processing; and (2) guidelines on how to optimize data for Silverchair’s system, taking advantage of functionalities and features of SCM6.

Packaging requirements for Zipline loading are in the Package Requirements for Zipline CTE. Copies may be requested from your Product Owner or other Silverchair representative.

Silverchair’s XSDs

Silverchair’s custom XML specifications are in an XSD format, and are hosted alongside this narrative specification. Our recommendation is that users replace their entire set of specification files upon each release, as the XSDs refer to each other, and are meant to be used as a single unit. The latest release of the XSDs can be found here: SilverchairSpecifications1_22.zip.

Silverchair’s custom XSDs include SCJATS-journalpublishing.xsd, for articles and proceedings; SCJATS-journalissue.xsd, for journal issue-meta files; SCBITS-book.xsd, for books; and a SC-common.xsd file that serves as the base XSD for all formats.

XML encoding

XML must be well-formed, conformant XML according to the W3C XML Recommendation, fully tagged, and valid to the SCJATS XML Schema. Content must also meet the requirements in this Silverchair specification.

Silverchair accepts content in both fully tagged (full-text) and so-called metadata-only or PDF-only forms. Metadata-only content merely omits the body of the content from the XML; there is no flag to identify content as full text or metadata-only. Content metadata for both forms must be complete as described here.

XML declaration

Declarations required at the top of each XML file are:

Example:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>

Special Characters

UTF–8 character encoding is required to ensure that characters are translated properly upon import into the SCM6 database. Content XML may also contain numeric character references (e.g. &#345; or &#x159;) or the character entity references that JATS supports for special characters. Predefined entities for ampersand, less-than, and greater-than should be used where the intent is to display the actual characters ampersand (&), less-than (<), or greater-than (>) respectively; the predefined entities should not be used where those characters are part of markup or encodings.

Some characters do not have a unique encoding. Examples are a capital V with a dot over it, used to indicate ventilation rate in medical texts. To encode a V with a dot, use combining diacritical marks. For example, to encode V dot, use &#x0056;&#x0307; which will produce this: V̇.

The article wrapper

The root element of an article must be the <article> element from the SCJATS article format.

For example:

<article
    article-type="research-article"
    xml:lang="en"
    xmlns:mml="http://www.w3.org/1998/Math/MathML"
    xmlns:xlink="http://www.w3.org/1999/xlink"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:ali="http://www.niso.org/schemas/ali/1.0/"
    xmlns="http://specifications.silverchair.com/xsd/1/22/SCJATS-journalpublishing.xsd"
 >

Article type attribute

Article types are used for indexing and retrieval. An article is required to have an article type. Mark the <article> element with the appropriate value for @article-type. NLM provides suggested article types at http://jats.nlm.nih.gov/publishing/tag-library/1.0/n-eqr0.html, but any values may be used. Spaces and variations in punctuation and spelling will be read and processed as different article types. Values supplied for @article-type are not case-sensitive, however. All required article types must be set up in SCM6 before importing articles. See example below:

<article article-type="editorial">

If the article is part of conference proceedings the value for @article-type must be “proceedings” so that the article will be imported correctly as a proceeding article. See example below:

<article article-type="proceedings">

Journal metadata

At least one journal ISSN is required within <journal-meta> for all articles, as the ISSN will identify the journal to which an article belongs. The journal must be configured in SCM6 before importing the XML for an article itself, with a matching ISSN, as this is how the article will get correctly assigned to the journal it belongs to.

Use the @pub-type attribute with a value of “ppub” on the <issn> element to specify the print ISSN (e.g., <issn pub-type="ppub">) or, similarly @pub-type with a value of “epub” to specify the electronic ISSN (e.g., <issn pub-type="epub">). Both may be included; only one of each may be included.

Other elements in <journal-meta> are allowed but Zipline will ignore them; they have no effect in SCM6. The journal metadata that are pre-configured in SCM6 will be used exclusively by the system.

Article metadata

Provide at least the following elements within <article-meta> whenever applicable. Metadata is required for both articles with full text and articles that are supplied in PDF only. The element and associated attribute values provided here will be displayed in the article and used for indexing and retrieval of articles.

Required and recommended article metadata

Required Article Metadata
Required element Required Attributes Notes
<article-id> One of the following for each element:
@pub-id-type="doi"
@pub-id-type="publisher-id"
DOIs are required to enable some SCM6 functionality, including automated article replacement, duplication checking, and PubMed and Crossref deposits. Articles may have multiple <article-id>. Include only the DOI name, without the doi: or http://dx.doi.org/ prefix.
<article-title> Contained in a <title-group> element. Articles without titles will be assigned a default title to make them navigable on the website.
<pub-date> One of the following for each element:
@pub-type="ppub"
@pub-type="epub"
@pub-type="cover"
@pub-type="collection"
See section Article and issue publication dates
<volume> Note that values are not normalized in processing; vol 01 and vol 1 are treated as two separate volumes. Volume numbers are not required for Publish Ahead of Print articles.
<issue> Note that (as with volume) issue 01 and issue 1 are treated as two separate issues. Issue numbers are not required for Publish Ahead of Print articles or proceedings.
<fpage> [1] First page number. Non-numeric values such as “1a” are acceptable if this reflects the article’s pagination. If page numbers are not used, a value that is the equivalent of page number (e.g. CID) should be put in <elocation-id>.
<elocation-id> [1] For articles without a traditional printed page number, use elocation-id.
Recommended Article Metadata
Recommended element Required Attributes Notes
<lpage> Last page number. Required if different in value from <fpage>.
<self-uri> @xlink:href="article_pdf.pdf" Required if a PDF of the article is present.
<related-article> Required for errata and any other related proceeding link. See section Related article links

Alternate titles

Alternate titles can be used to create special display behavior based on context. For example, a shorter title may be created for display of Featured articles on the journal home page. Speak to your build team about options.

<alt-title> is an optional child of <title-group>.

Issue titles

Issue titles can be included in article XML by using the optional <issue-title> element as a child of <article-meta>. Issue titles can also be included and updated in an <issue-meta> metadata file, see sections Issue-level data and Issue title.

Automatic replacements

Zipline will use an article’s DOI or publisher ID to automatically identify duplicate articles and make replacements. DOI will trump publisher ID for the purpose of matching articles. If the journal or conference is live, then an imported article will replace an article already in the system that has a matching DOI or publisher ID. If the journal or conference is not live—for example, while importing backfile content—then articles will be imported as new even if they have a duplicate DOI or publisher ID.

Other article identifiers

You may include the following article identifiers in addition to DOI and publisher ID, but they will not allow replacement:

ID type tagging notes
arXiv arXiv:1501.00001 Include the canonical arXiv ID as defined by arXiv. For example, after April 2007, the arXiv ID value includes the arXiv: domain identifier (arXiv:1501.00001), but before that they do not (math.GT/0309136)

Article and issue publication dates

Article and issue dates should be included in a <pub-date> node. At least one <pub-date> is required to be valid against the JATS tag set.

To supply a date, the following options are available (full year, month, and day information must be provided from at least one option):

Dates can be provided in non-numerical form (e.g. <month>January</month>). The <season> tag can also be used instead of day and month (e.g. <season>Fall</season> or <season>1st Quarter</season>). If the date is provided in a form other than numerical month and year, then the @iso-8601-date attribute must be included to supply a numerical article date. In this case, the day and month or season provided can be used for display, while the @iso-8601-date value is used as the underlying article date by the system.

The @pub-type attribute is required and the following @pub-type attribute values may be used:

Volumes with no issues and issues with no volume

In rare cases, an issue does not belong to a volume, or a volume contains articles with no issues. Use @content-type="empty" on <issue> or <volume> to indicate that there is no issue or volume, respectively. Use of this attribute should be rare—in almost all cases, articles belong to an issue, which in turn belongs to a volume.

In the case of Publish Ahead of Print (aka Online First) or Just Accepted Manuscript articles, omit the <volume> and <issue> elements entirely; the system does not expect such articles to be associated with an issue, and therefore does not expect a volume or issue.

Dual issue numbering

When a journal’s issues have both a traditional vol-issue numbering system and an additional sequential issue numbering system, use @seq on <issue> to capture the additional numbering.

<issue seq="115">2</issue>

Article life-cycle state (advance publication)

The system will assume journal articles belong to a volume and issue by default. To import articles as Published Ahead of Print or Accepted Manuscript, use a <custom-meta> node with <meta-name>article-lifecycle</meta-name>.

<custom-meta-group>
        <custom-meta>
            <meta-name>article-lifecycle</meta-name>
            <meta-value>pap</meta-value>
        </custom-meta>
</custom-meta-group>

The following values for <meta-value> are permitted:

meta-value article lifecycle
jam Just Accepted Manuscript, Accepted Manuscript
pap Published Ahead of Print, Ahead of Print, Online First

Open Science Framework badges

Publishers may include metadata regarding awarded Open Science Framework badges by using a <custom-meta> node with <meta-name>open-science-badges</meta-name>.

<custom-meta-group>
        <custom-meta>
            <meta-name>open-science-badges</meta-name>
            <meta-value>open-materials</meta-value>
        </custom-meta>
</custom-meta-group>

The following values for <meta-value> are permitted:

meta-value Open Science Framework badge
open-data Open Data
open-materials Open Materials
preregistered Preregistered
preregistered-analysis-plan Preregistered+Analysis Plan

For more information on the OSF badges please visit: https://osf.io/tvyxz/wiki/home/.

Other metadata

Permissions

The <permissions> element holds copyright information and license material.

Copyright may include:

When the <permissions> element is in the <article-meta>, its <license> element sets the access type for the article. If a funder for an article has an embargo period, then the article will automatically become available outside the paywall after the embargo period. See the section Funding information for deposit to the Funder Registry for how to include funding information.

Free to Read

The <ali:free_to_read> element is a simple flag whose presence indicates that the document is free-to-read, without making statements about any additional reuse rights or restrictions. Date attributes (@start_date and @end_date) can specify when the document is free to be read. The absence of both start and end dates indicates a permanent free-to-read status. Note the namespace must be included on the element, or declared in the document header.

<permissions>
    ...
    <ali:free_to_read xmlns:ali="http://www.niso.org/schemas/ali/1.0/"/>
    ...
</permissions>

License, including free and open access

The <license> element contains the set of conditions under which people are allowed to use the content, or other license-related information or restrictions. The @license-type attribute defines the type of license being granted for the article.

license type description
@license-type="free" Free article
@license-type="open-access" Open Access article
@license-type="crown-copyright" CrownCopyright article (free)
@license-type="us-gov" USGov article (free)
@license-type="cc-by" Creative Commons Attribution license (Open Access)
@license-type="cc-by-nc" Creative Commons Attribution-NonCommercial license (Open Access)
@license-type="cc-by-nc-nd" Creative Commons Attribution-NonCommercial-NoDerivs license (Open Access)
@license-type="cc-by-nc-sa" Creative Commons Attribution-NonCommercial-ShareAlike license (Open Access)
@license-type="cc-by-nd" Creative Commons Attribution-NoDerivs license (Open Access)
@license-type="cc-by-sa" Creative Commons Attribution-ShareAlike license (Open Access)
@license-type="cc-by-igo" Creative Commons Attribution-IGO license (Open Access)
<permissions>
    …
    <license license-type="open-access" xlink:href="http://creativecommons.org/licenses/by/2.0/">
        <ali:license_ref xmlns:ali="http://www.niso.org/schemas/ali/1.0/">https://creativecommons.org/licenses/by/4.0/</ali:license_ref>
        <license-p>This is an open-access article distributed under the terms of the Creative Commons Attribution License, which permits unrestricted use, distribution, and reproduction in any medium, provided the original
work is properly cited.</license-p>
    </license>
</permissions>

See Figures for instruction on using the <permissions> and <license> elements to restrict access to figure images within an article.

Document history

History is used as a container for dates related to the processing history of the document, such as received date and accepted date. Values for @date-type are client-specific and must be set up in SCM6 before loading. Use a combination of <day>, <month>, <year>, and @iso-8601-date (on <date>) as described in Article and issue publication dates to provide a valid date.

<article-meta>
    …
    <history>
        <date date-type="received">
            <day>05</day>
            <month>01</month>
            <year>1998</year>
        </date>
        <date date-type="rev-recd">
            <day>24</day>
            <month>05</month>
            <year>1998</year>
        </date>
        <date date-type="accepted">
            <day>06</day>
            <month>06</month>
            <year>1998</year>
        </date>
    </history>
    …
</article-meta>

Authors

Authors and other contributors that should appear in the content by-line should be placed in a <contrib-group> node.

Place each contributor in a <contrib> node with a @contrib-type value of “author”, “editor”, “chair”, or “translator”. A <contrib> element with no @contrib-type attribute will default to @contrib-type="author". <contrib> elements with a @contrib-type attribute value other than “author”, “editor”, “chair”, or “translator” will be ignored.

Other @contrib-type values can be configured with the build team.

Use the <role> sub-element to include the role of the contributor to be displayed.

Use the @equal-contrib attribute on <contrib> to indicate whether all contributors contributed equally. If the contributor whom this attribute modifies contributed equally with all other contributors, this attribute should be set to “yes”; if their contribution was greater or lesser, then this attribute should be set to “no”. These contributors may contain a link to a footnote in <author-notes> for further description, such a link should use <xref ref-type="author-notes">.

ORCID ID

Include an ORCID for an individual author in a <contrib-id> element with @contrib-id-type="orcid". Only individual authors and individual members of an organization (members of a <collab>) may have an ORCID. Specify the ORCID as a full URI—e.g. <contrib-id contrib-id-type="orcid">http://orcid.org/0000-0002-1825-0097</contrib-id>.

The @authenticated attribute can be used with a value of “true” or “false” to indicate that the authority associated with the ID type (named in @contrib-id-type) has authenticated the value of the ID. The default value is “false”. This value is used only for Crossref metadata purposes.

Value Meaning
true This contributor identifier has been marked by the issuing authority as authenticated.
false No guarantee has been made about this contributor identifier.

Corresponding authors

To indicate that a contributor is the corresponding contributor for the content, use the optional @corresp attribute: <contrib contrib-type="author" corresp="yes">. Contact information included as a child of <contrib>, such as <email>, will be stored as metadata about the author, and will be the source for features such as toll-free links. To link this author to displayed contact information, include an <xref ref-type="corresp"> with the appropriate @rid referencing <corresp> in the <author-notes> element; see Author notes for more information.

Alternative names

If a single author has more than one version of their name, use the <name-alternatives> element within the <contrib> element.

<contrib-group>
        <contrib contrib-type="author">
            <name-alternatives>
                    <name>
                            <surname>Balzer</surname>
                            <given-names>Carsten</given-names>
                    </name>
                    <name>
                            <surname>LaGata</surname>
                            <given-names>Carla</given-names>
                    </name>
            </name-alternatives>
        </contrib>
</contrib-group>

Author affiliations

If there are author affiliations (<aff>), the <aff> nodes can be included as sibling elements to the <contrib-group> node. These <aff> nodes must include an @id attribute. In the <contrib> node for which the affiliation applies, include an <xref> node that references the appropriate <aff> node.

If your sites are designed to display separate linked text from the author to the affiliation (e.g. a superscripted number), the <aff> node must include a <label>. Do not include a label as content of the <xref> in this case.

<contrib-group> 
        <contrib contrib-type="author">
            <name>
                <surname>Keefe</surname>
                <given-names>Lindsey</given-names>
            </name>
            <degrees>PhD</degrees>
            <xref ref-type="aff" rid="aff1" />
        </contrib>
        …
</contrib-group>

<aff id="aff1">
    <label>1</label>Silverchair Information Systems, Charlottesville, VA 22902. 
</aff>

Affiliations that are not linked from a <contrib> element will be ignored.

The <aff> node can also be included as a child of the <contrib> element to which the affiliation applies. Using this method, affiliations must be repeated for each contributor if multiple contributors have the same affiliation, and the @id attribute is not required.

Each affiliated organization should be included in a separate <aff> node.

Collaborative group authors

Use <collab> instead of <name> if the author is a group credited under a single name or the author is an organization (such groups may be known by other names such as collaborative groups or collectives). Members of each group can be provided inside a <contrib-group> node that is a child of the <collab> element. These contributing members are not treated as authors and will not appear in the by-line, but will be submitted to PubMed as investigators/collaborators.

On behalf of

Use <on-behalf-of> as a child of <contrib> if a single author is writing on behalf of an organization, and use the tag as a child of <contrib-group> to apply it to a list of authors. If a subset of authors is writing on behalf of an organization and another subset isn’t, group the authors in different <contrib-group> elements. The separation of authors into different <contrib-group> elements has no other bearing on the content. Include the full content for display in the <on-behalf-of> element. For example: <on-behalf-of>for the Joint Working Group</on-behalf-of>. The <on-behalf-of> will only be imported for top-level authors; it may not be included for the individual members of a collaborative group.

Author comments

Notes that are not affiliations but are specific to a contributor can be included in an <author-comment> node within the <contrib> node to which the note applies. The @content-type attribute must be included to indicate the type of note. Permitted attribute values are:

Biographical data

Include biographical data in the <bio> element within the <contrib> node to which the bio applies. A <bio> element placed as a child of <contrib-group> will apply to all authors in that group. The <bio> element may also be used under the <collab> element.

Author notes

Use an author notes section for additional notes about contributors that are not directly tied to a single author. The author notes can be included using the <author-notes> element.

Use <corresp> to include display information concerning how and with whom to correspond about content. The <corresp> must include an @id attribute for it to link to the <contrib> element.

<author-notes>
    <corresp id="cor1">
        <email>lkeefe@university.edu</email>
    </corresp>
</author-notes>

Use <fn fn-type="COI-statement"> or <fn fn-type="conflict"> in <author-notes> to include a Conflict of Interest statement. A Conflict of Interest statement can be specifically linked to an individual contrib that contains an <xref> with @ref-type="author-notes".

 <author-notes>
    <fn fn-type="COI-statement" id="con1">
      <label>*</label>
      <p>Competing Interests: The authors have declared that no competing interests exist.</p>
    </fn>
 </author-notes>

Use <fn fn-type="equal"> to provide a statement about equal contributors. This can be used separately or in conjunction with <contrib equal-contrib="yes">.

<author-notes>
    ...
    <fn fn-type="equal" id="afn9">
      <label>*</label>          
      <p>Keefe and Hibino contributed equally to this paper.</p>
    </fn>
 </author-notes>

If your sites are designed to display separate linked text from the author to the author-notes (e.g. a statement for Conflict of Interest or equal contribution), the <fn> node must include a <label>. Do not include a label as content of the <xref> in this case.

Link to PDF of article

Link an article PDF to the article using <self-uri>, for example <self-uri xlink:href="2011.11010094.pdf"/> where the @xlink:href value is the exact file name as it occurs in the pdf subdirectory.

Do not prepend the file name with a directory path.

The <self-uri> element is intended to link to the same piece of content in different forms. For links to data supplements use the <supplementary-material> element (section Supplementary material). For links within the same document, use the <xref> element (section Cross-references). For links to external resources, use the <ext-link> element (section External links).

Supplementary material

To add supplementary material to the article, use the <supplementary-material> tag in the <article-meta> section within the <front> of the article.

Put the exact data supplement file name, including the extension, in the @xlink:href attribute value, as in <supplementary-material content-type="data-supplement" xlink:href="supplement.pdf">. Do not include a file path.

For data supplements use the attribute @content-type="data-supplement". For disclosures use the attribute @content-type="disclosure". If no @content-type attribute is provided, the material will be treated as a data supplement. See also Featured images, audio, and video.

Any file type listed in the Zipline Packaging Requirements is acceptable for supplementary material.

Use the <label> tag for a label, and the <title> tag inside the <caption> for a title. Other explanatory text should go in the <caption> tag, in <p> elements.

If a data supplement is referenced within the text, the <supplementary-material> element must have a unique identifier in the @id attribute. Use an <xref> in the text to indicate the link to the supplement.

<xref ref-type="supplementary-material" rid="sup1">Table 3</xref>

Supplementary material can be assigned a unique identifier such as a DOI using the <object-id> tag within the element. The @pub-id-type attribute must be included with a value of either “doi” or “publisher-id”. If there is no publisher-id in an <object-id> element and the <supplementary-material> element has an @id attribute, SCM6 will use the value of the @id as the publisher-id.

The list of data supplements can be referenced within the text by using an <xref> without an @rid: <xref ref-type="supplementary-material">Supplementary material page</xref>.

Page range and count

The page range and page count of an article can be included in the metadata. The page range should be included in <page-range>. Use <page-range> if pages are discontinuous. Include <fpage> and <lpage> even if <page-range> is provided; this information aids in determining accurate citation data.

The page count of the article can be included as the value of the @count attribute of the <page-count> element within a <counts> element. Page count is the only count that we accept.

<counts>
    <page-count count="6" />
</counts>

Edited state

Edited state metadata may be captured in custom-meta in the following way:

   <custom-meta-group>
           <custom-meta>
                <meta-name>edited-state</meta-name>
                <meta-value>corrected-proof</meta-value>
           </custom-meta>
   </custom-meta-group>

The type of edited state, such as corrected proof, must be set up in advance with the build team and tagged in <meta-value>.

Abstracts

Abstracts are included in the <abstract> node within the <article-meta> element. The authored abstract should have no @abstract-type attribute, or it should have the attribute @abstract-type="abstract". Only one authored abstract is allowed on an article.

To create a graphical, audio, or video abstract, use @abstract-type="graphical", @abstract-type="audio", or @abstract-type="video" as specified below (note: <fig> in <p> is not recommended except in this case, see Nesting special content elements ):

<abstract abstract-type="graphical">
    <p>
        <fig id="fig1g">
            <label>Graphical Abstract Figure.</label>
            <caption><p>Woody plant encroachment…</p></caption>
            <graphic xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="abcfig1g.png"/>
        </fig>
    </p>
</abstract>

<abstract abstract-type="audio">
    <p>
        <fig id="abstract_audio1" fig-type="audio">
            <label>Audio 1.</label>
            <caption><p>Caption about audio…</p></caption>
            <media content-type="brightcove" xlink:href="http://bcove.me/id">
                <object-id pub-id-type="videoid">012345678</object-id>
                <object-id pub-id-type="referenceid">myAudio1</object-id>
            </media>

        </fig>
    </p>
</abstract>

<abstract abstract-type="video">
    <p>
        <fig id="abstract_video1" fig-type="video">
            <label>Video 1.</label>
            <caption><p>Caption about video…</p></caption>
            <media content-type="brightcove" xlink:href="http://bcove.me/id">
                <object-id pub-id-type="videoid">123456789</object-id>
                <object-id pub-id-type="referenceid">myVideo1</object-id>
            </media>

        </fig>
    </p>
</abstract>

The attributes @abstract-type="teaser" (see section Teasers) and @abstract-type="precis" will also be imported.

Within an abstract, you may include titled sections using <sec> nodes and the <title> element in each <sec>. Abstracts tagged with titled sections will be sent to PubMed as structured abstracts.

The @specific-use="layperson" attribute can be used on <abstract> to indicate a lay summary. A lay summary is not meant as a separate abstract type, but rather indicates an intended audience.

Abstract translations

Use the <trans-abstract> element for translated versions of the abstract, with each version in its own element. Include the @xml:lang attribute to indicate the language of each abstract.

SCM6 will consider <trans-abstract> to be a translation of the authored abstract. The @abstract-type attribute may be omitted or may include the value @abstract-type="abstract"; Zipline will drop the element if it includes other @abstract-type values.

The @specific-use="layperson" attribute can be used on <trans-abstract> to indicate a lay summary. A lay summary is not meant as a separate abstract type, but rather indicates an intended audience.

Hierarchical categories

Content can be assigned to categories. Use the <subj-group subj-group-type="category"> and <subject> elements to designate categories for the book or chapter. Each category should be placed in a <subject> element within the <subj-group> element.

The following content can be assigned to categories using <subj-group>:

SCM6 does not create categories on the fly, except for catgories with category type “toc-heading” (see below) or for specific book product codes. They must be set up in SCM6 before importing. Categories—factoring in category type and hierarchy—must be unique.

SCM6 supports hierarchical categories, which allows for parent-child relationships between categories. When assigning a child-level category to content, the parent categories must also be supplied in case more than one subcategory shares the same name. Zipline can currently import up to a 2-level hierarchy. The example below shows content with a category structure of:

<subj-group subj-group-type="category">
    <subject>Wireless Sensor Networks</subject>
    <subj-group subj-group-type="category">
        <subject>Alternative Energy Harvesting Systems</subject>
    </subj-group>
</subj-group>

Since the schema only allows nested <subj-group> elements after the <subject> elements, use multiple top-level <subj-group subj-group-type="category"> nodes to designate multiple parent-child categories.

If multiple facets of organization are required and the same category name exists for multiple facets, append a hyphen and the name of the category type to the end of the @subj-group-type value. For example, if the following categories have been set up in SCM6 for the same site:

then specify the former in the XML by including:

<subj-group subj-group-type="category-Book Categories">
    <subject>Research</subject>
</subj-group>

specify the latter in the XML by including:

<subj-group subj-group-type="category-Article Categories">
    <subject>Research</subject>
</subj-group>

Optionally, SCM6 may be configured to create categories on the fly during import for the category type “toc-heading” (<subj-group subj-group-type="category-toc-heading">). If this configuration is turned on, the system will create new categories under this category type when it finds new values in the XML. By default this configuration is turned off; please consult your Silverchair representative to enable the configuration.

Taxonomies

To assign content to a taxonomy, use <subj-group subj-group-type="category-taxonomy-collection"> and place each taxonomic ID in <subject>. Use only one <subject> per <subj-group>.

<subj-group subj-group-type="category-taxonomy-collection">
    <subject>T-123</subject>
</subj-group>
<subj-group subj-group-type="category-taxonomy-collection">
    <subject>T-456</subject>
</subj-group>

Note that before content can be assigned to a taxonomy, the taxonomy must exist in the SCM6 database or the content will produce an error. To add a taxonomy to the database, upload it as an RDF file via the Zipline API. For more information, see the Zipline User Guide.

Issue sponsor

If the issue has a sponsor, put that information in <issue-sponsor>. Note that <issue-sponsor> only allows text, numbers, and special characters.

Alternate title for deck

Some articles have a deck title (i.e., magazine articles), which is a short article summary, or tagline, that accompanies the article title. A tagline is typically a phrase or a sentence or two, and they are short and precise. The deck title will appear below the main article title.

In <title-group>, use <alt-title> with @alt-title-type="deck", as follows, if you wish to include a tagline for the article:

<title-group>
    <article-title>Title of article</article-title>
    <alt-title alt-title-type="deck">Deck title</alt-title>
</title-group>

Issue-level data

Use a separate issue metadata XML file to provide issue-level data that aren’t otherwise specified in the article XML. The root element for issue metadata files is <issue-meta> from the SCJATS issue-meta format. The issue metadata file is optional—if the issue has no asset files at the issue level and the table of contents is ordered by default site behavior, then the issue does not need an issue metadata file.

The issue-meta will only load successfully if referencing articles are loaded concurrently or already exist in the database.

Required identifiers

The issue metadata file must have an <issue-identifier> node with child elements <issn> (journal ISSN), <volume>, and <issue>. These values associate the file with a journal and issue. The <issn> elements must have a @pub-type attribute with either “ppub” or “epub” as the value.

Issue title

You can override the issue title provided in <article-meta> by including an <issue-title> in the issue metadata file.

Issue date

You can override the publication date provided in <article-meta> by including a <pub-date> in the issue metadata file. See section Article and issue publication dates for further specific tagging requirements.

Issue type

Use the <issue-type> element to designate an issue as a special type. The list below shows allowed values. If no <issue-type> element is included, the issue will become a regular issue.

issue-type value Description
regular A regular issue in which the articles have the same date and are typically published at once.
supplemental An issue for work published as a supplement. You can configure your sites to prevent supplemental issues from being listed as the latest issue.

Issue-level asset files

Journal issues may have associated asset files such as an issue cover image or front matter. The issue cover must be in an acceptable format to display (.bmp, .gif, .jpeg, .jpg, .tif, .tiff, .png). Front matter may be in PDF or image form. Include these files in the assets folder, in the same package as the issue metadata file.

The issue metadata file must reference the asset files using <supplementary-material> tags with @content-type values as shown in the following table. The value of the @xlink:href attribute must match the file name, including the file extension. See the package specification for allowed file types. Issue-level asset files are optional, and therefore the <supplementary-material> element is optional in the issue-meta XML. For example <supplementary-material content-type="cover" xlink:href="image.png" />.

Issue-level file Attribute
Cover image @content-type="cover"
Cover figure @content-type="cover-figure"
Cover caption @content-type="cover-caption"
Front matter @content-type="front"
Back matter @content-type="back"
Editorial Board @content-type="ed-board"
Table of Contents @content-type="toc"
Advertising @content-type="advertising"
Administration @content-type="administration"

Issue editors

Include issue editors in a <contrib-group> node using <contrib contrib-type="editor">. Contributors in the issue-meta file may not be identified as corresponding authors.

Issue table of contents

Default TOC ordering

Sites will order articles on the issue table of contents (TOC) by start page, grouped first by article type or category, by default. Whether the issue TOC groups articles by article type or by category is configured during your site’s build.

Manually ordered TOC

You may override the default issue TOC ordering by including a manual TOC in the issue metadata file, in a <table-of-contents> element. The manual issue TOC is a metadata model and not a presentational model (and thus differs from the <toc> element in BITS). Inclusion of an issue TOC will order the articles and group them under headings. Information displayed about the articles (e.g. title, authors, page numbers) will come from the article metadata that was imported in the article XML.

Allowed values for @pub-id-type are:

Topic-driven TOC

You may override the default issue TOC ordering with a topic-driven TOC. The topic-driven TOC will display a list of all categories (of a category type predetermined by your build team) associated with the articles in the issue. Selecting a category will display the articles associated with that category.

To specify use of a topic-driven TOC for an issue, include the attribute @dynamic-toc-type="topic-driven" in the <issue-meta> element.

The @dynamic-toc-type attribute and <table-of-contents> element may not appear in the same issue meta file.

Issue sponsor

If the issue has a sponsor, put that information in <issue-sponsor>. Note that <issue-sponsor> only allows text, numbers, and special characters.

Issue-level PDF

If the issue has an accompanying PDF, call out that PDF in <self-uri>. The attribute @xlink:href is required, and should contain the name of the PDF file. Example: <self-uri xlink:href="journal_issue1.pdf">.

Special features for articles

Teasers

In addition to regular abstracts in the metadata, Silverchair supports teasers, a short summary or descriptive text that will appear in various places on the site, such as in Search Results. If you wish an article to have a teaser, encode it in the metadata as <abstract abstract-type="teaser">.

For featured articles (see below), the teaser can be displayed with the article listing on the issue’s home page. The traditional abstract will not appear in the featured section.

Featured articles

To designate an article as “featured” on an issue’s home page, include a <subj-group subj-group-type="featured"> element in the article metadata inside <article-categories> as follows:

<subj-group subj-group-type="featured"><subject>Featured</subject></subj-group>

The value of the <subject> element must match the featured group name set up in SCM6. Featured group names must be set up in SCM6 before using them.

A featured article may also be given an alternate title for display; tag it as <alt-title> and determine the attribute and display behavior with the build team. For example, <alt-title> with attribute @alt-title-type="featured" could include a shorter title for display on the journal home page.

<title-group>
    <article-title>Lipid-Modifying Therapies and the Risk of Pancreatitis</article-title>
    <subtitle>A Meta-Analysis</subtitle>
    <alt-title alt-title-type="featured">Statins, Fibrates, and Pancreatitis</alt-title>
</title-group>

Featured images, audio, and video

To designate a featured image, audio, or video for an article, include a <supplementary-material> element with @content-type="featured-figure", @content-type="featured-audio", or @content-type="featured-video" in the article-meta. Use a <graphic> element for the pointer to the image file; use the <media> element to capture audio or video metadata.

<supplementary-material id="featfig" content-type="featured-figure">
    <label>Some title for the image</label>
    <caption>
        <p>A caption for the featured image.</p>
    </caption>
    <graphic xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="FeaturedFigureImage.png" />
</supplementary-material>

<supplementary-material id="feataudio" content-type="featured-audio">
    <label>Audio 1</label>
    <caption>
        <title>Some title for the audio</title>
        <p>A caption for the featured audio.</p>
    </caption>
    <media content-type="brightcove" xlink:href="http://bcove.me/id">
        <object-id pub-id-type="videoid">012345678</object-id>
        <object-id pub-id-type="referenceid">myAudio1</object-id>
    </media>
</supplementary-material>

<supplementary-material id="featvideo" content-type="featured-video">
    <label>Video 1</label>
    <caption>
        <title>Some title for the video</title>
        <p>A caption for the featured video.</p>
    </caption>
    <media content-type="brightcove" xlink:href="http://bcove.me/id">
        <object-id pub-id-type="videoid">123456789</object-id>
        <object-id pub-id-type="referenceid">myVideo1</object-id>
    </media>
</supplementary-material>

If the same image, audio, or video should appear in the body of the article, it should also be included in a <fig> in the body XML.

Only one image, audio, or video for the featured article will be used.

Online-only articles

To designate an article as “online only”, include a <subj-group subj-group-type="online-only"> element in the article metadata inside <article-categories> as follows:

<subj-group subj-group-type="online-only"><subject>Online Exclusive</subject></subj-group>

The value of the <subject> element must match the online-only group name set up in SCM6 (“Online Exclusive” in the above example). Group names must be set up in SCM6 before using them.

Use the <related-article> element in the content metadata (e.g. <article-meta>) to establish a two-way (database-driven) link between the content and another article. For example, you can link an erratum to the original article or a response to a Letter to the Editor. Related articles must be limited to articles within the publisher’s content. The XML containing the <related-article> and the target content can be imported in any order in relation to each other.

There are two methods for indicating which article to link to:

  1. DOI of the related article
  2. Volume and first page number of the related article

Of these, DOI is strongly preferred. Volume and page number can be used for articles that do not have an assigned DOI, but links may not always be created if the system cannot find a match or finds more than one match and cannot determine which is correct. This can happen if there are multiple articles on a single page, e.g. multiple letters to the editor.

To link via DOI, two methods are available:

To link via volume and page number, the following attributes are required:

Related articles that use the @xlink:href attribute to identify the target will be ignored by the SCM6 system, unless the target value is a DOI and the element includes the @ext-link-type="doi" attribute.

Values for @related-article-type must match a value in our system. Please coordinate with your build team to define their functionality before use.

If the following @related-article-type values have been set up for your build, they can be used for Crossmark functionality from Crossref, allowing readers to see the status of a work by displaying any corrections, retractions, or updates to that record. See https://www.crossref.org/services/crossmark/ for more details.

Related content

You may link content to other content that is published separately in the SCM6 system. Your site can use these links to surface related content to the user. Some example use cases include:

Use the <related-object> element in <article-meta>, <book-meta> or <book-part-meta> to designate a relation to another piece of content, or in the running text to link between chapters in books. Use the @document-type, @document-id-type, and @document-id attributes to designate the type of content and document to target. To link to an object (e.g. figure, table) within a piece of content, also include the @object-type, @object-id-type, and @object-id attributes with the appropriate values. You must designate both the document and the object when linking to an object.

Links to the following content types can be created from articles, books and chapters. For links to non-standard content, the target content must be imported first, or be in the same package when creating a link. For links to other content, the XML with the <related-object> tag and the target XML can be imported in any order.

Target document/content type tagging format
Non-standard <related-object document-type="non-standard" document-id-type="publisher-id" document-id="gbos123-12345"/>
Book (using ISBN 13) <related-object document-type="book" document-id-type="isbn13" document-id="1-234-56790-3"/>
Book (using ISBN 10) <related-object document-type="book" document-id-type="isbn10" document-id="7412589636"/>
Book (using eISBN) <related-object document-type="book" document-id-type="eisbn" document-id="1-234-56790-3"/>
Standalone multimedia (using DOI) <related-object document-type="multimedia" document-id-type="doi" document-id="11.1111/11111111"/>
Standalone multimedia (using publisher ID) <related-object document-type="multimedia" document-id-type="publisher-id" document-id="vid.oneoneone" />

To target objects within the document, additionally include the following attributes:

Target object tagging format
Main Division (in non-standard only) < … object-type="main-division" object-id-type="publisher-id" object-id="gbos123-12345.part1"/>
Part (in book only) < … object-type="part" object-id-type="publisher-id" object-id="book1.part1"/>
Chapter (in book only) < … object-type="chapter" object-id-type="publisher-id" object-id="book1.ch1"/>
Jump point (in multimedia only) < … object-type="jump-point" object-id-type="publisher-id" object-id="mm1234.jump001"/>
Jump point, hidden (in multimedia only) < … object-type="jump-point" object-id-type="publisher-id" object-id="mm1234.jump001"/>
Section < … object-type="sec" object-id-type="publisher-id" object-id="12345.sec01"/>
Figure < … object-type="fig" object-id-type="publisher-id" object-id="12345.fig01"/>
Table < … object-type="table" object-id-type="publisher-id" object-id="12345.table01"/>
Video < … object-type="video" object-id-type="publisher-id" object-id="12345.vid01"/>

For example <related-object document-type="non-standard" document-id-type="publisher-id" document-id="gbos123-12345" object-type="fig" object-id-type="publisher-id" object-id="12345.fig01"/>

An example of chapter-to-chapter links in the running text: <related-object document-type="book" document-id-type="isbn13" document-id="9781234567890" object-type="chapter" object-id-type="publisher-id" object-id="book-9781234567890-ch1">Chapter 1</related-object>

Links to objects within non-standard content will not be maintained if the target content is replaced.

Use the @link-type attribute to designate the link type. The link-type must match a value in our system. If the link-type is directional in nature (e.g. A is a correction for B vs. B is corrected by A), the link-type should follow the logic:

“The content in this XML is a/the [linkType] of/for the target content.”

Author assigned keywords

SCM6 accepts keywords in <article-meta> only. Speak to your build team about using keywords to create quick search links on the article page. Keywords do not require advance setup in SCM6 and will be created on the fly during import.

<kwd-group kwd-group-type="Chemicals">
    <kwd>chlorantraniliprole</kwd>
</kwd-group>

Reference highlighting

The beginning and end of arbitrary portions of text can be indicated using the <milestone-start> and <milestone-end> elements. These tags can indicate the portions of text to highlight in an article that is linked from a CME or quiz to describe the correct answer.

Since these are empty elements, they can be used to indicate non-hierarchical portions of the text that cannot otherwise be indicated using standard opening and closing element tags without violating XML standards. Where a <milestone-start> element is used, a matching <milestone-end> element must be used.

The <milestone-start> element must have an @id attribute. The <milestone-end> element must have an @rid attribute whose value equals the @id of the matching <milestone-start> element.

Funding information for deposit to the Funder Registry

Include information about funding of the research in the <funding-group> tag. Zipline can import the funder’s name, funder’s identifier, and associated award identifiers, and SCM6 can deposit this information to the Funder Registry. Inside the <funding-source> element, use the <institution-wrap> element with child elements <institution> and <institution-id> to designate the name and identifiers of an institution, respectively. On <institution-id>, the attribute @institution-id-type="DOI" must be present if the ID comes from the Open Funder Registry. Add @award-type="grant" to <award-group> if the content is to be deposited to PMC under either the Selective deposit agreement or the NIH portfolio agreement.

<funding-group specific-use="FundRef">
     <award-group award-type="grant">
        <funding-source>
            <institution-wrap>                      
                <institution>National Science Foundation</institution>
                <institution-id institution-id-type="DOI">10.13039/100000001</institution-id>
            </institution-wrap>
        </funding-source>
        <award-id>WU4001</award-id>
    </award-group>
 </funding-group>

If an embargo period is stored in SCM6 for a funder, articles associated with an award from that funder will automatically become available outside the paywall after that embargo period. Embargo periods for funding agencies are maintained in SCM6 and are not included in the XML.

The initial access type for an article is set during import. A license URL for an article can also be sent to Crossref. See section Permissions for information about setting access type and including licensing information.

Deprecated Funding Information Method

Use of the <named-content content-type="funder-name"> and <named-content content-type="funder-identifier"> tags to designate the funder name and identifiers (demonstrated below) is a deprecated version of tagging funding information to deposit to the Funder Registry. This method maintains backwards compatibility with previous versions of Silverchair’s specifications but should be discontinued in favor of the method described in Funding information for deposit to the Funder Registry.

<funding-group>
    <award-group award-type="grant">
        <funding-source>
            <named-content content-type="funder-name">National Science Foundation</named-content>
            <named-content content-type="funder-identifier">10.13039/100000001</named-content>
        </funding-source>
        <award-id>psychoceramics-1152342</award-id>
    </award-group>
</funding-group>

Languages

Designate the language of an article or sections of an article using the @xml:lang attribute with ISO 639–1 codes as the value. Include the attribute on the <article> element and on elements that are part of the body content of the article (“body content” used loosely, including front matter and back matter, but excluding anything in <article-meta> or <sec-meta>).

The <abstract> and <author-notes> elements may also have a language.

A language indicated at the article level will apply to the rest of the article. A language indicated within the content will cascade to descendant elements. A language applied at a lower level will take precedence over any language indicated on an ancestor element or at the article level. The language indicated at the article level will apply only to content elements, and not to <article-meta> or <sec-meta> or their elements.

To indicate a language on a span of inline text within an element’s content, use a <named-content> element with @content-type="foreign-text", and with the @xml:lang attribute.

Use the <related-article> element in the content’s text (for example, in the body of the text) to create an in-line one-way link to an article in SCM6. See Related article links for specific tagging requirements regarding the use of attributes to designate the target of the link. To create a two-way database-driven link between content, use <related-article> in the content’s metadata as described in Related article links.

CRediT Contributor Roles

The CRediT (Contributor Roles Taxonomy) Taxonomy has been written to better define and communicate the different kinds of contributor roles in research outputs. SCJATS incorporates this taxonomy on the <role> element using role attributes.

Attribute Name Definition
@vocab Name of the controlled vocabulary - ‘CRediT’
@vocab-identifier Unique identifier of the vocabulary, such as (but not limited to) a URI or DOI. For CRediT, the identifier may be https://dictionary.casrai.org/Contributor_Roles.
@vocab-term The content of the element is the display version of the vocabulary or taxonomic term. The @vocab-term attribute holds the canonical version of the same term, as it appears in the vocabulary. For example, if the attribute value was “Writer — original draft”, the element might contain the display text “Author”. Character Caution: Characters such as En Dash are used in the canonical CRediT names, and they may also be used in the content of the <role> element. But General Entities (such as –) should not be used in the value of this attribute; inside the @vocab-term value, use the Unicode character reference “—” for an En Dash.
@vocab-term-identifier Unique identifier of the term within a specific vocabulary, such as (but not limited to) an item number, an accession number, a URI, a DOI, etc.

The attribute @degree-contribution is also available on <role> to indicate the level of contribution for this contributor. The recommended values are “lead”, “supporting”, and “equal”.

The following is a tagging example for the role “writer”.

    <role vocab="CRediT" 
          vocab-identifier="http://dictionary.casrai.org/Contributor_Roles"
          vocab-term="Writing &#8212; Original Draft"
          vocab-term-identifier="http://dictionary.casrai.org/Contributor_Roles/Writing_%E2%80%93_original_draft" 
          degree-contribution="lead">writer</role>

Peer Review PDFs

Peer Review PDFs can be attached to an article. To include Peer Review PDFs, use the <supplementary-material> tag with @content-type="peer-review" and call out the name of the file in @xlink:href. Peer Review materials will be linked on the article page with a static link and can be deposited to PubMed Central.

 <supplementary-material content-type="peer-review" xlink:href="peer-review.pdf"/>

Proceedings XML requirements

Proceedings generally follow the same requirements as for journal articles, using the <article> root element. Details are given in this section for information specific to proceedings. The conference series must be configured in SCM6 before importing the XML for a proceeding itself, with matching series information, as this is how the proceeding will get correctly assigned to its series.

Conference proceedings journal metadata

The following metadata in the <journal-meta> element are recommended for conference proceedings.

Conference Proceedings Journal Metadata
Element Recommended attributes Notes
<issn> This is required.
<isbn> If the conference volume has an ISBN, include it.
Use the attribute @content-type="ISBN10" or @content-type="ISBN13" for print ISBN.
Use the attribute @content-type="eISBN" for electronic ISBN.
<publisher>/<publisher-name>

Conference article metadata

The article element requires an @article-type attribute.

Article Element for Proceedings
Element Required attributes Notes
<article> @article-type="proceedings"

The following is the required article metadata for conference proceedings.

Required Article Metadata for Proceedings
Required element Required attributes Notes
<article-title> Contain in <title-group> element.
<contrib-group> @content-type="article"
@content-type="volume"
Use @content-type="article" for proceedings authors. Put volume editors within a <contrib-group> with @content-type="volume". Volume editors will be updated every time an article is loaded to that volume.
<contrib> @contrib-type="author" (use for proceedings authors)
@contrib-type="editor" (use for volume editors)
Contain in <contrib-group> element.
<collab> Use for groups of authors credited under a single name.
<fpage> First page number. Non-numeric values such as “1a” are acceptable if this reflects the proceeding’s pagination. If page numbers are not used, a value that is the equivalent of page number (e.g. CID) should be put in <fpage>.
<lpage> Required if different in value from <fpage>.
<self-uri> @xlink:href="proceeding_pdf.pdf" Required if a PDF of the proceeding is present.
<permissions> Copyright statements go here. Multiple copyright statements, years, and holders are permitted.
Recommended Article Metadata for Proceedings
Recommended element Required attributes Notes
<article-id> One of the following for each element:
@pub-id-type="doi"
@pub-id-type="publisher-id"
DOIs are required to enable some SCM6 functionality, including automated article replacement, duplication checking, and Crossref deposits. Proceeding articles may have multiple <article-id>.

Automatic replacements

Zipline will use an article’s DOI or publisher ID to automatically identify duplicate articles and make replacements. DOI will trump publisher ID for the purpose of matching articles. If the journal or conference is live, then an imported article will replace an article already in the system that has a matching DOI or publisher ID. If the journal or conference is not live—for example, while importing backfile content—then articles will be imported as new.

Conference hierarchy metadata

The conference metadata includes the full conference hierarchy for the proceeding, plus information about the volume and the session within the volume. The metadata must match for each proceeding in the volume; otherwise the system will create a new volume with the conference hierarchy specified in the metadata. The proceeding is matched to an existing conference series by <conference content-type="conf-level-1"> with a child of <conf-acronym> with a value that has already been set up in SCM6.

Conference hierarchy metadata

Conference Hierarchy Metadata
Required element Required attributes Notes
<conference> @content-type="conf-level-1"
and
@content-type="conf-level-2"
Two conference levels are supported. “conf-level–1” indicates the conference series information. “conf-level–2” indicates the conference itself. The <conference> element is the parent of the following elements. Note that both levels are required in the xml.
<conf-date> [2] To indicate only the start date of the conference, the format is <conf-date>YYYY-MM-DD</conf-date>. If you want to specify start and end dates for a conference, please use the format <conf-date>YYYY-MM-DD|YYYY-MM-DD</conf-date> (note the pipe delimiter between the dates). If you’d like for the conference to have only a month as the date, please include 00 in place of the day. Example: <conf-date>2012-05-00</conf-date> would display as “May 2012”.
If there is no date for the conference series (i.e., “conf-level–1”), then include <conf-date> as an empty element to satisfy JATS requirements. At least a start date is required for the conference itself (i.e., “conf-level–2”).
<conf-name> Spelling, case, and punctuation must be consistent for all proceedings in a conference.
<conf-acronym> This is a short identifier for the conference.
<conf-num> Optional.
<conf-loc> [2] Spelling, case and punctuation must be consistent for all proceedings in a conference.
<conf-sponsor> Optional.
<conf-theme> Optional.

Conference XML example

Below is an XML snippet that shows the metadata described above (volume and session are described below).

<conference content-type="conf-level-1">
    <conf-date />
    <conf-name>Annual Conference</conf-name>
    <conf-acronym>AC</conf-acronym>
    <conf-num>30</conf-num>
</conference>
<conference content-type="conf-level-2">
    <conf-date>2012-03-06|2012-03-10</conf-date>
    <conf-name>Annual Yearly Conference for 2012</conf-name>
    <conf-acronym>YC12</conf-acronym>
    <conf-num>1234567</conf-num>
    <conf-loc>Charlottesville, VA USA</conf-loc>
    <conf-sponsor>Society of Conference Sponsors</conf-sponsor>
    <conf-theme>Managing Change</conf-theme>
</conference>
<conference content-type="volume">
    <conf-date/>
    <conf-name>Managing Change 2012</conf-name>
    <conf-num>123</conf-num>
    <conf-sponsor>Managing Change Managers</conf-sponsor>
</conference>
<conference content-type="session">
    <conf-date/>
    <conf-name>Change in Organizations</conf-name>
</conference>

Volume metadata

The volume metadata is required for all proceedings articles.

Conference Volume Metadata
Required element Required attributes Notes
<conference> @content-type="volume" Information about the conference volume will go here. The <conference> element is the parent of the following elements.
<conf-date/> [3] If no date is available, include an empty element to satisfy JATS requirements.
<conf-name> [3] Put volume name here. The volume name must be consistent across all proceedings in the volume.
<conf-num> Volume number goes here.

If the conference volume has a sponsor, put that in a <conf-sponsor> element. This is optional.

Session metadata

A conference session is also known as a conference section. These are different headers within the volume. The conference session metadata is optional.

Session Metadata
Required element Required attributes Notes
<conference> @content-type="session" The <conference> element is the parent of the following elements.
<conf-date /> A session date cannot be assigned. Include as an empty element to satisfy JATS requirements.
<conf-name> Put session name here.

Conference authors

Volume editors

To specify one or more volume editors, use a <contrib-group> with the attribute @content-type="volume" as follows:

<contrib-group content-type="volume">
    <contrib contrib-type="editor">
        <name><surname>Young</surname><given-names>John G.</given-names></name>
    </contrib>
</contrib-group>

The <contrib-group> should be included in the <article-meta> section.

Conference volume editors will be updated every time an article is loaded to that volume. Conference volume editors must therefore be included with all content.

Proceedings authors

Authors go into a contrib-group as follows:

<contrib-group content-type="article">
    <contrib contrib-type="author">
        <name><surname>Young</surname><given-names>John G.</given-names></name>
    </contrib>
</contrib-group>

Body

Sections and paragraphs

Sections can be nested to form sub-sections. Sub-sections intended to be at the same sub-section level should appear in the XML in <sec> elements at the same nested level.

The paragraph element <p> describes block-level text. Paragraph elements cannot be nested. Each <p> element does not necessarily need to represent a single key point, thought, or topic as in the common definition of a paragraph. For example, if a list appears in the middle of a paragraph (in the common sense), then the paragraph should be split into two separate <p> elements with a <list> element in between.

Automatic numbering

Automatic numbering of figures (and analogous elements such as tables and boxed text) is not provided. If numbering is wanted the numbers should be provided in the <title> or <label> element contents.

<fig id="f1">
    <label>Fig. 1</label>
    <caption><p>A schematic of … </p></caption>
    <graphic xlink:href="JBO_17_2_026001_f001.png"/>
</fig>

The exception to this requirement is bibliographic references, which will be automatically numbered if no numbering is provided.

Nesting special content elements

Certain content elements—figures, tables, boxed-text, graphics, media, supplementary material, lists, and verse groups (poems)—can have special display characteristics enabled on SCM6. For example, clicking on a figure may enlarge the image, or tables may be listed in an index of tables.

Nesting these elements inside any other special element, or inside a paragraph element, may cause those special display characteristics to fail. In general, nesting these elements should be avoided if they need to be detected for special display logic.

Figures and graphics

Figures

Figures (<fig>) should be placed after the paragraph in which they are cited, not mid-paragraph. If more than one figure or table is cited in any particular paragraph, they should be placed in the order they are cited. If they are cited in a list item, they should be placed after the (outermost) closing list tag.

<p>... in <xref ref-type="fig" rid="f1">Fig.&#xA0;1</xref>. The ...</p>
<fig id="f1"><label>Fig. 1</label><caption><p>...</p></caption><graphic xlink:href="XXX_22_2_026001_f001.png"/></fig>

<fig> elements should be used for formal figures, especially when numbered and/or captioned. If your site includes features such as an index of figures, figure carousel, or tab of figures, the <fig> element designates the items that appear in those features.

If a figure has more than one image part, and the image parts require labels, use the <fig-group> element. For example, the group of figures may have a caption, with the internal figures each having their own label and caption.

The @id attribute must be used on the <fig> or the <fig-group> if they will be referenced from the body of the text using an <xref>.

The <graphic> element within the <fig> is used to point to the external file containing a still image. A <graphic> must have an attribute @xlink:href, whose value should be the exact file name of the image. Provide only the literal file name relative to the directory specified for the file in the appropriate packaging guidelines. For example, a figure image stored directly in the Assets directory should use @xlink:href="image.png" without a file path preceding the file name.

To designate a figure image as restricted, include the <permissions> element as a child of <fig>, with a <license license-type="restricted"> element inside the <permissions>. Restricted images can prevent download of the image, for example.

Figures can be assigned a unique identifier such as a DOI using the <object-id> tag within the element. The @pub-id-type attribute must be included with a value of either “doi” or “publisher-id”.

Graphics

The <graphic> element can also be used without a <fig>. A <graphic> can be placed either outside or inside a paragraph, and will appear on its own line in either case.

This tagging should be used for images that are not numbered and may or may not have a label, such as author headshots. These images will appear within the text of the document, without a pop up. These images will not appear in features such as the table of figures.

Inline graphics

Inline graphics appear within a line of text, and are tagged using the <inline-graphic> element. An <inline-graphic> must have an attribute @xlink:href, whose value should be the exact file name of the image.

<p>The temperatures rose 20 degrees <inline-graphic xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="sparkline.png" /> in 20 minutes. ...</p>

Tables

Use the <table-wrap> element to include tables. The element may contain a <label> and <caption>, and must contain a <table> or <graphic> element. Include XML content for the table in <table>. To provide the table content in the form of an image, use the <graphic> element to point to the image file instead of using the <table> element.

Like figures, tables should be placed after the paragraph in which they are cited, and not mid-paragraph.

A <graphic> must have an attribute @xlink:href, whose value should be the exact file name of the image. Provide only the literal file name relative to the directory specified for the file in the appropriate packaging guidelines. For example, a table image stored directly in the Assets directory should use @xlink:href="image.png" without a file path preceding the file name.

If a group of tables should be treated as a unit, group tables using the <table-wrap-group> element. For example, the group of tables may have a caption, with the internal tables each having their own label and caption.

The @id attribute must be used on the <table-wrap> or <table-wrap-group> if the table will be referenced by an <xref> from elsewhere in the article.

Tabular formatting

To apply tabular formatting to content without the full-fledged table treatment (e.g. listing in table of tables, expandable thumbnails, downloads), use either the <table-wrap> element with a @specific-use="inline" attribute or the <array> element. The element <table-wrap specific-use="inline"> allows a label, title, caption, and column headings while the <array> does not. However, the <array> element is commonly understood whereas the use of <table-wrap specific-use="inline"> is idiosyncratic to SCM6.

Sidebars and boxed-text

Use the <boxed-text> element without a @content-type attribute for a boxed-text that is not a sidebar.

For sidebars, use the <boxed-text> element with special flags on the @content-type attribute. There are three types of sidebars allowed, in three sizes, as indicated by the value of the @content-type attribute:

Placement in XML is indicative of online placement; for instance, if a sidebar or box is placed between two paragraphs, that is where it will appear on the web site.

Like figures and tables, sidebars and boxed-text may be numbered by using <label>, and can include a <caption>. The @id attribute must be used on the <boxed-text> if the boxed text will be referenced by an <xref> from elsewhere in the article.

Sidebars and boxed text should not be placed mid-paragraph.

Multimedia

Include video, audio, or models in a <fig> element with attribute @fig-type="video", @fig-type="audio", @fig-type="model", respectively. The <fig> element for multimedia must have a child <media> element instead of a <graphic> element. The <media> element within the <fig> designates the multimedia file or location.

Place the <fig> element after the paragraph in which it is cited, not mid-paragraph. If more than one figure or table is cited in any particular paragraph, they should be placed in the order they are cited. If they are cited in a list item, they should be placed after the (outermost) closing list tag.

Do not include multimedia inside a <fig-group>.

The @id attribute must be used on the <fig> if the multimedia will be referenced from the body of the text using an <xref>.

Multimedia can be assigned a unique identifier such as a DOI using the <object-id> tag as a child of the <fig> element. The @pub-id-type attribute must be included with a value of either “doi” or “publisher-id”.

Brightcove

Use Brightcove content for multimedia by using @content-type="brightcove" on the <media> element.

To identify the video in Brightcove, one of either the Brightcove Video ID or Brightcove Reference ID must be included using <object-id pub-id-type="videoid"> and <object-id pub-id-type="referenceid">, respectively, as a child of the <media> element. Both may be included. Optionally, include Brightcove’s shortened URL for the video in the @xlink:href attribute. Do not include other Brightcove metadata in the XML.

Note that the <object-id> under the <media> element points to the video in Brightcove, while the <object-id> under the <fig> assigns an ID to the figure/video/audio.

<fig id="video1" fig-type="video">
    <object-id pub-id-type="doi">10.9999/SSC_20120928_v107i3_043_video1</object-id>
    <label>Video 1</label>
    <caption><title>Fluoroscopy</title><p>Video of fluoroscopy.</p></caption>
    <media content-type="brightcove" xlink:href="http://bcove.me/hky4pn1o">
        <object-id pub-id-type="videoid">123456789</object-id>
        <object-id pub-id-type="referenceid">myVideo1</object-id>
    </media>
</fig>

Sketchfab

Use Sketchfab content for multimedia by using @content-type="sketchfab" on the <media> element.

To identify the model in Sketchfab, the model ID must be included using <object-id pub-id-type="modelid"> as a child of the <media> element.

Note that the <object-id> under the <media> element points to the model in Sketchfab, while the <object-id> under the <fig> assigns an ID to the model in our system.

<fig id="model1" fig-type="model">
    <object-id pub-id-type="doi">10.9999/SSC_20120928_v107i3_043_model1</object-id>
    <label>Model 1</label>
            <caption><title>Model Title</title><p>Description of the model.</p></caption>
            <media content-type="sketchfab">
                 <object-id pub-id-type="modelid">123cf4cc5d67e89f1bf0000ad123df456</object-id>
            </media>
    </fig>

Math and equations

Equations must be placed in a <disp-formula> element or an <inline-formula> element. Both formula elements may contain text, MathML, LaTeX, TeX or images. The <inline-formula> may not contain a <graphic>, but may contain an <inline-graphic>.

Equations appearing on their own line should be contained in a <disp-formula> element. The <disp-formula> element may be placed inside or outside a <p>. To label the formula—for example, with a number that appears to the right of the formula—include the label text in a <label> within the <disp-formula>. The <disp-formula> may be referenced by an <xref>; if the formula will be referenced, an @id attribute must be included.

Equations appearing within a line of text should be placed in an <inline-formula> element. The element should appear within a paragraph (<p>) or other element containing text. Inline formulas cannot be referenced by an <xref>.

Mathematical equations can be described using MathML contained in the <mml:math> element. If both an image and MathML have been provided for a particular equation, we will display the image. The image file name is declared in the @altimg attribute value on the <mml:math> element and it must match the file supplied. If no image is provided, we will display the formatted MathML.

XML Schema allows use of any namespace prefix for the MathML elements. However, the MathML elements must use “mml” as the namespace prefix to validate to the JATS DTD.

Mathematical equations can also be described using LaTeX or TeX contained in the <tex-math> element. Further wrap the LaTeX markup in CDATA or escape special literal characters (e.g. ampersands) to prevent them from invalidating your XML document.

Details in the MathML documentation may be found at http://www.w3.org/TR/MathML2/.

Statements

Include formal statements such as theorems, lemma, and proofs in a <statement> element.

Lists

Place lists inside the <list> element. The <list> element should not be placed within a <p> element. The @list-type attribute can be used to designate the type of list as follows. If no @list-type is provided, the list will default to a simple list. Do not include the list item character (i.e. numbering or bullets) in the content; this will be generated automatically.

List types
list-type attribute Default list item character Notes
simple n/a Gets list indentation, but no character in front of each item. Sometimes called “unordered”.
bullet
number 1, 2, 3
alpha-lower a, b, c
alpha-upper A, B, C
roman-lower i, ii, iii, iv
roman-upper I, II, III, IV

Poems

Poems can be included in the <verse-group> element. The <verse-group> element should not be placed within a <p> element.

Cross-references

Cross-reference links to items within the same XML document are indicated with the <xref> element. (However, for a book supplied as one XML document, chapter-to-chapter links must use <related-object> as described in Related content.) The @ref-type attribute indicates the element type of the cross-reference target and the @rid provides its id value; @rid is required except for links to the list of supplementary data (see Supplementary material).

SCM6 supports the following different <xref> types, and specific behavior should be confirmed with the build team. Attribute types for <xref ref-type>:

Ref types
ref-type attribute Notes
aff Affiliation
app Appendix
author-notes Author notes
bibr Bibliographic reference
boxed-text Textbox or sidebar
corresp Corresponding author
disp-formula Display forumula
fig Figure or group of figures
fn Footnote
other None of the other items listed
sec Section
supplementary-material Supplementary material file
table Table or group of tables
table-fn Table footnote

An <xref> element used to designate an affiliation for a contributor must also have a @ref-type="aff" attribute. An <xref> element used to connect a contributor to a Conflict of Interest statement in <author-notes> should have a @ref-type="author-notes". Similarly, an <xref> element used to connect a contributor to a footnote indicating equal contribution in <author-notes> should have a @ref-type="author-notes".

Except for references to author affiliations, correspondence information for authors, bibliographic references, and Conflict of Interest statements, the content of the element—often the figure number—must be included. Provide literal content for display as shown by the “4(g)” in this example:

See figure <xref ref-type="fig" rid="f4">4(g)</xref>.

If the bibliographic references in the <ref-list> section have an @id attribute, then SCM6 can generate the display text for the link automatically, and this method is preferred.

Jones<xref ref-type="bibr" rid="bib2" /> shows that…

The @rid attribute may have multiple values; separate each value with a space. If a document has a string of cross references either a single <xref> can link to all the reference in the string or each reference can have an <xref>. So, if a document contains:

… widely discussed [1, 2, 3] in the …

you may either tag:

… widely discussed [<xref ref-type="bibr" rid="r1" />, <xref ref-type="bibr" rid="r2" />, <xref ref-type="bibr" rid="r3" />] in the …

(cross references to bibiographic references can take the label from the target)

or

… widely discussed [<xref ref-type="bibr" rid="r1 r2 r3">1, 2, 3</xref>] in the …

or

… widely discussed [<xref ref-type="bibr" rid="r1">1</xref>, <xref ref-type="bibr" rid="r2">2</xref>, <xref ref-type="bibr" rid="r3">3</xref>] in the ….

You may also include the content as a range. The following would appear as “… widely discussed [1–3] in the …”.

… widely discussed [<xref ref-type="bibr" rid="r1 r2 r3">1–3</xref>] in the …

Content outside of the XML file can be cross-referenced using the <related-object> element. See Related content for guidance in structuring those links.

Use the <ext-link> element for links external to SCM6 from the content’s text. The @xlink:href attribute should be used to indicate the location of the external content.

References

References or bibliographic citations should be tagged inside <ref-list>. Each bibliographic entry should be in a <ref> element.

References should be tagged at as granular a level as possible to enable SCM6 to query PubMed, Crossref or other online databases; retrieve citation information and turn it into a live link; and format citations on the site. Granular tagging also enables any other functionality based on references that may be desired on the site.

Silverchair recommends that at least these elements should be tagged:

SCM6 can create links to PubMed and Crossref for journal articles referenced in the references section. For SCM6 to determine and create these links, the @publication-type="journal" attribute must be included in the <element-citation> or <mixed-citation> element.

Crossref, PubMed, arXiv, and Web of Science information may optionally be supplied with the references by including a <pub-id> element. Use the attribute @pub-id-type="doi" for a DOI, @pub-id-type="pmid" for PubMed ID, @pub-id-type="arxiv" for arXiv, and @pub-id-type="wos" for Web of Science.

The system provides formatting and punctuation for <element-citation>, while <mixed-citation> is formatted and punctuated from the source data.

If you are using <element-citation>, we suggest you preview the rendition of your data in our system to ensure good results.

<element-citation publication-type="journal" publication-format="print">
    <name><surname>Carila</surname><given-names>RC</given-names></name>
    <name><surname>Poole</surname><given-names>JM</given-names></name>
    <name><surname>Keefe</surname><given-names>LE</given-names></name>
    <name><surname>Wan</surname><given-names>L</given-names></name>   
    <article-title>Blood pressure levels among sedentary workers</article-title>   
    <source>J Dem Diseases</source>
    <year>2012</year>
    <month>Jan</month>
    <volume>32</volume>
    <issue>1</issue>
    <fpage>112</fpage>
    <lpage>116</lpage>   
</element-citation>

If you are using <mixed-citation> the XML must include all punctuation and spacing (such as the space between the <surname> and <given-names> below) as it should be displayed.

<mixed-citation publication-type="journal" publication-format="print"><string-name><surname>Carila</surname> <given-names>RC</given-names></string-name>, <string-name><surname>Poole</surname> <given-names>JM</given-names></string-name>, <string-name><surname>Keefe</surname> <given-names>LE</given-names></string-name>, <string-name><surname>Wan</surname> <given-names>L</given-names></string-name>. <article-title>Blood pressure levels among sedentary workers</article-title>. <source>J Dem Diseases</source>. <year>2012</year> <month>Jan</month>; <volume>32</volume>(<issue>1</issue>): <fpage>112</fpage>–<lpage>116</lpage>.</mixed-citation>

Note: some users prefer to use <element-citation> for citations types such as articles, where automatic formatting is likely to be satisfactory and use <mixed-citation> for unusual citation types (e.g., court cases, unpublished letters) where the citation format is more unique.

The <ref> element must have an @id attribute if it is linked from elsewhere in the content using an <xref>.

Data citations

When citing a data set, use @publication-type="data". Use @person-group-type="curator" on <person-group> when appropriate. Include at least one of <data-title> (name of data set) or <source> (name of repository holding the data). Wrap the repository ID in <pub-id> and include the full URI to the data, if known, in @xlink:href. Use @assigning-authority on <pub-id> when appropriate to identify the group responsible for the identifier.

 <mixed-citation publication-type="data"> ... <data-title>Dataset 10</data-title> <source>FigShare</source>. <pub-id pub-id-type="doi" assigning-authority="figshare" xlink:href="http:doi.org/10.6084/m9.figshare.815894">10.6084/m9.figshare.815894</pub-id>.</mixed-citation>

Footnotes

Footnotes should be included in an <fn-group> element, with each footnote in an <fn>. The <fn> element must have an @id attribute if it is linked from elsewhere in the content using an <xref>. Footnotes provided in any other section of the document will display in the section where they appear instead of as a separate footnotes section.

Image maps

To include an image map, list the coordinates and corresponding links in <ext-link> elements inside the <graphic> node. Put the coordinates in a <named-content content-type="coordinates"> element. Linked areas will be rectangular. List the coordinates in order x1,y1,x2,y2, where:


  1. Either <fpage> or <elocation-id> is required.  ↩

  2. Conference location, start date, and end date will be updated every time an article is loaded to the conference. The information must therefore be included with all content.  ↩

  3. The volume date and volume name will be updated every time an article is loaded to that volume. The volume date and name must therefore be included with all content.  ↩