TF JATS File Naming Convention
This file describes the file naming convention, id naming convention, and image file guidelines for TF JATS. This naming convention is based on the TFJA and CATS file naming conventions, and is aimed at simplifying delivery requirements while enabling delivery of "complete" files (rather than "online" files) to support figure tracking in CATS and re-purposing content. Specific delivery requirements will be defined using subsets of this convention.
Conventions used in this document
Several data elements commonly used in the file naming convention are indicated in this document as shown below. Patterns are described using a syntax similar to Regular Expressions.
| Element | Token | Example | Pattern |
|---|---|---|---|
| Journal Acronym | {journal} | BATC | [A-Z0-9]+ |
| Article ID / Manuscript ID | {articleid} | 123456 | [0-9]+ |
| Volume Number | {volume} | 2 | [0-9a-zA-Z]+(-[0-9a-zA-Z]+)? |
| Issue Number | {issue} |
3 |
[0-9a-zA-Z]+(-[0-9a-zA-Z]+)? |
| Formatted Issue Number | {f-issue} |
03 |
[0-9a-zA-Z]{2,}(-[0-9a-zA-Z]{2,})? |
| File Format Extension | {ext} | [a-z0-9]+ | |
| Print or Online formatted | {po} | P | [PO] |
| Description segment | {description} | any text | [a-zA-Z0-9\x2D]+ |
The naming convention uses data elements and identifier tokens separated by the underscore (_) character, followed by a standard file name extension. Usually, the first segment identifies the journal, the second segment identifies the file as related to an issue (I) or an article (A), followed by segments that identify the issue or article, followed by segments that identify the contents of the file. Standard file extensions (.xml, .zip, .pdf, and so forth) are used to identify the file format.
The second segment is also used to identify item types other than issues and articles. Codes used to identify item types in the CATS file naming convention are as follows:
| Code | Description | Example | Pattern |
|---|---|---|---|
| I | Issue | BATC_I_2_3_J.zip | See below... |
| A | Article | BATC_A_123456_J.zip | See below... |
| GN | General Content | BATC_GN_12345.pdf |
{journal}_GN_{gnid}(_{description})? |
Zip File Requirements
All files for an issue or an article should be packaged in .zip format for delivery. Issue and article .zip files should be structured the same as the issue and article folders described below.
The .zip file should be structured with content files placed at the top level. There should not be a single top-level folder within the .zip.
Issue Level Files
The issue folder, or issue .zip, collects all issue-level files and article folders. An issue folder, or issue.zip, should contain at minimum an Issue XML file and one or more article folders. The issue folder and issue level files should be named as follows:
| File/Folder type | Example | Pattern |
|---|---|---|
| Issue Folder | BATC_I_2_3 | {journal}_I_{volume}_{issue} |
| Issue .zip | BATC_I_2_3_J.zip | {journal}_I_{volume}_{issue}_J.zip |
| General Content files | BATC_GN_12345.pdf | See above... |
| Table of Contents PDF | BATC_I_2_3_TOC.pdf | {journal}_I_{volume}_{issue}_TOC.pdf |
| Covers PDF | BATC_I_2_3_COVER.pdf | {journal}_I_{volume}_{issue}_COVER.pdf |
| Cover Images | BATC_I_2_3_COVER_110.jpg |
{journal}_I_{volume}_{issue}_COVER_{width}.{ext} |
| Miscellaneous Scanned Pages PDF | BATC_I_2_3_MISC.pdf | {journal}_I_{volume}_{issue}_MISC.pdf |
| Composite Inside Pages PDF | BATC_I_2_3_TEXT.pdf | {journal}_I_{volume}_{issue}_TEXT.pdf |
| Issue XML | BATC_I_2_3_J.xml | {journal}_I_{volume}_{issue}_J.xml |
| CATS Data File | cats.xml | cats.xml |
| Article Folders | BATC_A_123456 | See below... |
Issue numbers may be zero padded to two digits. For example, issue 3 with zero padding is 03, and issue 4-6 with zero padding is 04-06. Ranges in issue numbers or volume numbers should use a hyphen (-) to represent the range.
For current issues: Table of Contents pages, Covers, and other non-article pages are logged in CATS as General Content, and these files should be named using the "General Content files" naming convention. The description segment should contain "TOC" for general content files containing tables of contents, and the description segment may contain "C1", "C2", "C3", "C4", "OFC", "IFC", "IBC" or "OBC" for covers. For other non-article pages, the description segment may be assigned a descriptive label. A Table of Contents PDF may be present and may possibly be in addition to any General Content files that contain the table of contents for an issue.
For retrodigitized issues: Table of Contents pages should be named using the "Table of Contents PDF" convention, scanned covers should be named using the "Covers PDF" convention, and other non-article pages should be named using the "Miscellaneous Scanned Pages PDF" convention.
In print final files delivered to CATS, the "Covers PDF" naming convention above may also be used to name composite cover files, and the "Composite Inside Pages PDF" convention may be used to name the composite inside pages PDF, if these files are required. Print-quality composite covers and composite inside pages files are not normally included in TF JATS files.
Article Level Files
An article folder, or an article .zip, should contain all files relevant to an article, and should have, at minimum, and Article XML file. Article level files and folders should be named as follows:
| File/Folder type | Example | Pattern |
|---|---|---|
| Article Folder | BATC_A_123456 | {journal}_A_{articleid} |
| Article .zip | BATC_A_123456_J.zip | {journal}_A_{articleid}_J.zip |
| Article XML | BATC_A_123456_J.xml | {journal}_A_{articleid}_J.xml |
| Article PDF | BATC_A_123456_O.pdf | {journal}_A_{articleid}_{po}.pdf |
| Tagged Manuscript File | BATC_A_123456_T.docx |
{journal}_A_{articleid}_T.{ext} |
| CATS Data File | cats.xml | cats.xml |
| Images folder | graphic | graphic |
| Image File | BATC_A_123456_F0001_B.gif | {journal}_A_{articleid}_{xmlid}(_{po}?{cb})?.{ext} |
| Supplementary Files folder | suppl | suppl |
| Supplementary File | BATC_A_123456_SM0001.zip | {journal}_A_{articleid}_{xmlid}(_{description})?.{ext} |
| Media Files Folder | media | media |
| Media File | BATC_A_123456_MED0001.mov | {journal}_A_{articleid}_{xmlid}(_{description})?.{ext} |
Article PDF
The article PDF should be referenced using the <self-uri> element within the <article-meta> section. The content-type attribute should specify "pdf", and the xlink:href attribute should specify the file name of the PDF. For example:
<self-uri content-type="pdf" xlink:href="BATC_A_1000001_O.pdf"/>If both print and online versions of the article PDF are included, both should be referenced from the XML and the specific-use attribute should be set to distinguish each PDF. For example:
<self-uri content-type="pdf" specific-use="web-only" xlink:href="BATC_A_1000001_O.pdf"/>
<self-uri content-type="pdf" specific-use="print-only" xlink:href="BATC_A_1000001_P.pdf"/>A PDF file is normally required for every article. In cases where a PDF file is not present the full-text-limited attribute on the <article-status> element should specify that the PDF file is not present (otherwise, a validation error may result). The value should be set to "no-pdf", "rights", or "retracted", when no PDF is present. For example:
<article-status stage="final" full-text-limited="no-pdf"/>In archive projects, when a scanned PDF file is found to contain errors (such as missing pages, or a low quality scan), the full-text-limited attribute should be set to "incomplete" or "bad-scan".
Image Files
Image files used in an article should be placed in a folder named "graphic" within the article folder and named using the Image File convention in the above table. All image files should be referenced from within the article XML file.
Image files should be saved at the same resolution as used to create the PDF for print. When different versions of an image are needed, for example for an figure that appears in color online and in black and white in print, all versions of the file should be included and identified using the naming convention and attributes on the graphic or inline-graphic element.
For image files the tokens are as follows:
| Code | Description | Example | Pattern |
|---|---|---|---|
| {xmlid} | Should match the id attribute of the object in the article XML. See list of ID prefixes below. | F0001 | [A-Za-z]+[0-9]{4}[A-Za-z]* |
| {cb} | Color or Black and White (grey scale). Should match the graphic content-type attribute in the XML as "color" or "black-white" | C | [CB] |
| {po} | Print or Online. Should match the graphic specific-use attribute in the XML as "print-only" or "web-only" | O | [PO] |
All image files included with an article should be referenced within the article XML. When a particular item is represented in multiple forms the <alternatives> element should be used to enclose the tags for all forms of the item (for example, a figure supplied as black and white and as color, or a math equation supplied as .gif image, TeX and MathML).
For example, a standard black and white figure:
<fig id="f0001"><label>Figure 1</label>
<graphic xlink:href="BATC_A_123456_F0001_B.jpg" content-type="black-white"/>
</fig>For example, a figure that appears in color online and in black and white (or grey scale) in print:
<fig if="f0002"><label>Figure 2</label>
<alternatives>
<graphic xlink:href="BATC_A_123456_F0002_PB.jpg" specific-use="print-only" content-type="black-white"/>
<graphic xlink:href="BATC_A_123456_F0002_OC.jpg" specific-use="web-only" content-type="color"/>
</alternatives>
</fig>Inline images that have only one version do not need to include content-type or specific-use descriptors. For example:
<inline-graphic xlink:href="BATC_A_123456_ILG0001.gif"/>Supplementary Material Files
When an article includes supplementary online-only files, these files should be placed in "suppl" folder within the article folder and named using the Supplementary File convention in the above table using "SM" at the start of the {xmlid} segment. This example is for journal BATC article ID 1000001.
|
|
Supplementary files should be referenced from within the article XML using the <supplementary-material> element with the file name placed in the xlink:href attribute. For example:
<supplementary-material id="sm0001" content-type="dataset"
mimetype="application" xlink:href="BATC_A_1000001_SM0001.zip">
<caption><title>Survey Data</title></caption>
</supplementary-material>The XML should contain a <supplementary-material> tag for each supplementary file, but it is not required for this tag to be present for each supplementary file. It is also allowable for <supplementary-material> tags to be added to the article XML before the supplementary files themselves are added to the article files.
Media Files
When an article includes media files, these files should be placed in "media" folder within the article folder and named using the Media File convention in the above table using "MED" at the start of the {xmlid} segment. This example is for journal BATC article ID 1000001.
|
|
Media files should be referenced from within the article XML using the <media> element with the file name placed in the xlink:href attribute. For example:
<media id="MED0001" mimetype="video" mime-subtype="x-msvideo"
xlink:show="new" xlink:href="BATC_A_1000001_MED0001.mov"/>A media file may have an associated image file that should be used when the media file cannot be displayed. The associated image file should have the same base file name as the media file and have a different file extension, and be placed in the "graphic" folder and referenced in the XML using the <graphic> element. For example:
|
|
XML ID Conventions
The id attribute that appears on several XML elements is restricted by the schema to an NMTOKEN ([a-zA-Z0-9]+). The following conventions should be used in assigning values to id attributes based on the element the id identifies, and id attribute values should match the pattern for {xmlid} described above. Numbers should be zero-padded to four digits, and suffix letters (for example F0001A for "Figure 1a") should be included after the number. The identifier should match the item type and number (or label) of the item in the document. Other formats, such as id values assigned by the generate-id() XPath function, are allowed but the preference is to use this convention.
| Component | id Prefix | Example |
|---|---|---|
| Figure* | f |
|
| Unnumbered Figure | uf |
|
| Inline Graphic | ilg |
|
| Math | m |
|
| Unnumbered Math | um |
|
| Inline Math | ilm |
|
| Chemistry | c |
|
| Unnumbered Chemistry | uc |
|
| Table* | t |
|
| Unnumbered Table | ut |
|
| Affiliation | aff |
|
| Biography | b |
|
| Boxed Text (sidebar) | bt |
|
| Footnote | fn |
|
| Table Footnote | tfn |
|
| Endnote | en |
|
| Citation | cit |
|
| Section | s |
|
| List | l |
|
| Appendix | app |
|
| Author Note | an |
|
| Supplementary Material* | sm |
|
| Media* | med |
|
| Query* | q |
|
|
*Additional validation may be applied to these id's by CATS data. |
||
Note that the file name convention normally uses all upper-case characters
except for the file extension, and the XML id attribute convention normally
uses all lower-case characters (though it is not a requirement to use all
lower-case characters in XML id attributes), so if id attribute values are
used for comparison the comparison should be case-insensitive. File names
placed in the xlink:href attribute should match the actual file name exactly
using case-sensitivity. For example: <inline-graphic id="ilg0001"
xlink:href="BATC_A_123456_ILG0001.gif"/>.
Example: Retrodigitized Issue
Example file names and .zip file structure for a retrodigitized issue. This example is for journal BATC, volume 2, issue 3.
|
|
Example: Current Issue
Example file names and .zip file structure for a current issue in production. This example is for journal BATC, volume 2, issue 3.
|
|
Example: Current Article
Example file names and .zip file structure for a current article in production. This example is for journal BATC article ID 1000001.
|
|