Modifying JATS for Local Use

This section contains implementor’s instructions for customizing JATS, or making derivative tag sets based on it. It uses the Archiving Tag Set as an example, but these instructions apply equally to Publishing, Authoring, and to BITS.
First Steps: Using This Tag Library
If you want to learn about the Archiving Tag Set in order to write a new tag set based on this Tag Set or to modify the current Tag Set:
  • Skim the first two chapters of this Tag Library, the Navigation and the Structure of the Tag Library.
  • Read the parameter entities that name the classes (in the module %default-classes.ent;).
  • If you do not know the symbols used in the Hierarchy Diagrams, then read the “Key to the Near & Far® Diagrams”.
  • Use the Hierarchy Diagrams to give you a good sense of the top-level elements and their contents.
  • Pick an element from one of the diagrams. (Look up the element in the Elements Section to find the full name of the element, the definition, usage notes, content allowed, and attributes list. Look up one of the attributes to find its full name, usage notes, and potential values.)
  • Read the Tag Set Modules. New Tag Sets are created by writing, at a minimum, a new DTD module and new customization modules, so you might want to read the modules in this order:
    • The DTD module (JATS-archivearticle1-4d1.dtd);
    • The module that names all the Archiving-Tag-Set-specific customization and element modules (%archivecustom-modules.ent;);
    • The module that names all the other modules in the Suite (%modules.ent;);
    • The Archiving customization modules (%archivecustom-classes.ent; %archivecustom-mixes.ent; and %archivecustom-models.ent;).
      You might also wish to familiarize yourself with the relationship between the “customization” modules and the “default” modules for classes, mixes, and models, so you might read the Suite class and mix modules next (%default-classes.ent; and %default-mixes.ent;);
    • Any one of the many class-defining modules from the Suite (for example, the %list.ent; module).
Modular DTD Design
This Suite has been written as a series of XML DTD modules that can be combined into a number of different tag sets. The modules are separate physical files that, taken together, define all element structures (such as tables, math, chemistry, paragraphs, sections, figures, footnotes, and reference elements), as well as attributes and entities in the Suite.
Modules in the Suite are primarily intended to group elements for maintenance. There are different kinds of modules. A module may:
  • Be a building block for a base Tag Set (such as the module Module to Name the Modules).
  • Define the elements inside a particular structure. For example, the Bibliography References (Citation) Elements Module names all the potential components of bibliographic reference lists.
  • Name the members of a “class” of elements, where class is a named grouping of elements that share a similar usage or potential location. For example, the Phrase-Level Content Elements Module defines small floating elements that may occur within text, such as inside a paragraph or a title, or that describe textual content, for example, a disease name, drug name, or the name of a discipline.
  • Be a module of “editorial convenience”. For example, the module Common (Shared) Element Declarations Module holds elements and attributes used in the content models of the various class elements.
The major disadvantage of a modular system is the longer learning curve, since it may not be immediately obvious where within the system to find a particular element or attribute cluster. To help with this, each element page includes an expanded content model.
There are many advantages to such a modular approach. The smaller units are written once, maintained in one place, and used in many different tag sets. This makes it much easier to keep lower level structures consistent across document types, while allowing for any real differences that analysis identifies. A tag set for a new function (such as an authoring tag set) or a new publication type can be built quickly, since most of the necessary components will already be defined in the Suite. Editorial and production personnel can bring the experience gained on one tagging project directly to the next with very little loss or retraining. Customized software (including authoring, typesetting, and electronic display tools) can be written once, shared among projects, and modified only for real distinctions.
JATS and Linked Data
The primary purpose of JATS is to support journal article markup for production, interchange, and archiving of the complete text of articles, with the associated metadata necessary to support those activities. Therefore, JATS is not defined in an RDF-enabled way. In addition, JATS is a descriptive rather than a prescriptive standard, so it does not mandate a way to make ontological or linked-data connections. Nevertheless, JATS provides several tagging constructs that are useful in making a JATS document as RDF-friendly as is practical in an application specifically designed for full text document production:
  • Every element in JATS has either an optional or a required attribute of type ID. These attributes were added to enable document creators to provide URIs at any level they choose in the document. These IDs can be used to make the document, or a portion of the document at any level of specificity, directly addressable.
  • Every element in JATS can take an @xml:base attribute. This attribute provides a base URI for identifiers within the XML document. While this mechanism provides an inward-facing linkability rather than a pointer to an external ontology, @xml:base can be used to support link-bases into the XML and external semantic interpretations layered over the XML.
  • There is also an easy mechanism to add RDF-a attributes (or any other attributes) to every JATS element. The JATS DTDs provide two parameter entities (%jats-common-atts; and %jats-common-atts-id-required;) that can be used to add any attributes a user may prefer to all of the elements in the Tag Suite (except those out of our control, such as MathML elements). These are the two parameter entities that give each JATS element an ID and an @xml:base. Among current JATS users, these parameter entities have been used to add RDF-a attributes to each element in a JATS document collections.
How To Make New Tag Sets
Parameter Entities Modules to Customize and Change
Parameter entities are the major mechanism for customizing JATS or creating a new tag set from the modules in the Suite. Individual tag sets will be constructed by (1) establishing element and attribute combinations and content models using parameter entities in one of the Tag-Set-specific customizing modules and (2) choosing appropriate modules from the Suite that declare the elements needed. For example, if a base tag set contained 6 kinds of lists and 2 table models, a more specific tag set, such as an authoring tag set, might use a Customize Classes Module to redefine the List Class to name only 3 lists and redefine the Display Class to allow only one table model.
The standard modules to create a customized tag set are: the DTD itself, a module to name its components, and as many override modules and new elements modules as necessary. Typical modules for a new tag set are:
  • DTD — The DTD module (.dtd) for the new tag set base DTD (At a minimum, this module declares the top-level element (such as article, book, or report) and any other structural elements unique to the new document type.);
  • Tag-Set-specific Module of Modules — Module to name all the new modules created expressly for the new Tag Set;
  • Class overrides — Tag-Set-specific overrides of the Suite default element classes;
  • Mix overrides — Tag-Set-specific overrides of the Suite default class mixes;
  • Model overrides — Tag-Set-specific content model overrides for the content models in the modules of the Suite (using “-elements” and “-model” parameter entities); and
  • New Models — Tag-Set-specific new elements. (For example, a new Book Tag Set might add book-specific metadata elements.)
Element Classes Concept
Many of the elements in JATS have been grouped into loose element classes. There is no hard and fast rule for what constitutes a class; each one is a design decision, a matter of judgment. These classes are designed to ease customization to meet the particular needs of new tag sets. Base classes for the JATS DTD Suite are defined in a separate Default Element Classes Module (%default-classes.ent;).
Content models are built using sequences of elements and OR groups (which are typically classes and sometimes mixes). As an example, the content model for a <p> element is declared to be an OR group (that is, a choice) of data characters and any of the elements named in the Paragraph Elements mix. The mix %p-elements; is declared to be a large OR group of many other element-defining classes: the Phrase Class Elements, the Mathematical Expressions Class Elements, the List Class Elements, the Citation Class Elements, etc.
Implementor’s Note: These element classes can be viewed as building blocks that will be used to build larger parameter entities for element mixes. A mix describes a usage circumstance for a group of elements, such as all the paragraph-level elements, all the elements allowed inside a table cell, all the elements inside a paragraph, or all the inline elements. For example, to add another block display item to the Block Display Class Elements, you would edit the %block-display.class; parameter entity in your Tag-Set-specific Class Override Module to override the default parameter entity defined in the Suite’s Default Element Classes Module and create a new module containing the Element Declaration of the new block display item.
Parameter Entity Names for Classes and Mixes
PARAMETER ENTITY: SAME FUNCTION, SAME NAME — The Suite modules and initial Tag Sets have used a series of parameter entity naming conventions consistently. While parsing software cannot enforce these parameter entity naming or usage conventions, these conventions can make it much easier for a person to know how the content models work and what must be modified to make a Tag Set change.
CLASSES — Classes are functional groupings of elements used together in an OR group. Each class is named with a parameter entity, and all class parameter entity names end in the suffix “.class”:
 <!ENTITY % list.class "def-list | list">
A class, by definition, should never be made empty; the class should be removed from all models where you do not want the class elements included.
MIXES — Mixes are functional OR groups of classes; mixes should never contain element names directly. All mixes must be declared after all classes, since mixes are composed of classes. Mix names have no set suffix; for example, they may end in “-mix” or “-elements”. Content models and content model overrides use mixes and classes for all OR groups. Only content model sequences are made up of element names directly.
MODEL OVERRIDES — Parameter entity mixes for overriding a content model are of two styles: (1) inline mixes and (2) full content model replacements. These two groupings have been defined and named separately to preserve the mixed-content or element-content nature of the models in Tag Sets derived from the Suite.
The inline parameter entities to be intermingled with character data (#PCDATA) in a mixed content model are named with a suffix “-elements”. For example, “%institution-elements;” would be used in the content model for the element <institution>:
      <!ENTITY % institution-elements "| %subsup.class;" >
      <!ELEMENT  institution (#PCDATA %institution-elements;)* >
    
All inline mixes begin with an OR bar, so that the mix can be removed leaving just character data (#PCDATA):
      <!ENTITY % rendition-plus "| %emphasis.class;  | %subsup.class;" >
    
The override of a complete content model will be named with a suffix “-model” and should include the entire content model, including the enclosing parentheses:
      <!ENTITY % kwd-group-model "(title?, (%kwd.class;)+ )" >
      <!ELEMENT  kwd-group %kwd-group-model; >
    
How To Build a New Custom Tag Set
The Concept
The basic idea for a new Tag Set is that all lower-level elements (paragraphs, lists, figures, etc.) will be defined in modules — either the modules of the base Suite or in new Tag-Set-specific modules — rather than in the DTD itself. The new DTD will be fairly short and include only definitions of the topmost elements, at least the document element and maybe its children.
Modules are declared using external parameter entities in the Suite’s Module to Name the Modules or in the Tag-Set-specific Module of Modules. Modules are referenced in the DTD proper, in the order needed to define the parameter entities in sequence.
The Journal Publishing Tag Set was written as an example of the new best-practice customization technique, so its files names are used in the example below. A new variant tag set that follows this plan will probably consist of the following modules:
  • A DTD module to define the top-level elements (for example, JATS-journalpublishing1-4d1.dtd);
  • A Tag-Set-specific Module of Modules to name new non-Suite modules in this Tag Set (for example, %journalpubcustom-modules.ent;);
  • A Tag-Set-specific definition of element classes to add new classes and override the default classes (for example, %journalpubcustom-classes.ent;);
  • A Tag-Set-specific definition of element mixes to add new mixes and override the default mixes (for example, %journalpubcustom-mixes.ent;);
  • A Tag-Set-specific module of content model overrides (for example, %journalpubcustom-models.ent;);
  • Tag-Set-specific modules to hold new element declarations; and
  • All or most of the modules in the full Suite.
Making a Variant Tag Set
To show the process, here is a series of instructions for making a new tag set, illustrated by showing how the Journal Publishing Tag Set was created from the modules of the whole Suite.
  1. Modules — Write a new Tag-Set-specific Module of Modules, which defines all new customization modules the tag set needs. As an example, the Journal Publishing Tag Set created the module %journalpubcustom-modules.ent;, which contains the definitions of the class-override module %journalpubcustom-classes.ent;, the mix-override module %journalpubcustom-mixes.ent;, and the models-override module %journalpubcustom-models.ent;.
  2. Class overrides — Write a Tag-Set-specific class-override module, defining any overrides to the Suite classes. These classes are defined in the default classes module, %default-classes.ent;. As an example, the Journal Publishing Tag Set created the module %journalpubcustom-classes.ent;, in which %emphasis.class; and %rest-of-para.class; were redefined.
  3. Mix overrides — Write a Tag-Set-specific mix-override module, defining any overrides to the Suite mixes. These mixes are defined in the default mixes module, %default-mixes.ent;. As an example, the Journal Publishing Tag Set created the module %journalpubcustom-mixes.ent;, in which mix overrides such as %emphasized-text; and %sec-back-matter-mix; were declared.
  4. Model overrides — Create a Tag-Set-specific content-model-override module, defining any overrides to the content models and attribute lists for the Suite. As an example, the Journal Publishing Tag Set created the module %journalpubcustom-models.ent;, in which element collections (suffixed “-elements”) that will be mixed with #PCDATA were redefined, full content models overrides (suffixed “-model”) were redefined, and some new attributes and attribute lists were added.
  5. New Elements — Write any new element modules needed. These will define any new block-level or phrase-level elements. For the Journal Publishing Tag Set, there are no such modules, but, for example, the Book Tag Set made from this Archiving Tag Set defines book-specific metadata.
  6. DTD Module — With those modules in place, construct a new DTD module. Within that module:
    • Use an external parameter entity Declaration to name and then call the Tag-Set-specific module of modules, for the Journal Publishing Tag Set, the module %journalpubcustom-modules.ent;.
    • Use an external parameter entity Declaration to name and then call the Suite Module of Modules, which names all the potential modules, for the Journal Publishing Tag Set, the module %modules.ent;.
    • Use an external parameter entity reference to call in the NISO Access and Indicators Exchange Model (%JATS-ali-namespace.ent;) that defines the namespace, prefix, and pseudo-attribute @xmlns used by ALI elements.
    • Use an external parameter entity reference to call in the standard Common Attributes Module (%JATS-common-atts.ent;) that defines attributes used by nearly all elements.
    • Use an external parameter entity reference to call the Tag-Set-specific class overrides, for the Journal Publishing Tag Set, the module %journalpubcustom-classes.ent;.
    • Use an external parameter entity reference to call the Suite default classes, for the Journal Publishing Tag Set, the module %default-classes.ent;.
    • Use an external parameter entity reference to call the Tag-Set-specific mix overrides, for the Journal Publishing Tag Set, the module %journalpubcustom-mixes.ent;.
    • Use an external parameter entity reference to call the Suite default mixes, for the Journal Publishing Tag Set, the module %default-mixes.ent;.
    • Use an external parameter entity reference to call the Tag-Set-specific content models and attribute list overrides, for the Journal Publishing Tag Set, the module %journalpubcustom-models.ent;.
    • Use an external parameter entity reference to call in the standard Common Module (%common.ent;) that defines elements and attributes so common they are used by many modules.
    • Use an external parameter entity reference to call any new Tag-Set-specific module defining new block-level or phrase-level elements. For the Journal Publishing Tag Set, there are no such modules, but, for example, the Book Tag Set made from this Archiving Tag Set defines book-specific metadata.
    • Select, from the Module of Modules, those modules which contain the elements needed for your Tag Set (for instance, selecting lists and not selecting math elements) and call in each of the modules needed. The Journal Publishing Tag Set calls these in alphabetical order, since the order does not matter.
    • Define the document element and any other unique elements and entities needed for this Tag Set. For example, the Journal Publishing Tag Set declares only a few elements including: <article> [the top-level element] and its potential components: <front>, <body>, <back>, <sub-article>, and <response>.
Namespaces and MathML
When JATS was first designed, many software tools did not handle multiple redefinitions of the same namespace cleanly and correctly. Therefore, the following namespace prefixes, namespace URIs, and xmlns declarations are declared in the MathML DTD setup modules or in the MathML 2.0 and MathML 3.0 QName modules (and MathML 2.0 and MathML 3.0 schema modules for XSD and RNG) rather than directly within JATS-specific modules:
  • XLink
    • The XLink prefix is set to “xlink”.
    • The XLink namespace URI is set to “http://www.w3.org/1999/xlink”.
    • The XLink xmlns pseudo-attribute is set as follows, for use in attribute lists:
      xmlns:xlink  CDATA  #FIXED 'http://www.w3.org/1999/xlink'
  • MathML
    • The MathML namespace prefix is set to “mml”.
    • The MathML namespace URI is set to “http://www.w3.org/1998/Math/MathML”.
    • The MathML xmlns pseudo-attribute is set as follows, for use in attribute lists:
      xmlns:mml  CDATA  #FIXED 'http://www.w3.org/1998/Math/MathML'
  • W3C Schema Instance
    • The W3C Schema namespace prefix is set to “xsi”.
    • The W3C Schema namespace URI is set to “http://www.w3.org/2001/XMLSchema-instance”.
    • The W3C schema xmlns pseudo-attribute is set as follows, for use in attribute lists:
      xmlns:xsi  CDATA  #FIXED 'http://www.w3.org/2001/XMLSchema-instance'
The math and linking namespaces are defined inside the MathML modules, rather than defined as part of the JATS modules, as the ALI namespace (for example) is defined. This has annoying subsetting implications. It means that if you do not include the MathML setup modules and MathML modules in your tag set, you will not have the math and linking namespaces defined, unless you define them yourself.
Thus, if you want to use the JATS modules to create a tag set that does not include MathML, there are two options open to you:
  • Include the MathML setup modules and MathML DTD modules and ignore them in your tagging and in your documentation; or
  • Write your own namespace setup module that declares the namespaces mentioned above.
JATS Naming Conventions
Element and Attribute Naming Rules
  • CASE — All XML names originating in this Tag Set or in the Suite are to be in lower case. Such names include element names, attribute names, parameter entity names, notation names, and IDs. The casing and interior punctuation of element-type names, attribute names, and parameter entity names inherited from PUBLIC models (such as the NISO JATS XHTML-inspired table model, the MathML Tag Set, or the OASIS XML Exchange (CALS) table model) are unchanged. That means that they occur in the case in which they were found in the original module, and so may be in mixed case or upper case (e.g., %Flow.mix;).
  • MULTI-WORD NAMES — When two or more words are concatenated into an element name, attribute name, or parameter entity name, a hyphen is placed between the words, for example, <verse-group>, <article-title>, and <award-id>.
  • WORD STANDARDIZATION — Abbreviations may be used when words are used in combination. When a word stands alone as a name, it is not abbreviated. Thus, the element <conference> uses the full word “conference”, but the conference combinations (such as <conf-theme> and <conf-num>) use the abbreviation “conf”. Abbreviations are standardized so that, for example, “figure” is always used as “fig” (as in the element <fig-group>) and “group” is not abbreviated (as in the elements <fig-group>, <kwd-group>, and <fn-group>).
  • EMPHASIS — The typographic emphasis elements are usually spelled out in full, for example, <bold> (rather than “<b>”), <italic>, and <underline> instead of being differentiated using attribute values on an element such as <emphasis>. Superscript and subscript are not considered to be purely typographic, and each is a separate element: <sub> and <sup>.
The following table contains a growing list of abbreviations/names to be used in combined tag names (element type names), attribute names, and parameter entity names. (Words in the list below that are not abbreviated are displayed in italics.)
ORIGINAL WORD ABBREVIATION
acknowledgment ack
address addr
affiliation aff
alternate/alternative-something alt
alternatives alternatives
article article
attribution attrib
author author
biography bio
chemical chem
communication communication
conference conf
contributor/contribution contrib
corresponding corresp
count count
cross x (no hyphen)
definition def
description desc
display disp
editor editor
end end
equal equal
external ext
figure fig
first f (no hyphen; <fpage>)
footnote fn
formula formula
government gov
graphic graphic
group/grouping group
heading/header head
identifier/ID id
inline inline
institution institution
item item
journal journal
keyword kwd
last l (no hyphen; <lpage>)
link link
list list
location loc
material material
metadata meta
number num
page page
paragraph p
prefix prefix
proceedings proceedings
publication pub
publisher publisher
quote quote
reference ref
related related
section sec
sequence/sequential seq
series series
size size
standard std
start start
statement statement
structure struct
subject subj
subscript sub (rather than “inferior”)
suffix suffix
superscript sup (rather than “superior”)
supplement supplement
supplementary supplementary
table table
title title
translated/translator trans
type type
underline underline
version version
volume vol
word word
wrapper wrap
File Naming Conventions
This Tag Library describes the components for the JATS Authoring Tag Set, one of the several JATS tag sets. Each of the tag sets is described in a DTD, an XSD schema, and a RELAX NG schema. For the DTD, the base DTD module (delivered as the file JATS-archivearticle1-4d1.dtd) calls in all the other DTD fragment modules as external parameter entities. Each module specific to this Archiving Tag Set (therefore, not part of the Suite) takes the prefix “JATS-archivecustom-” The same prefix has been followed in the other two constraint languages/schemas.
Each DTD and DTD fragment module has been assigned a unique formal public identifier (fpi). File names are never referenced directly in the DTD; the file is referred to by the name of an external parameter entity, which names the fpi and a system name for the file. The external parameter entity name has been set to the initial delivery filename, that is, with the version number not part of the name.
The three JATS DTDs, the individual DTD-fragment modules of this Archiving Tag Set and the Suite, the XSD schema modules, and the RELAX NG schema modules have been given DOS/Windows 3-digit suffixes indicating their type:
*.dtd
A module that can be used as the top level of an XML hierarchy. Used for the Archiving and Interchange Tag Set top level, JATS-archivearticle1-4d1.dtd, but also the suffix for public tag set modules that have been included in the Tag Set such as the MathML Tag Set.
*.ent
A DTD fragment for incorporation into a full DTD. May contain element declarations, entity declarations, etc., for example, JATS-articlemeta1-4d1.ent.
*.mod
A DTD fragment for incorporation into a full DTD. May contain element declarations, entity declarations, etc. This extension has the same meaning as *.ent and is only used to maintain the extension names dictated by the inclusion of PUBLIC tag set and/or schema fragments, for example, mathml2-qname-1.mod.
*.xsd
A W3C XML Schema (XSD) schema module, for example, JATS-archivearticle1-4d1.xsd.
*.rng
A RELAX NG schema module, for example, JATS-archivearticle1-4d1.rng and JATS-articlemeta1-4d1.ent.rng.
All NISO JATS versions reflect the major version number in the file name. For example, a module whose name in early versions of the NLM Tag Set was list.ent is now named JATS-list1-4d1.ent (to indicate that it is part of the NISO JATS 1.4d1 Committee Draft). (Note: The parameter entity that references the file is still called %list.ent;, but it now references a file with the JATS- prefix and the version number embedded, namely JATS-list1-4d1.ent.)
The current plan is that future dot releases (1.1, 1.2, 1.3, 1.4, etc.) will be reflected in the filename (for example, JATS-list1-3.ent, JATS-list1-4d1.ent, etc.). Filenames will not be named with a single digit as was done in earlier versions. For example, the file name for the list module in JATS 1.3d1 was JATS-list1.ent; that file is named JATS-list1-3.ent in the current 1.3 standard and JATS-list1-4d1.ent in this release. The next major release, JATS 2.0, will probably make the name of that module JATS-list2.ent.
Modules in JATS Archiving and Suite
The Journal Article Tag Suite was created to allow a multiplicity of tag sets, based on the needs of the intended use, for example, an authoring tag set versus an archiving tag set for a repository. The Journal Archiving Tag Set (JATS-archivearticle1-4d1.dtd) and its specific customization modules (%archivecustom-classes.ent; %archivecustom-mixes.ent; %archivecustom-models.ent; and %archivecustom-modules.ent;) define an archival and interchange focused Tag Set. The following modules are critical for the customization process that creates that Tag Set:
Journal Archiving and Interchange DTD
(File names JATS-archivearticle1-4d1.dtd and JATS-archivearticle1-4d1-mathml3.dtd) The top-level Journal Archiving Tag Set DTD Module that declares the document element (<article>) and the other top-level elements that define a journal article (front matter, back matter, and sub-articles or responses). All elements but these few are declared in the modules of the Suite. The DTD invokes all the other modules it uses, by reference, as external parameter entities: first the Archiving Tag-Set-specific Module of Modules is called to name all Archive-specific customized modules, then the Suite Module of Modules is called to name all the potential modules from the Suite, then customized and default modules are called (for parameter entities naming element classes, mixes, and models), then the Common Module for shared elements and attribute lists is called, and finally all the other modules are called as needed.
Archiving Tag-Set-specific Module to Name Modules
(parameter entity %archivecustom-modules.ent; Defines all the external modules that are specific to the Archiving Tag Set (except itself, which must be both named and called inside the DTD). A Tag Set selects from these modules by referencing the module names through external parameter entities. The entities are declared in the Archiving Tag-Set-specific Module of Modules (%archivecustom-modules.ent;), but referenced (or not) in the DTD proper. To include a set of elements (such as all the lists or all the MathML elements), a DTD references the external parameter entity of the module that contains these declarations.
Implementor’s Note: The Archiving Tag-Set-specific Module of Modules and the Suite Module to Name the Modules need to be the among the first external modules called by the Archiving DTD. Customization modules for classes, mixes, and models will typically be called following the Archiving Tag-Set-specific modules and the Module of Modules.
Archiving Tag-Set-specific Class Customizations Module
(parameter entity %archivecustom-classes.ent;) Sets up parameter entities that will be used to override default classes prescribed by the %default-classes.ent; module.
Implementor’s Note: This module must be called after the Archiving Tag-Set-specific Module of Modules (%archivecustom-modules.ent;) and the Suite Module to Name the Modules (%modules.ent;) but before any other module, including specifically the %default-classes.ent; module (which this module overrides) and the %archivecustom-mixes.ent; and "%archivecustom-models.ent; modules (which build on this module).
Archiving Tag-Set-specific Mix Customizations Module
(parameter entity %archivecustom-mixes.ent;) Sets up parameter entities that will be used to override default mixes (groupings made of “classes”) prescribed by the %default-mixes.ent; module.
Implementor’s Note: This module must be called after the Archiving Customize Classes Module (%archivecustom-classes.ent;) and the Default Classes Module (%default-classes.ent;) but before any other module, including specifically the %default-mixes.ent; module (which this module overrides) and the %archivecustom-models.ent; module (which builds on this module).
Archiving Tag-Set-specific Models/Attributes Customizations Module
(parameter entity %archivecustom-models.ent;) Sets up parameter entities that will be used to override default content model parameter entities set elsewhere in the Suite. Also defines customizable attribute Declared Values and attribute lists for the Tag Set being defined.
Implementor’s Note: This module must be called after the Archiving Tag Set Customize Mixes Module (%archivecustom-mixes.ent;) and Default Mixes Module (%default-mixes.ent;) but before any “base” module of the interchange Suite.
The NISO JATS common modules, which are overridden by the customizations, include the following:
Suite Module to Name the Modules
(parameter entity %modules.ent;) Defines all the external modules that are part of the modular NISO JATS DTD Suite (except the module itself, which must be both named and called inside a DTD). A Tag Set selects from the Suite modules by referencing the module names through external parameter entities. The entities are declared in the Module to Name the Modules (%modules.ent;), but referenced (or not) in the DTD proper. To include a set of elements (such as all the article metadata or all the display elements) a DTD references the external parameter entity of the module that contains these declarations.
Implementor’s Note: The Archiving Tag-Set-specific Module of Modules and the Suite Module to Name the Modules need to be the among the first external modules called by the Archiving DTD. Customization modules for classes, mixes, and models will typically be called next, following these two.
ALI Namespace Module
(parameter entity %JATS-ali-namespace.ent;) Namespace setup for the NISO Access License and Indicators elements (prefix “ali:”). The elements are defined in the JATS Common module (described below).
Common (Shared) Attributes Module
(parameter entity %JATS-common-atts.ent;) Defines attributes intended to be used on ALL elements defined in the NISO JATS, including table elements for both the XHTML-inspired and OASIS-inspired table models, with the exception of <mml:math> whose namespaces JATS does not control.
Must be called after all module-of-modules modules and any namespacing modules, but before all customization (over-ride) modules.
Suite Default Element Classes Module
(parameter entity %default-classes.ent;) Sets up the parameter entities that name the element members of each class that will be used to establish the content models.
Implementor’s Note: This module must be called before the Archiving Customize Mixes Module (%archivecustom-mixes.ent;) and the Default Element Mixes Module (%default-mixes.ent;), as well as the Archiving Customize Models Module, %archivecustom-models.ent; (which builds on those modules).
Suite Default Element Mixes Module
(parameter entity %default-mixes.ent;) Sets up the parameter entities that name mixes (groupings made of “classes”) that will be used to establish the content models.
Implementor’s Note: This module must be called before the Archiving Customize Models Module (%archivecustom-models.ent;") or any “base” module of the interchange Suite.
Common (Shared) Elements Module
(parameter entity %common.ent;) Declarations for elements, attributes, entities, and notations that are shared by more than one class module.
Implementor’s Note: This module must be called before any of the modules comprising the interchange Suite.
The modules that define the elements and attributes that make up the Suite are defined by the following modules. These too may be overridden by the customization modules of the Archiving DTD.
Article Metadata Elements Module
(parameter entity %articlemeta.ent;) Declares the metadata elements (issue elements and article header elements) used to describe a journal article.
Design Note: Metadata elements that describe the journal are in the Journal Metadata Module, %journalmeta.ent;.
Back Matter Elements Module
(parameter entity %backmatter.ent;) Declares elements that are not part of the main textual flow of a work, but are considered to be ancillary material such as appendices, glossaries, and bibliographic reference lists.
Display Class Elements Module
(parameter entity %display.ent;) Declares the display-related elements, such as figures, graphics, math, chemical expressions and structures, tables, etc.
Format Class Elements Module
(parameter entity %format.ent;) Declares elements concerned with rendition of output, for example, printing on a page or display on a screen. This module includes the elements in the Appearance Class, the Break Class, and the Emphasis Class.
Funding Elements Module
(parameter entity %funding.ent;) Declares elements that model open access, grant, sponsorship, or other funding information, for example, the grant number (<award-id>) and the grant holder (<principal-award-recipient>).
Journal Metadata Elements Module
(parameter entity %journalmeta.ent;) Declares the elements used to describe the journal in which a journal article is published.
Design Note: The issue and article metadata is defined in the Article Metadata module, %articlemeta.ent;.
Link Class Elements Module
(parameter entity %link.ent;) Declares elements that are links (internal or external) by definition, such as URLs (<uri>) and internal cross references (<xref>).
List Class Elements Module
(parameter entity %list.ent;) Declares the elements in the List Class; these are all lists except the lists of bibliographic references (citations). Lists are considered to be composed of items.
Math Class Elements Module
(parameter entity %math.ent;) Declares the elements in the math classes such as display equations.
NLM Citation Module
(parameter entity %nlmcitation.ent;) Adds the model for the NLM structured bibliographic citation element (<nlm-citation>). This element is now obsolete and should be replaced by either an <element-citation> element or a <mixed-citation> element.
Paragraph-Like Elements Module
(parameter entity %para.ent;) Declares structural, non-display elements that may appear in the same places as a paragraph. These elements are named in the various paragraph class parameter entities.
Subject Phrase Class Elements Module
(parameter entity %phrase.ent;) Declares the Phrase Class elements, that is, names the inline, subject-specific elements.
Bibliographic Reference (Citation) Class Elements Module
(parameter entity %references.ent;) Declares the bibliographic reference elements.
Related Object Elements Module
(parameter entity %related-object.ent;) Defines the container element <related-object>, which is used as a container for text links and description of an external object such as a spreadsheet or a book that is related to the current work.
Section Class Elements Module
(parameter entity %section.ent;) Declares the elements of the Section Class, that is, declares all section-level elements in the Journal Archiving Tag Set.
The modules that define the MathML 2.0 AND MathML 3.0 elements and attributes:
MathML 2.0 Setup Module
(parameter entity %mathmlsetup.ent;) Invokes the MathML 2.0 modules.
Implementor’s Note:: To include the MathML 2.0 elements, a DTD must reference this module. This module sets up all parameter entities needed to use the MathML 2.0 Tag Set and references (invokes) the MathML 2.0 Tag Set Module, which, in turn, invokes all the other MathML 2.0 modules. Warning: MathML 2.0 and MathML 3.0 may not be used together; a Tag Set must choose one or the other.
MathML 3.0 Setup Module
(parameter entity %mathml3-mathmlsetup.ent;) Invokes the MathML 3.0 modules.
Implementor’s Note:: To include the MathML 3.0 elements, a DTD must reference this module. This module sets up all parameter entities needed to use the MathML 3.0 Tag Set and references (invokes) the MathML 3.0 Tag Set Module, which, in turn, invokes all the other MathML 3.0 modules. Warning: MathML 2.0 and MathML 3.0 may not be used together; a Tag Set must choose one or the other.
MathML 3.0 Modules
(parameter entity %mathml3-modules.ent;) Names the modules needed for MathML 3.0.
MathML DTD
(parameter entity %mathml.dtd;) Used for either the Mathematical Markup Language (MathML) 2.0 or the MathML 3.0, an XML application for describing mathematical notation and capturing both its structure and content.
MathML Qualified Names 1.0
(parameter entity %mathml-qname.mod;) Declares parameter entities to support namespace-qualified names, namespace declarations, and name prefixing for MathML, as well as declares the parameter entities used to provide namespace-qualified names for all MathML element types. Used for either MathML 2.0 or MathML 3.0.
Extra Entities for MathML
(parameter entity %ent-mmlextra;) Used for MathML processing. Used for either MathML 2.0 or MathML 3.0.
Aliases for MathML
(parameter entity %ent-mmlalias;) Used for MathML processing. Used for either MathML 2.0 or MathML 3.0.
The modules that define the NISO JATS XHTML-inspired table model are:
NISO JATS XHTML-inspired Table Setup Module
(parameter entity %XHTMLtablesetup.ent;) Sets all parameter entities needed by the NISO JATS XHTML-inspired Table Module, and then invokes the module containing that model.
To include the NISO JATS XHTML-inspired table model in a tag set, a DTD must reference this module. This module sets up all parameter entities needed to use the XHTML-inspired Table Module and references (invokes) the NISO JATS XHTML-inspired Table Module. (See next item.)
NISO JATS XHTML-inspired Table Module
(parameter entity %xhtml-table-1.mod;) The public XML DTD version of the XHTML-inspired Table Module. This module is invoked from the module %XHTMLtablesetup.ent;. (See previous item.) This is the default table model for JATS.
NISO JATS XHTML-inspired Table Style Module
(parameter entity %xhtml-inlstyle-1.mod;) Declares the @style attribute, which supports inline style markup for elements such as <td> and <tr> within XHTML-inspired tables.
The modules that define BITS included index terms and overrides to them:
BITS Embedded Index Element Module
(parameter entity %index-term.ent;) Element declarations the index elements which are embedded in the document narrative.
BITS Question and Answer Module
(parameter entity %question-answer.ent;) Element declarations for BITS questions and answers (not complete tests, but used to put build quizzes and tests.
JATS BITS Multi-lingual Attribute Overrides
(parameter entity %bits-multi-lingual-atts.ent;) Attribute declarations that add the multi-lingual attributes, by override, to all the content elements in BITS index terms and BITS question/answer. This is a separate module to make it easy to remove if BITS votes to add the multi-lingual material.
The modules that may be used to define a version of the Archiving DTD that uses the OASIS XML Exchange (CALS) table model include the following. Several of these modules (such as the DTD itself and the class customization module) are replacements for the default Archiving DTD and customization modules.
Journal Archiving and Interchange DTD with OASIS Tables (JATS-archive-oasis-article1-4d1.dtd)
Complete Archiving DTD for the creation of new journal articles. This extension of the Journal Archiving and Interchange DTD replaces the Archiving DTD module and invokes both the XHTML table and the CALS OASIS XML Exchange Table models.
Journal Archiving and Interchange DTD with OASIS Tables DTD-Specific Modules (JATS-archive-oasis-custom-modules1-4d1.ent)
The DTD-specific modules for the new Journal Archiving and Interchange DTD that includes OASIS Tables.
Journal Archiving and Interchange DTD with OASIS Tables Customize Classes Module (JATS-archive-oasis-custom-classes1-4d1.ent)
The class overrides for this new DTD. These repeat all the class overrides of the regular Archiving DTD, with the table and alternative classes modified to use the OASIS XML Exchange (CALS) table elements. There is no equivalent mix override module because this DTD uses the ordinary Archiving mix overrides.
JATS OASIS Table Namespace Module (JATS-oasis-namespace1-4d1.ent)
This modules establishes the prefix for the OASIS Exchange (CALS) table model, by default “oasis” (“<oasis:table>”).
JATS Namespaced OASIS XML Table Setup Module (JATS-oasis-tablesetup1-4d1.ent)
(parameter entity %oasis-tablesetup.ent;) Implementor’s Note: Not used in the current Archiving Tag Set. Sets all parameter entities needed by the OASIS XML Exchange (CALS) table model, and then invokes the module containing that model.
To include the OASIS XML Exchange (CALS) table model, a DTD must reference this module. This module sets up all parameter entities needed to use the OASIS table model and references (invokes) the OASIS XML Exchange (CALS) Table Model Module. This module has been modified to use a namespace prefix of “oasis” for all table elements, to permit both the OASIS Exchange (CALS) table models and XHTML-inspired table models to be used in one tag set. There is a separate Tag Library (https://jats.nlm.nih.gov/options/OASIS/tag-library/19990315/index.html) describing the OASIS elements, attributes, and parameter entities.
OASIS XML Exchange (CALS) Table Model Module (oasis-exchange.ent)
This is the OASIS XML Exchange (CALS) table model DTD fragment, modified to use the OASIS namespace and the “oasis” prefix. This module is invoked from the JATS OASIS XML Exchange (CALS) setup module.
The modules that define character entities and notations (all optional):
XML Special Characters Module
(parameter entity %xmlspecchars.ent;) Standard ISO XML special character entities used in JATS.
Custom Special Characters Module
(parameter entity %chars.ent;) Custom special character entities created specifically for use in JATS.
Notation Declarations Module
(parameter entity %notat.ent;) Container module for the Notation Declarations to be used with this Suite. These notations have been placed in their own module for easy expansion or replacement.