Document Revision History
Date Description Version
See consolidated revision history page

# Introduction

Silverchair has created SCBITS, a custom XML specification for loading book XML into SCM. SCBITs is based on the Book Interchange Tag Suite (BITS) version 2.0, which is maintained by the NLM and based on NISO’s Journal Article Tag Suite (JATS). XML content for book content must be valid against the SCBITS XML Schema and additional rules stated herein.

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

The documentation provided by the NLM at https://jats.nlm.nih.gov/extensions/bits/tag-library/2.0/index.html is an excellent resource to supplement the information contained in this document. The key to transforming data to conform to the SCBITS 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 SCM.

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 in a zip package on the main specifications site http://specifications.silverchair.com/.

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.

## Sample XML Files

The following sample files have been provided in the Silverchair specifications zip package to illustrate commonplace examples of platform features. These XML files are provided alongside the Silverchair XSD files as representative, but not authoritative, samples and should be considered supplemental only.

# 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:

• XML version
• Character encoding

Example:

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


## Special characters

UTF–8 character encoding is required to ensure that characters are translated properly upon import into the SCM 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 the 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̇.

# Translating print books to the web

The layout and formatting of a print book and its presentation on the web are different things. There are a number of consequences that are not immediately apparent that require XML prepared for the web to be different from XML prepared for print. Some of these differences are things that if incorporated into the authoring process early enough, can save time and effort down the road and result in a highly readable book both in print and online. An excellent example of this is found in Referencing other parts of the text.

## Referencing other parts of the text

References in the text such as, “See page 288,” do not work on the web because page numbers don’t exist on the web. Instead, phrases such as “See Figure 2–1” and “See Chapter 45, Section 3: The Body’s Response to Insulin” work well on the web because one can navigate to and find these items.

You cannot specify exact placement of components on the web the way you can in print. Thus, text such as “See top image” is better written as “See Image 54” for use on the web. Image 54 might not be above the referencing text in the online display.

It is also possible to create hyperlinks in the XML document by using internal identifiers. Ideally, referenced content would have an ID and the referring text would have a link that uses the ID to point to the referenced text.

## Word-wrap

Words that wrap on the printed page and therefore have a hyphen between syllables do not need that treatment on the web because you cannot control the width of the text display area. Various devices such as mobile phones, tablets, laptops, and desktop monitors may have a variety of screen sizes that web display must accommodate. If you are converting a book originally designed for print into web format, the hyphens that exist solely for word-wrapping reasons need to be removed. The same is true of long URLs where a space was inserted at the end of a line. These URLs will not work as links with spaces in them.

## Tables

You can do things with tables in print that are not supported by today’s browsers and markup languages or that are not compatible with the web. For example, tables cannot be turned sideways on the web. Very large tables that are displayed over several print pages need to be reassembled into a single table for web display.

## List numbering

Numbers and bullets do not need to be included in the XML text for lists that are tagged as numbered or bulleted lists. The system will automatically number or bullet lists based on the list tagging. If the numbers are included in the text, the display on the web will show two numbers or bullets in front of each list item, one from the system automation and one from the text.

## Section titles

Section titles are converted into HTML headings on the site. These headings are styled based on the hierarchy of the sections within the document.

SCM does not support figures or tables as part of a section title. Inline-graphics are supported.

# Book File Structure

The root element of a book must be the either the <book> element or the <book-part-wrapper> element from the SCBITS format.

Silverchair accepts book XML in one of two ways:

1. The entire book in one XML file.
2. Separate XML files for each part or chapter.

## Book as single XML file

When a book is sent as a single XML file, the book file root element is <book>. Parts and chapters are identified throughout the XML with <book-part> elements.

## Book as multiple XML files

For book parts sent as separate XML files, the root element is <book-part-wrapper>.

## Book type attribute

Book types are used for indexing and retrieval by engines like Google Scholar. This attribute is optional, but the use of Google Scholar-recognized values (i.e., “edited-volume” or “monograph”) is strongly recommended. If no book type is provided, the value will default to “book” in our system. Note that Google Scholar considers the value “book” to be invalid and will not crawl your site if it is used.

@book-type attribute value Meaning
book Default value with no specific meaning. Google Scholar considers this value invalid and will not crawl your site if it is used. Avoid using this value if possible. Use one of the values below instead.
edited-volume Composed of papers written by many different authors. Individual chapters will be indexed by Google Scholar.
monograph Multi-chapter authored book on a single topic. Individual chapters will not be indexed by Google Scholar. Instead, the Monograph Preview (frontmatter, table of contents, introduction chapter, and references) will be indexed.

## Identifiers

### ISBN

The ISBN uniquely identifies books in SCM and is required. For example, to match a new chapter to its already-created book in the system, Zipline uses the ISBN values. The final digit in the ISBN is a check digit, which is a rule used to verify that the ISBN is valid. If the ISBN is not valid, it will not be deposited to Crossref.

The ISBN will be displayed on the site exactly as shown in the XML, so be sure to use dashes as appropriate. Note that we recommend retaining the spaces or hyphens that appear in the formatted number because they aid in human readability. Use the <isbn> element with the following attributes to designate the ISBN:

ISBN type tag
10-digit ISBN <isbn publication-format="print" content-type="ISBN10">0-77-043740-0</isbn>
13-digit ISBN <isbn publication-format="print" content-type="ISBN13">978-0-77-043740-4</isbn>
ISBN of digital version <isbn publication-format="electronic">978-0-31-603221-6</isbn>

### Publisher ID - book

For publisher-unique IDs assigned to the book, use <book-id book-id-type="publisher-id">. The book-level publisher ID is optional and does not affect Zipline behavior.

### Publisher ID - Parts and Chapters

Assign publisher-unique IDs to book parts (e.g. parts and chapters) using the @id attribute on the element that creates the book part (e.g. <book-part>).

Publisher IDs must be unique within the book. They can be any combination of numbers and letters but must start with a letter, per XML rules.

### Publisher ID - other elements

Publishers may have IDs on as many other elements as they like, and this is encouraged by Silverchair. Publisher IDs at levels below the book part must also be unique across the book (they cannot duplicate the Publisher IDs on book parts).

Unique identifiers allow for the replacement of content while maintaining semantic tagging, retaining statistical usage data, Learning Module links, user bookmarks and cross-site links.

### DOI

For DOIs assigned to the book, use <book-id book-id-type="doi">.

For DOIs assigned to a book chapter or other book parts, use <book-part-id book-part-id-type="doi">.

<book-part-id book-part-id-type="doi">10.1234/myBook_3352.2013</book-part-id>


For DOIs assigned to figures, tables, supplementary material or any other components within the book, use the <object-id> element with a @pub-id-type="doi" attribute. Example:

<fig>
<object-id pub-id-type="doi">10.1234/ch8fig1.20130413</object-id>
...
</fig>


DOIs are optional and do not drive replacement functionality in Zipline.

DOIs within citations are tagged differently. They use the <pub-id> element. See DOIs in References for more information.

### ISSN

To assign an ISSN to a book (optional), use <issn> with the @publication-format="electronic" attribute.

### Book Series

To assign a Book Series to a book (optional), use <collection-meta collection-type="series"> with a <title-group> with a child element <title>. Example:

     <collection-meta collection-type="series">
<title-group>
<title>Book Series</title>
</title-group>
</collection-meta>


### Collection

To assign a generic Collection to a book that is not a series or edition set (optional), use <collection-meta collection-type="collection"> with a <title-group> with a child element <title>. Example:

     <collection-meta collection-type="collection">
<title-group>
<title>Collection Name</title>
</title-group>
</collection-meta>


### Edition Set

To designate an Edition Set for a book (optional), use <collection-meta collection-type="edition-set"> with <collection-id collection-id-type="editionSet">.

 <collection-meta collection-type="edition-set">
<collection-id collection-id-type="editionSet">9790000000204</collection-id>
</collection-meta>


This identifier is used to connect multiple editions of the same book, and it must be numeric. Use the same identifier value for every edition of the book (for example, some publishers use the ISBN value of the first edition to connect all editions). Only one <collection-meta collection-type="edition-set"> is allowed per book.

## Book metadata: The book-meta Tag

The first file imported for a book must include at least the following in the <book-meta>, so that the system can populate the data when the book is created:

Element Required attributes Notes
<pub-date> 4-digit year required, with month and day optional, e.g. <pub-date><year>2013</year></pub-date>
<isbn> At least one ISBN is required.
<book-title>
<alt-title alt-title-type="short-name">

When replacing a book’s meta-data for a book that has been published, the following values must match what is already in the system; these values cannot be modified after a book is published:

• short name
• ISBN
• ISBN 10
• ISBN of the electronic version
• title
• subtitle
• citation name
• DOI

Consult the Zipline user guide for instructions on how to replace book metadata.

### Book IDs

The ISBNs serve as unique identifiers for books in SCM. The first file that is imported to a book will create the book in the system and establish the ISBNs for the book. All subsequent imports to the book must contain the ISBN so that the system can match the file to the existing book. The subsequent files do not need to contain all of the ISBN types, but cannot contain more ISBN types than are in the system.

### Book titles

Books may have up to five types of titles: book title, subtitle, display name, citation name, and short name:

• Book title is the official title of the book.
• Subtitle is the subtitle for the book (combined with the official book title on import).
• The display name, if configured, will display on the site instead of the official book title + subtitle; consult with your build team to activate this configuration.
• Citation name is used when creating citations for the book or when the book is sent to a third-party site such as Crossref.
• The short name is usually a short code to identify the book.

The title and short name are required when creating a new book; the others are optional. If no alternate titles are provided, the official book title + subtitle will be used for display and for submission to third-party sites such as Crossref.

Provide titles as follows:

title type Element Notes
book title <book-title> Required. The official title of the book.
subtitle <subtitle> An optional subtitle. Combined with the official book title on import.
display name <alt-title alt-title-type="display"> Optional. If configured, display name will display on the site instead of the official book title + subtitle. If not provided or configured, book-title + subtitle will display.
citation name <alt-title alt-title-type="citation"> Optional. If citation is not provided, the book title + subtitle will display and be submitted to third part sites such as Crossref.
short name <alt-title alt-title-type="short-name"> Required. Short code used to identify the book, often used to prefix image names and ID values. This does not usually display on the site.

### Edition

Provide the book’s edition in the <edition> element. Do not include the edition in the title of the book. Use the @designator attribute to include the edition number as an unadorned numeric or alphabetic value. In the example below, the value “1” will be stored for purposes such as sorting, while “1st edition” could be used for display.

<edition designator="1">1<sup>st</sup> edition</edition>


### Volume

Provide a book’s volume number in the <book-volume-number> element.

    <book-volume-number>13</book-volume-number>


### Contributors

#### Book level vs. chapter level contributors

Contributors at the book level go in the <contrib-group> at the <book-meta> level.

Part and chapter level contributors go into the <contrib-group> at the <book-part-meta> level.

Contributors may also be included at the section level by putting a <contrib-group> at the <sec-meta> level.

<book>
<book-meta>
…
<contrib-group>
<contrib id="ed1">
<name>
<surname>Bear</surname>
<prefix>Dr</prefix>
<suffix>Jr</suffix>
</name>
<degrees>MD, PhD</degrees>
<role>Editor</role>
</contrib>
</contrib-group>
…
</book-meta>
<book-body>
<book-part id="chapter_1" book-part-type="chapter">
<book-part-meta>
<title-group>
<title>Forest Fire Safety</title>
</title-group>
<contrib-group>
<contrib id="auth1">
<name>
<surname>Bear</surname>
<given-names>Smokey</given-names>
<prefix>Dr</prefix>
</name>
<degrees>PhD</degrees>
</contrib>
</contrib-group>
…
</book-part-meta>
</book-part>
</book-body>
</book>


#### Tagging

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 unless configured with the development team prior to loading. Please note that any @contrib-type value other than “author” will need a configuration turned on by the development team to display.

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 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">. Please note that equal contributor information is not currently imported into our system for books.

You can use the @initials attribute on <surname> and <given-names> if contributor initials are made available in your XML authoring workflow. This attribute is not imported by our platform.

#### ORCID iD

Include an ORCID iD 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 iD. Specify the ORCID iD 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.

To be accepted by Crossref, the ORCID iD must pass a checksum using a check digit, which is the last character of the ORCID iD.

#### 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. The element <string-name> can be used for personal names where the order of the name components should not be enforced.

<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>


If the intention is to provide the author’s name in multiple languages, the @name-style and @xml:lang attributes should be used when supplying multiple versions of a name for proper display. The value for the @xml:lang attribute needs to be a valid ISO 639–1 language code.

<contrib contrib-type="author">
<name-alternatives>
<name name-style="western">
<surname>Zhang</surname>
<given-names>Y. P.</given-names>
</name>
<string-name name-style="eastern" xml:lang="zh">张轶泼</string-name>
</name-alternatives>
</contrib>


#### 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, 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.

#### ROR IDs

An ROR (research organization registry) ID can be included within <institution-wrap> in the <aff> node to connect a contributor to a given research organization. If ROR IDs are included in the xml, they will be stored in our database and deposited downstream. Please note that ROR IDs will not display.

Within the <institution-wrap> element, use <institution-id> with @institution-id-type="ror" to contain the ROR ID and <institution> to contain the associated organization name.

<aff id="aff1">
<label>a</label>
<institution-wrap>
<institution-id institution-id-type="ror">https://ror.org/03vek6s52</institution-id>
<institution>Harvard University</institution>
</institution-wrap>
Cambridge, MA 02138, <country country="us">United States</country>
</aff>


If a contributor is affiliated with more than one research organization, please include a separate <institution-wrap> for each organization within the <aff> element. Note that although <institution-wrap> is allowed in other locations, it will only be imported as a contributor ROR ID when used in <aff>. In other locations, such as within <funding-source>, this information will simply be copied.

#### 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.

Please note that this feature is currently only supported for journals and proceedings. Although <on-behalf-of> is allowed in SCBITS, it is not currently imported into our system or displayed for books.

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:

• <author-comment content-type="disclosure">
• <author-comment content-type="deceased">
• <author-comment content-type="other">
• <author-comment content-type="occupation">
• <author-comment content-type="url">

Please note that import and display of author comments with a @content-type value of “occupation” or “url” is currently only supported for books. Please also note that for books the display of these types of author comment (ie, “occupation” and “url”) is configurable by client, so consult with your development team about whether you would like these to appear on your site.

#### 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.

Generally, acknowledgements should be included in the <ack> section of the <book-back>. Many larger books are edited by one or more persons and chapters are authored by a different group of individuals. Use <author-comment> when an individual chapter author wishes to include an acknowledgement or comment that is relevant for that individual author only and not any of the other chapter authors. For acknowledgements or notes by all the chapter authors, use the <author-notes> tag in the <book-part-meta> section. You may also use the <author-notes> tag at the <book-meta> level for notes applicable to all book authors if there is a need to differentiate the notes from acknowledgements.

### Dates

The publication date for the book should be included in a <pub-date> node.

To supply a date, the following options are available:

• Supply at least a <year> in numerical form. Optionally, also provide <month> in non-numerical (e.g. <month>January</month>) or numerical form and provide <day> in numerical form.
• Supply a date in ISO 8601 format using an @iso-8601-date attribute and the format YYYY-MM-DD.
• Supply a publication format using the @publication-format attribute.

If the date is provided in a form other than numerical month, day, and year, then the @iso-8601-date attribute must be included to supply a numerical publication date. In this case, the year, month, and day provided can be used for display, while the @iso-8601-date value is used as the underlying publication date by the system.

If an ISO 8601 date is not provided and only a <year> is supplied, January 1st of that year will be used as the underlying publication date by the system.

If a distinction between print and electronic publication date is needed, then the @publication-format attribute should be included. Use <pub-date publication-format="ppub"> to indicate a print publication date and <pub-date publication-format="epub"> to indicate an electronic publication date.

For date support on chapters, see section Chapters.

### Document history

The <pub-history> element is used as a container for dates related to the processing history of the document, such as received date and accepted date, or the version history of the document.

Processing history is optional and can be included in both the book and book-part levels.

<book-meta>
…
<pub-history>
<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>
<date date-type="reviewed">
<day>08</day>
<month>06</month>
<year>1998</year>
</date>
</pub-history>
…
</book-meta>


#### Chapter Versioning

Version history is optional and can only be included at the chapter book-part level (i.e., <book-part book-part-type="chapter">). It is presumed that when a book is initially published, chapters will not have version metadata. However, all subsequent versions must include metadata via <pub-history>.

When establishing version history, you must include <event> tagging that references the original published version with <event event-type="published">. The <event event-type="published"> metadata on a new version is important as it will set a version number and published date on the original chapter. The version number within the published event history must be 0.

While all versions of a chapter are unique, they share the same publisher ID. Each versioned chapter must contain a unique DOI and version number. If previous versions of a chapter will not be published on Silverchair’s platform, they should still be represented via version metadata.

Element Required attributes Notes
<event> @event-type Use “published” to reference the original version, “version” for everything else
<event-desc> @specific-use="version-number" This is where the version number is stored. Version number for @event-type='published' must equal 0.
<pub-date> If non-numeric date used or <day>, <month>, or <year> not provided, use @iso-8601-date
<notes> Optional field for front-end description of the version
<book-part-meta>
…
<pub-history>
<event event-type="published">
<event-desc specific-use="version-number">0</event-desc>
<pub-date iso-8601-date="2013-07-13">
<day>13</day>
<month>07</month>
<year>2013</year>
</pub-date>
</event>
<event event-type="version">
<event-desc specific-use="version-number">1</event-desc>
<pub-date iso-8601-date="2013-08-12">
<day>12</day>
<month>08</month>
<year>2013</year>
</pub-date>
</event>
</pub-history>
…
</book-part-meta>


Loading of versioned content requires reloading a chapter with the same @id value. This can be done either by reloading the whole book with the updated chapter and new version metadata, or, by loading multiple versions of the same chapter in the same zipline package with separate book-part-wrapper xml files. Whole book xml files and book-part-wrappers cannot be mixed in a single Zipline package.

To replace a versioned book part chapter, both the publisher ID and the DOI must be present in the replacement package. If a DOI is not included, then the book part version cannot be replaced upon reload to Zipline.

When loading and publishing a new version to Zipline, the previous versions will still be surfaceable through the latest version of the chapter. Please note, however, that only the most recent, published version can be surfaced by a front end search of the web site.

### Permissions

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

• <copyright-statement>: The information that will display on the site should be the complete statement of copyright for the content. It is likely that this will duplicate information in the <copyright-year> and <copyright-holder> elements.
• <copyright-year>: The year of copyright.
• <copyright-holder>:The name of the copyright holder.
<permissions id="per1">
...
</permissions>


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>
...
...
</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 book or chapter. To deposit license information to Crossref, a license URL is required, in either @xlink:href (on <license>) or <ali:license_ref>.

• @license-type attribute: The access type to be stored in the database for the book or chapter. The “free”, “open-access”, and Creative Commons licenses at the book or chapter level will make the content available on the site without authentication. The “crown-copyright” and “us-gov” license types will default to private. If there is no <license> element in the xml file or the @license-type is not specified, the content will default to private. Please note that if a chapter has no <license> element or specific @license-type, that chapter will inherit the @license-type used at the book level.
@license-type="free" Free book/chapter
@license-type="open-access" Open Access book/chapter
@license-type="crown-copyright" CrownCopyright article (defaults to private, but access requirement can be configured with your build team)
@license-type="us-gov" USGov book/chapter (defaults to private, but access requirement can be configured with your build team)
@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)
• @license-type can also be used to indicate that the content should be excluded from on-site purchase. Simply use the attribute @license-type="not-for-sale".
• @xlink:href attribute: A URL to a resource describing the license.
• <license-p>: A paragraph of text within the description of a <license>. If you want the license information to display on the site, it must be included in <license-p>.
• <ali:license_ref>: A reference to a URI that carries the license terms specifying how a work may be used. Note the namespace must be included on the element, or declared in the document header.
• Please note that best practice is to use only one or the other of @xlink:href on <license> or <ali:license_ref>.
<permissions>
…
<license-p>This content is available without a subscription.  It may not be altered in any way and proper attribution is required.</license-p>
</permissions>


OR

<permissions id="per1">
…
<license-p>This content is available without a subscription.  It may not be altered in any way and proper attribution is required.</license-p>
</permissions>


### Linking to other versions of content

The <self-uri> element is intended to link to the same piece of content in different forms. For data supplements or other book-level files 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 in book-meta or book-part-meta, use the <related-object> element (section External links to related content).

#### Link to PDF of content

Import a PDF of the book or book part using <self-uri> in the <book-meta> or <book-part-meta> respectively. For example, <self-uri xlink:href="2011.11010094.pdf"/> where the @xlink:href value is the exact file name as it occurs in the package. Do not prepend the file name with a directory path. The attribute and value @content-type="pdf" may also be indicated on <self-uri>, but it is not required.

To link to book or book part PDFs in different languages, use additional <self-uri> elements, each with an @xml:lang attribute that has as its value the appropriate ISO 639–1 (i.e., two-letter) code. If multiple self-uri elements are used, they all must have @xml:lang attributes with unique ISO 639–1 codes. Ask your build team for the full list of supported languages.

<self-uri xlink:href="book.pdf" xml:lang="en"/>


To import so-called “PDF-only” books, simply include <self-uri> elements for each book part’s PDF file and omit the front matter, body, and back matter from the XML.

#### Link to MOBI or ePub of content

Link a MOBI or ePub file of the book or book part using <self-uri> with @content-type="mobi" or @content-type="epub", respectively. For example <self-uri content-type="epub" xlink:href="2011.11010094.epub"/> where the @xlink:href value is the exact file name as it occurs in the assets folder. Do not prepend the file name with a directory path. Please note that this feature requires a configuration for existing clients.

#### Link to Country-Specific PDF of content

Some publishers have a requirement to provide country-specific versions of PDFs to users. SCM supports the ability to provide country-specific PDFs by using the @content-type and @specific-use attribtues on the <self-uri> element in addition to calling out the PDF. The @content-type should always have the value of “pdf-country-specific”; whereas, the @specific-use attribute will change based on the country’s ISO 3166–1 code. For example, the PDF shown below will surface for users in France:

<self-uri content-type="pdf-country-specific" specific-use="fr" xlink:href="bookpdf_fr.pdf"/>


For multiple country PDFs support, provide a separate <self-uri> for each country. Please note that if you do not provide a PDF per the instructions in Link to PDF of content but a country-specific PDF is provided, then the PDF will only be available to the user in that country.

### Supplementary material

To add supplementary material to the book, use the <supplementary-material> tag in the <book-meta>; to add supplementary material to a chapter, use the <supplementary-material> tag in the <book-part-meta>

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.

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, SCM will use the value of the @id as the publisher-id.

### Book-level asset files

Books may have ancillary material at the book level such as a book cover, front matter, etc. that publishers want available on the site in non-HTML formats. To add book-level assets to the book, use the <supplementary-material> tag in the <book-meta>.

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

The following asset types may be included, using the values listed for @content-type.

book-level file Attribute value
Cover image @content-type="cover"
Front matter @content-type="front"
Back matter @content-type="back"
Editorial Board @content-type="ed-board"
Table of Contents @content-type="toc"
MARC record @content-type="marc"
Affiliate logo @content-type="affiliate-logo"
Google Preview PDF @content-type="preview-pdf"

Any file type listed in the Zipline Packaging Requirements for book-level files is acceptable.

### Abstracts

Abstracts are included in the <abstract> node within the <book-meta> or <book-part-meta> elements. The authored abstract should have no @abstract-type attribute, or it should have the attribute @abstract-type="abstract". The attributes @abstract-type="teaser" and @abstract-type="precis" will also be imported.

### Hierarchical categories

Content can be assigned to categories. Use the <subj-group subj-group-type="category"> and <subject> elements to designate categories for the content. 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>:

• articles
• books
• chapters

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

SCM 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:

• Wireless Sensor Networks
• Alternative Energy Harvesting Systems
<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 SCM for the same site:

• Research (with category type of Book Categories)
• Research (with category type of Article Categories)

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, SCM 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. These categories are used to dynamically order the TOC—meaning articles with the same category-toc-heading value will be grouped on the issue TOC. Please note that a manually ordered TOC provided in an issue file for an issue will override any category-toc-heading provided in the articles (see [Manually ordered TOC]). By default, this configuration is turned off; please consult your Silverchair representative to enable the configuration.

Please note that although @content-type is allowed on the <subject> element, its use is intended for pass-through only and does not drive any functionality on SCM.

### 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 SCM 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.

### Book publication status

To designate a book’s publication status, such as “in progress” ahead of print publication, use a <custom-meta> node with <meta-name>publication-status</meta-name> and a <meta-value> containing one of the statuses listed below.

<custom-meta-group>
<custom-meta>
<meta-name>publication-status</meta-name>
<meta-value>in-progress</meta-value>
</custom-meta>
</custom-meta-group>


The accepted publication statuses are as follows:

Publication Status Required <meta-value>
In Progress in-progress
Available available
Out of Print out-of-print
Out of Print Available Online out-of-print-available-online
Out of Print New Edition in Preparation out-of-print-new-edition-in-preparation
Out of Print Reprint in Preparation out-of-print-reprint-in-preparation
No Longer Distributed by Publisher no-longer-distributed-by-publisher

### Book Industry Communication (BIC) and Book Industry Standards and Communications (BISAC) Product Codes

To designate a BIC or BISAC product code for a book or book chapter, use <subj-group subj-group-type="bic"> or <subj-group subj-group-type="bisac">.

<subj-group subj-group-type="bic">
<subject>JPVK</subject>
</subj-group>


# Front matter

The front-matter section is optional. Front matter is generally shown on the book TOC page on the site, usually with its own link to view the front matter content. Publishers can use the named (predefined) book part elements from BITS in the book and book-part front matter, or use <front-matter-part> for anything not covered by the predefined elements. The @book-part-type attribute on <front-matter-part> can be used to differentiate these front matter parts.

To indicate that a piece of front matter should be suppressed from search, use the attribute @indexed on <front-matter-part> (<front-matter-part id="BDD1-ex" indexed="no">).

The TOC is automatically generated from the order of the chapters and parts as designated in the XML. For a book contained in a single XML file, arrange the parts and chapters in the order you wish them to appear on the TOC, with the correct nesting for chapters inside parts.

If the book is supplied with separate chapter files (ie, using book-part-wrapper), you will need to load a metadata file to order the TOC. The metadata file is a book file with the book-part shells placed for order. This book file should be loaded before any book-part-wrapper files are loaded.

You may submit a pre-structured table of contents using the <toc> element in book parts or at the top level of the book-part-wrapper. The <toc> element is a presentational model and not a metadata model—it is for display only and will not affect the actual order or structure of book parts in the book.

# Back matter

The <book-back> element is optional. Within <book-back>, the @book-part-type attribute on <book-part> can be used to differentiate end matter parts.

To indicate that a piece of end matter should be suppressed from search, use the attribute @indexed on <book-part> (<book-part id="9101" book-part-type="illustration" indexed="no">).

# Book body

A book may include parts and chapters, tagged using the <book-part> element with either the @book-part-type="part" or @book-part-type="chapter" attribute. Other values in @book-part-type are prohibited.

To indicate that a book-part should be suppressed from search, use the attribute @indexed on <book-part> (<book-part id="5678" book-part-type="chapter" indexed="no">).

Include part and chapter numbers/designations in the <label> element under the <title-group>, along with the term you would like used to refer to that part. Chapter “numbers” may be either numeric or non-numeric, e.g. e17 for an electronic-only chapter or 3s indicating a supplemental chapter. For example, the tagging

<book-part id="1234" book-part-type="part">
<book-part-meta>
<title-group>
<label>Part 1</label>
<title>Bees and Honey</title>
</title-group>
</book-part-meta>
</book-part>


will produce the following output on the site (styling shown for illustrative purpose only): Part 1 Bees and Honey

Include part and chapter titles in the <title> element under <title-group>. Include subtitle in the <subtitle> element under <title-group>.

## Parts

Use Parts for any piece of the book hierarchy that does not include text content, i.e. anything above a chapter. Some books use the term “Section” instead of Part.

Book parts are indicated using the <book-part> tag with an attribute of @book-part-type="part". Parts may be nested in other parts, and parts may contain chapters.

<book-part id="1234" book-part-type="part">
<book-part-meta>
<title-group>
<label>Part 1</label>
<title>Bees and Honey</title>
</title-group>
</book-part-meta>
<body>
<book-part id="chapter_1" book-part-type="chapter">
<book-part-meta>
<title-group>
<label>Chapter 1</label>
<title>Honey Production</title>
</title-group>
</book-part-meta>
</book-part>
<book-part id="chapter_2" book-part-type="chapter">
<book-part-meta>
<title-group>
<label>Chapter 2</label>
<title>Honey Collection</title>
</title-group>
</book-part-meta>
</book-part>
</body>
</book-part>


## Chapters

Chapters may contain text content. Chapters can be inside or outside a part. For example, the structure below is acceptable. Chapters may not contain other parts or chapters; the chapter must be a leaf node in the TOC structure of the book.

The chapter element is <book-part book-part-type="chapter">. Required attributes are @book-part-type="chapter", and @id.

<book-part id="1111" book-part-type="chapter">
<book-part-meta>
<title-group><title>Introduction</title></title-group>
</book-part-meta>
</book-part>
<book-part id="1234" book-part-type="part">
<book-part-meta>
<title-group>
<label>Part 1</label>
<title>Bees and Honey</title>
</title-group>
</book-part-meta>
<body>
<book-part id="chapter_1" book-part-type="chapter">
<book-part-meta>
<title-group>
<label>Chapter 1</label>
<title>Honey Production</title>
</title-group>
</book-part-meta>
</book-part>
<book-part id="chapter_2" book-part-type="chapter">
<book-part-meta>
<title-group>
<label>Chapter 2</label>
<title>Honey Collection</title>
</title-group>
</book-part-meta>
</book-part>
</body>
</book-part>


Chapters may optionally include a publication date using the <pub-date> node. This will enable chapters to display a publication date if it is different from the book publication date. Please note that, by default, the chapter page will display the book’s publication date, and you will need to consult with your build team to display a specific chapter publication date on your site.

• Supply a <year> in numerical form, a <month> in non-numerical (e.g. <month>January</month>) or numerical form, and <day> in numerical form.
• Supply a date in ISO 8601 format using an @iso-8601-date attribute and the format YYYY-MM-DD.
• Supply a publication format using the @publication-format attribute with a value of “epub”.

If the date is provided in a form other than numerical month, day, and year, then the @iso-8601-date attribute must be included to supply a numerical publication date. In this case, the year, month, and day provided can be used for display, while the @iso-8601-date value is used as the underlying publication date by the system.

The @publication-format attribute is required, and “epub” is the only value we support here.

# Special features for books

Special characters within headings need to be Unicode entity values. Inline images are supported.

## Related content

### Links to content in SCM

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

• Surfacing translations of the same piece of content.
• Connecting an errata to its original document.
• Explicitly connecting two pieces of content that cover the same topic.
• Connecting an author interview video to the content they authored.

Use the <related-object> element in <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 books and chapters. The XML with the <related-object> tag and the target XML can be imported in any order.

Target document/content type tagging format
Book (using ISBN 13) <related-object document-type="book" document-id-type="isbn13" document-id="1-234-56790-3125"/>
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-3125"/>

To target objects within the document, additionally include the following attributes (please note that Target objects with an asterisk (*) are not supported at the <book-meta> or <book-part-meta> level):

Target object tagging format
Part < … object-type="part" object-id-type="publisher-id" object-id="book1.part1"/>
Chapter < … object-type="chapter" object-id-type="publisher-id" object-id="book1.ch1"/>
Corresponding author information* < … object-type="corresp" object-id-type="publisher-id" object-id="12345.corresp01"/>
Author notes* < … object-type="author-notes" object-id-type="publisher-id" object-id="12345.authornote01"/>
Supplementary data < … object-type="supplementary-data" object-id-type="publisher-id" object-id="12345.supdata01"/>
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"/>
Boxed text* < … object-type="boxed-text" object-id-type="publisher-id" object-id="12345.box01"/>
Display formula* < … object-type="disp-formula" object-id-type="publisher-id" object-id="12345.formula01"/>
Video < … object-type="video" object-id-type="publisher-id" object-id="12345.vid01"/>
Audio < … object-type="audio" object-id-type="publisher-id" object-id="12345.aud01"/>
Page number < … object-type="target" object-id-type="publisher-id" object-id="12345.page01"/>
End note < … object-type="end-note" object-id-type="publisher-id" object-id="12345.endnote01"/>
Appendix* < … object-type="app" object-id-type="publisher-id" object-id="12345.app01"/>
Footnote* < … object-type="fn" object-id-type="publisher-id" object-id="12345.fn01"/>
Object not otherwise covered < … object-type="other" object-id-type="publisher-id" object-id="12345.para01"/>

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

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.”

### External links to related content

You may also link content to related external links at the book (<book-meta>) and chapter level (<book-part-meta>). Your site can use these links to surface related content to the user.

Use the <related-object> element in the <book-meta> or <book-part-meta> to designate a relation to an external link. Use the @document-type, @source-id, @source-id-type, and @source-type attributes to designate the type of content and external link target.

Links to the following source types can be created from books and chapters.

Type of external link tagging format
Companion website <related-object document-type="url" source-id="http://www.companionwebsite.com" source-id-type="url" source-type="companion-website">Companion website</related-object>
Blog article <related-object document-type="url" source-id="http://blog.oxforddictionaries.com/2012/11/vsi-english-literature-text-analyser/" source-id-type="url" source-type="blog-article">Text analyser</related-object>
Video <related-object document-type="url" source-id="http://www.youtube.com/watch?v=e1Hk9yNS5ZE" source-id-type="url" source-type="video">Jonathan Bate - English Literature: A Very Short Introduction</related-object>
External resource <related-object document-type="url" source-id="http://www.externalsource.com" source-id-type="url" source-type="external-resource">External resource</related-object>
Quiz <related-object document-type="url" source-id="http://www.websitename.com/pagename" source-id-type="url" source-type="quiz">Quiz</related-object>

## Author assigned keywords

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

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


## Restricted images based on electronic rights

To designate a figure image as restricted due to lack of electronic rights, include the <permissions> element as a child of <fig>, with a <license license-type="NoElectronicRight"> element inside the <permissions>. This type of restricted image will not be displayed and should not be supplied. Instead, the user will see a notice that indicates that the image has been omitted due to lack of electronic rights.

## Q&A content

SCM allows the ability to designate when content is Q&A content. You can designate that a piece of content is an answer or question using the following values in @specific-use on the <sec> containing the Q&A content:

Value of
@specific-use Definition
question-set a set of multiple questions
question a single question

Speak to your build team if you need specific functionality associated with these designations.

## Cross-references

Cross-reference links to items within the same chapter or other type of book part are indicated with the <xref> element. The @ref-type attribute indicates the element type of the cross-reference target and the @rid provides its id value.

Please note that content outside of the chapter or other type of book part must be cross-referenced using the <related-object> element. See Related content for guidance in structuring those links.

SCM 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 formula
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, 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>.


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 references 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 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 …


## Print sales

SCM supports print sales for books using the ProductBuilder tool. The book must exist in our database to enable selection as a print product and to provide book-level information for display on the site if a product page is desired. This means that print-only books will still need to be loaded via Zipline in SCBITS xml. In this case, please provide only book-level information in the <book-meta> element. Note that any book (online and print-only) can be designated for sale.

# 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 desired 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>
</fig>


## 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 SCM. 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> 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. Confirm desired functionality with your build team.

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 figures tab.

#### Text wrap for anchored images

There is an optional extension for journal articles that enables text to wrap around images tagged with the <graphic> element and the attribute @position="anchor". For example, this could be used when there is an image of a person with a paragraph about that person that should appear alongside the photograph, as opposed to above or below the photograph. The paragraph that it should appear alongside should follow the <graphic> element. Including a caption is optional:

<graphic id="personimage1" position="anchor" xlink:href="personimage1.jpeg">
<caption><p>Name of person.</p></caption>
</graphic>


To use this feature, you must consult your build team.

### 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 within a <p> 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 SCM.

## 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:

• <boxed-text content-type="sidebar-small">
• <boxed-text content-type="sidebar-medium">
• <boxed-text content-type="sidebar-large">

Please note that, although three different sizes are allowed, they will all display at the same size by default, and the need to change the size of the display is a customization.

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. Please note that Silverchair does not directly host multimedia. Thus, publishers are expected to upload their multimedia files to a 3rd party host, preferably one of those described in the sections below. If your multimedia is currently hosted by a provider that is not listed below, please consult with your development team.

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>
<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">
</media>
</fig>


### Glencoe

For Glencoe-hosted media, use @content-type="glencoe" on the <media> element. Put the full URI to the video in @xlink:href on <media content-type="glencoe">.

<fig id="video1" fig-type="video">
<object-id pub-id-type="doi">10.9999/SSC_20120928_v107i3_043_video2</object-id>
<label>Video 2</label>
<caption><title>Fluoroscopy II</title><p>Second video of fluoroscopy.</p></caption>
</fig>


### Video with media file to be archived at Silverchair

If the media file is in the package and is to be archived for downstream deposits at Silverchair, use the <alternatives> tag with children media elements. Under <alternatives>, provide <media content-type="media-archive"> and put the video file name in @xlink:href. If <media content-type="media-archive"> is provided, it must have a sibling element media element, with the media host provider specified in @content-type, for example, <media content-type="glencoe">. The physical media file will not be hosted, and is included only for downstream full text deposits.

<fig id="video1" fig-type="video">
<object-id pub-id-type="doi">10.9999/SSC_20120928_v107i3_043_video3</object-id>
<label>Video 3</label>
<caption><title>Fluoroscopy III</title><p>Third video of fluoroscopy.</p></caption>
<alternatives>
</alternatives>
</fig>


### AWS (JWPlayer)

AWS-hosted media is played through JWPlayer. You will need to consult your build team to have the video display on your site. For AWS-hosted media, use @content-type="jwplayer" on the <media> element.

Put the full URI to the video in @xlink:href on <media content-type="jwplayer">:

 <fig id="video1" fig-type="video">
<object-id pub-id-type="doi">10.9999/SSC_20120928_v107i3_043_video3</object-id>
<label>Video 3</label>
<caption><title>Fluoroscopy III</title><p>Third video of fluoroscopy.</p></caption>
</fig>


For YouTube-hosted media, use @content-type="youtube" on the <media> element. Put the full URI to the video in @xlink:href on <media content-type="youtube">. You will need to consult your build team to have the video display on your site.

<fig id="video6" fig-type="video">
<label>Video 6.</label>
</fig>


### SoundCloud

For SoundCloud-hosted media, use @content-type="soundcloud" on the <media> element. Specify @fig-type="audio", per normal rules for audio in <fig>. Put the embed URI to the audio in @xlink:href on <media content-type="soundcloud">. You will need to consult your build team to have the media display on your site.

<fig id="audio6" fig-type="audio">
<label>Audio 6.</label>
</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. 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 Silverchair XSDs. SCJATS and SCBITS currently support MathML 2 in XSD format.

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. We support LaTeX and TeX via MathJax. The Silverchair Platform does not support custom markup.

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, except where required by the XSD. 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.

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

Silverchair supports links to external databases. For example, use an <ext-link> to link to PDB with @ext-link-type="pdb" and an @xlink:href with the value of the ID of the data (e.g., @xlink:href="6N2I"). In the <ext-link>, provide the value that you want linked:

<ext-link ext-link-type="pdb" xlink:href="6N2I">6N2I</ext-link>


A complete listing of the supported values follows:

PDB pdb
GenBank - Gene gene
GenBank - Nucleotide ntide
PomBase pombase
OMIM omim
FlyBase flybase
WormBase wormbase
miRbase mirbase
Rfam rfam
Pfam pfam
PROSITE prosite
Swiss-Prot sprot
Swiss-Model smodel
ClinicalTrials.gov clintri
DDBJ/EMBL/GenBank gen
NCBI:refseq refseq
NCBI:geo geo
NCBI:protein protein
NCBI:pubchem-substance substance
NCBI:pubchem-bioassay bioassay
NCBI:pubchem-compound compound
NCBI:sra sra
NCBI:structure structure
NCBI:taxonomy taxonomy
EBI:arrayexpress arrayexpress
emblalign emblalign

## 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 SCM 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:

• <source>
• <article-title>
• <volume>
• <issue>
• <fpage>
• <surname>
• <year>
• <month>
• <day>

SCM can create links to PubMed and Crossref for journal articles or conference proceedings referenced in the references section. For SCM to determine and create these links, specific @publication-type values must be included in the <element-citation> or <mixed-citation> element. The values that are supported are @publication-type="journal" for journal articles and @publication-type="confproc" for conference proceedings.

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. The version number of the dataset should appear in <version>, with a machine-readable number in the @designator attribute.

 <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>. <version designator="16.2">16th version, second release</version>.</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 <fn-group> or general <author-notes> will display as a separate footnotes section at the end of the article. Footnotes in any other section will display where they appear.

## Whitespace between elements

The current functionality of Zipline removes spaces in between xml elements when the only data between those elements is whitespace. For example, in the xml <p><xref ref-type="bibr" rid="bib82">Soroor et al., 2019</xref> <italic>Preprint</italic></p>, the space between the closing tag </xref> and the opening <italic> tag will be stripped by the content processor. To preserve this space, we recommend that clients either use non-breaking space (&#160;), or place the whitespace within the previous element’s closing tag. The functional solutions are as follows:

• <p><xref ref-type="bibr" rid="bib82">Soroor et al., 2019</xref>&#160;<italic>Preprint</italic></p>
• <p><xref ref-type="bibr" rid="bib82">Soroor et al., 2019 </xref><italic>Preprint</italic></p>

This solution should be applied in all situations where the display of the XML requires the preservation of whitespace-only data between elements.

## Display Attributes

Although not supported on the front-end, SCM does allow you to upload content containing certain display attributes for use in print or other non-SCM purposes. Note that not all of these values are retained in the output XML that is downstreamed for deposits or other services.

attribute value Meaning
align Sets the horizontal alignment inside a table cell.
border Thickness, in pixels, of the border to draw around a table.
cell-padding Amount of space, measured in pixels, between the borders of a cell and the contents of a table cell.
cell-spacing Width of space between cells in a table.
disp-level Indicates the level at which to display a section when the display level and hierarchical level are different.
frame Specifies which sides of a table should be given rules.
orientation Indicates whether an object should be positioned in a tall manner (“portrait”) or in a wide manner (“landscape”).
position Typically indicates whether a display object must be anchored in its exact location or may float to a different location in the document.
rules Defines which rules to draw between rows and columns of an XHTML 1.1 table.
style Names the style or rendering to be applied to the element.
valign Sets the vertical alignment inside a table cell.
width Used within a NISO JATS table to specify width.

# Deprecated Features

The following features have been deprecated from SCBITS, but have been preserved in the specification to allow for backwards compatibility. These features will trigger a warning when content is loaded into Zipline, and we recommended updating the source content. These features may not be allowed in future releases of the Silverchair Specifications.

## appendix element as child of biography element

The use of the <app> tag within <bio> is not valid to BITS 2.0 or JATS 1.2, and it should not be used. Appendices should be moved to an <app> or <app-group> in <back>. Proper use is as follows.

<back>
<app-group id="appgroup-1">
<app id="app1">
<label>Appendix 1</label>
<title>Appendectomy</title>
<sec id="app1_sec1_1">
<title>Appendix Section title</title>
<p>An appendectomy is the surgical removal of the appendix. </p>
</sec>
</app>
</app-group>
</back>


## app-group element as child of book-back element

The use of the <app-group> tag within <book-back> is not valid to BITS 2.0, and it should not be used. Appendices should be moved to a <book-app-group> or <book-app> in <book-back>. Proper use is as follows.

<book-back>
<book-app-group id="bag1">
<book-part-meta>
<title-group>
<title>Appendices Group</title>
</title-group>
</book-part-meta>
<book-app id="ba1">
<book-part-meta>
<title-group>
<title>Appendix 1</title>
</title-group>
</book-part-meta>
<body>
<sec id="ba1s1">
<title>Scientific Name</title>
<p>Every node in the database is required to have ...</p>
</sec>
</body>
</book-app>
</book-app-group>
</book-back>


## @fn-type value of “COI-statement”

The value of @fn-type="COI-statement" to support Conflict of Interest statements has been deprecated and should not be used. Instead, please use @fn-type="coi-statement" or @fn-type="conflict".

## <meta-name> value of “in-progress” and <meta-value> value of “in progress”

Designating a book as “in progress” ahead of print publication, using a node with in-progress and in progress has been deprecated. Instead, please use publication-status and in-progress. See section Book publication status.