Balisage Paper: Customizing JATS (Journal Article Tag Suite)

Terminology: JATS Suite Versus JATS Tag Set

The Journal Article Tag Suite (JATS) is a growing set of modules which define the elements and attributes from which new tag sets can be developed. Think of the Suite as a build-a-tag-set kit. Individual Journal Article Tag Sets are built using the modules of the Suite and necessary new tag-set-specific modules.

Journal Article Tag Suite for Journal Articles

The core JATS document type is a journal article, and the ANSI/NISO JATS Tag Sets are journal article tag sets. The JATS standard (ANSI/NISO Z39.96-2019 JATS: Journal Article Tag Suite) defines XML elements and attributes that describe the content and/or metadata of journal articles —including research articles; subject review articles; non-research articles; editorials; letters; product, software, and book reviews; and included peer reviews or author responses— with the intent of providing a common format in which publishers, vendors, web hosts, libraries, and archives can produce, exchange, and store journal article content.

The intent of the Tag Suite is to preserve the intellectual content of journal articles independent of the format in which that content was originally delivered. Although it does not model any particular sequence or textual format, the Tag Suite enables a JATS user to capture structural and semantic components of existing tagged material.

JATS was originally developed as a conversion target, because, at that time, most of the large journal publishers used their own proprietary formats and a way was needed both for them to interchange content with each other and for archives, libraries, aggregators, hosters, and vendors to accept content readily from all of them.

Originally, JATS was designed for STEM articles (Science, Technology, Engineering, Mathematics), but it is now used internationally for journals of all disciplines. In addition, we have seen JATS tag sets built for:

JATS Article Tag Sets

There are (as of August 2019) three official journal article instantiations of the Suite, loosely called the JATS ‘Tag Sets’. These tag sets are built from the elements and attributes defined in the Suite and are intended to provide models for archiving, interchange, processing, publishing, and authoring journal article metadata and/or article content.

These three JATS Journal Article Tag Sets are available in several flavors:

Thus there are four Archiving Tag Sets, four Publishing Tag Sets, and two Authoring Tag Sets. (Authoring does not provide the CALS table option.)

Other JATS-based Tag Sets

In addition to the three JATS Journal Article Tag Sets (10 flavors in all), there are NISO- or NLM-sponsored tag sets, as well as many non-public subsets and supersets.

JATS History

JATS roots go back to 1985 and the very first DTD (an SGML DTD) ever published. It was produced (in advance of any SGML parsers) by the Association of American Publishers as one of three tag sets (journal articles, books, and journals). The AAP DTD (also known as the AAP Electronic Manuscript Standard and the AAP/EPSIG standard) was ratified as the U.S. standard ANSI/NISO Z39.59 in 1988. By 1993, the AAP Article DTD had metamorphosized into the international ISO 12083 Electronic Manuscript Preparation and Markup, which was reworked over the next few years and reemerged as ANSI/NISO 12083-1995, which was a nearly complete rewrite of the original ISO 12083.

In December 2001, the Harvard University Library under a grant from the Mellon Foundation commissioned a report to address the feasibility of developing a common structure (model/tag set) that could reasonably represent the intellectual content of journal articles. The resulting E-Journal Archival DTD Feasibility Study for the Harvard University E-Journal Archiving Project came to the conclusion that yes, a single model/tag set was possible and probably desirable, but that a model to meet that need did not then exist.

In 2002, NCBI (National Center for Biotechnology Information) of the National Library of Medicine began work on a single model for journal articles, thereafter called the NLM DTD, based on the 1998-2002 PMC DTD that had been written for PubMed Central. This DTD was (and is) in use and widely adopted even outside the realm of STEM articles.

NLM gave NISO the NLM DTD to use as a start to JATS and a NISO JATS Working Group was formed. The first JATS (NISO Z39.96.201x version 0.4) was released by NISO on March 30, 2011 as a Draft Standard for Trial Use. There was a 6-month public Comment Period and after the comments were resolved, the JATS Working Group released the JATS version 1.0 in 2012. (ANSI NISO Z39.96-2012). JATS became a continuous maintenance standard at NISO, under the JATS Standing Committee. which resolves user requests and publishes Committee Drafts once or twice a year. JATS 1.1 was issued in 2015 (JATS 1.1 ANSI NISO Z39.96-2015), and JATS 1.2 was issued in 2019 (JATS 1.2 ANSI/NISO Z39.96-2019)

Figure 1

JATS Adoption

JATS is how much of the world publishes/interchanges journal articles. JATS is in use in at least 25 countries world-wide (US, UK, Germany, France, Australia, Japan, Russia, Brazil, Egypt, etc.), and most middle-sized and small publishers world-wide publish journal articles in JATS. All of the huge publishers, who typically use their own bespoke tag sets, produce JATS for interchange or archival deposit. Many public archives accept (or require) JATS, for example Australian National Library, British National Library, Europe PMC, ITHAKA/JSTOR, Library of Congress (US), PubMed Central, SciELO, and many others. Conversion vendors all know how to handle JATS; numerous web-hosting and service vendors require or support JATS; and there are more tools and products written every day for authoring in JATS and conversion from Microsoft Word to JATS.

As Jeff Beck of NCBI said at JATS-Con (the JATS user conference) in 2017:

Why is JATS Customizable?

The JATS/NLM customization mechanism was designed in the 1980s to synchronize the maintenance of tag sets for organizations that needed to maintain multiple highly-interrelated tag sets. The idea was that most structural models (figures, tables, lists, sidebars) and most inline elements should be the same across all tag sets, with only a few differences where necessary. The top-level elements and their direct descendants would be different.

As an example, consider the following situation. A single organization needs to develop and maintain 25 related tag sets:

Each of the 25 document types is defined in a separate DTD; all DTDs share the modular library of components. The customization mechanism must allow the organization to change models whenever they need to but only when they want to.

A modular system with modular overrides allows the organization to localize changes in a very few files. Then a simple find-in-files mechanism, from an editing tool or the operating system, can tell them that, for example: amongst these 25 related vocabularies, there are 6 variations on this element and here are the exact Parameter Entities where that change can be examined or changed.

Who Customizes JATS?

While it does take some XML knowledge and an understanding of DTD structure and Parameter Entities to maintain a JATS-based tag set, it does not require XML experts. The mechanism is simple to learn. Organizational customizations are typically maintained by XML-aware programmers in the journal departments of the organization, but some JATS users have trained their senior editorial staff to do it, and some hire consultants, particularly if they do not modify their tag sets very often.

The 10 JATS Tag Sets and two BITS Tag Sets are maintained in a modular library using the customization mechanism described in this paper. Schema maintenance, documentation, and testing for the 12 are performed by Mulberry Technologies, Inc. and sponsored by the National Center for Biotechnology Information of the US National Library of Medicine.

How to Customize JATS

JATS is distributed in XSD, DTD, and RELAX NG format, but is maintained as a DTD. The customization mechanism for DTDs is modularity and Parameter Entity overrides.

First, a brief syntax reminder on how Parameter Entities look and work. A Parameter Entity is composed of:

Some examples include: %list.class;, %emphasis.class;, %abstract-model;, %title-elements;, and %abstract-atts;, where the bold words are the Parameter Entity names. Parameter Entities (like programming language parameters) are established to be overridden. Internal Parameter Entities are for string replacement. First you define a Parameter Entity, then you may use it for string substitution as many times as you want. For example:

      'def-list | list | var-list | term-list'

    <!ENTITY % ref-list-model "some model or other"       >
    <!ENTITY % ref-list-atts  "a list of attributes"      >

    <!ELEMENT  ref-list        %ref-list-model;           >
    <!ATTLIST  ref-list
                 %ref-list-atts;                            >

JATS is a Modular DTD System

Each JATS DTD is built using a library of DTD-fragment modules. Each module contains definitions for a group of related declarations. Each DTD is free to call in only the library modules it needs. If your target tag set has no bibliographic references, then leave out the modules defining those elements. That said, most JATS-based DTDs use most of the base JATS modules, adding a few modules of their own.

Three non-JATS exemplar models are shown below:

Figure 2

Modules are called into a DTD using External Parameter Entities, one external entity per module called. This is string substitution on a grand scale, where the entire contents of a module file can be called into the DTD at once.

Best practice in using a modular DTD library is to set up a system catalog and use it to provide access to the modules of the Suite. Catalogs provide an indirection mechanism to associates an established identifier with a URI — typically a file name. In this example, I will be using an OASIS XML Catalog specification catalog, but any method of catalog indirection would work.

OASIS XML catalogs use formal public identifiers (fpis) and establish one fpi and its filename (URI) equivalent for each module used in the tag set. So my customization process would be:

• Assign each DTD-specific file module a formal public identifier (fpi)

• Name each DTD-specific files in a catalog entry (an OASIS XML catalog shown) in the same catalog that already includes all the JATS modules.

      <public
        publicId="-//Mulberry//DTD Mystuff Models v1.0 20190710//EN"  
        uri="my-very-own-custom-models.ent" />

• In your modules, define one external Parameter Entity for each DTD-specific module

      <!ENTITY % the-custom-models.ent
         PUBLIC "-//Mulberry//DTD Mystuff Models v1.0 20190710//EN" 
         "my-very-own-custom-models.ent"                            />

• Then reference (call) your module using a Parameter Entity in your DTD. This places the entire file logically into the DTD at the point of reference.

      %the-custom-models.ent;

JATS-based Custom DTD Assembled from Modules

There is one very important rule when making new customizations using this method. Never, ever copy a JATS module and edit it. Or, more succinctly:

Never change the published JATS modules — Override them.

Each new document type is a new DTD that defines, in its DTD-specific modules, the Parameter Entities that override the JATS default Parameter Entities. Each DTD may use as many of the JATS base modules (or as few) as necessary. The DTD module typically defines only the top-level element (document element) and (maybe) its immediate children, and calls in all the Suite modules it needs to define the rest of the elements. New (non-JATS) elements (Learning Objectives, parts lists, product codes, taxonomic descriptions) are typically defined in their own modules or in the DTD module. In this way, all customizations are isolated in a few DTD-specific modules. When a new version of JATS is issued, the user can just plug in the new JATS modules and use the new version, unless they have overridden something that has changed in the new version, and the organization wants those new JATS changes. In such as case, add the contents of the new JATS Parameter Entit(ies) to your custom override Parameter Entit(ies).

Typical Scenario for a New JATS Customization

A JATS user wanting to make a new document type (for Reports for example), typically creates at least five new modules and adds them to a local JATS library. And, of course, adds the names of all these modules to a catalog.

Table I

Report DTD	Names and models the new top-level element (<report>)and calls in all the needed modules, in order, first Report-DTD-specific modules and then JATS modules
Report-custom-modules	Names any new Report-DTD-specific modules created just for this DTD
Report-custom-classes	Overrides for JATS element collections (classes)
Report-custom-mixes	Override for JATS structures (mixes)
Report-custom-models	Overrides for JATS content models and attribute lists
Any new element modules	As many modules as necessary to define Report-DTD-specific new elements (Taxonomic material, parts list, whatever is entirely new and cannot be found in ordinary JATS)

Since the DTD module must perform specific functions in a specific sequence, the structure of a customized JATS-based DTD typically looks like the following. This sequence is important because parameter Entities must be defined before they are used, and the first declaration found is the definitive definition.

The JATS-based DTD module:

• names and describes itself and its purpose in an initial comment,

• names the DTD-specific Module of Modules, then invokes it,

• names the JATS Suite Module of Modules, then invokes it, and then

• calls in the rest of the modules:

  • invokes the DTD-specific class and mix override modules and the default classes and mixes they override,

  • invokes the Model customization module that overrides the element modules,

  • invokes all the necessary element modules, and then

  • defines the top-level element and its components (as needed).

Figure 3: Structure of a Customized DTD

As an example, here is a Report-DTD customized DTD fragment

• Modules have been named with external Parameter Entities.

• The DTD fragment call in all Report-DTD-specific modules, followed by the JATS modules being overridden.

• Report-DTD-specific Parameter Entities override JATS Parameter Entities. Anything the new Report DTD did not change is left alone; it is standard JATS.

    %Report-custom-modules.ent;
    %JATS-modules.ent;

    %Report-custom-classes.ent;
    %JATS-default-classes.ent;

    %Report-custom-mixes.ent;
    %JATS-default-mixes.ent;

    %Report-custom-models.ent;

    %JATS-common.ent;
    %JATS-articlemeta.ent;
    %JATS-backmatter.ent;
    %Report-new-stuff.ent;
       and so on for the other modules the Report DTD needs

Now, with all the component modules in place, the DTD can define the new document element (<report>) and maybe new children such as <report-metadata> and <report-body>.

Caution: you may define a lot you never use by including a module. If you include a whole module (it defines 20 elements) and your tag set only uses one element from the module, you have just defined a lot of elements that you will not use. So what? This is not a problem, so do not be concerned that some tools will warn you about these orphan declarations. The condition defined but not used is legal in XML and very handy in modular DTDs!

Adding Rules for Interchange

As the preceding paragraphs illustrate, the JATS-XML produced by one organization may be significantly different from the JATS-XML produced by a different organization, even when they are using the same flavor of the same base tag set. XML-to-XML transformation may be necessary for seamless interchange and integration.

Specific best practice recommendations for JATS are outside the scope of the ANSI/NISO standard and even outside the scope of the non-normative DTD, XSD, RELAXNG schemas, and the Tag Library documentation. Basic interoperability lies in being a related family of specifications, with changes isolated so differences can be easily determined and resolved if possible.

Detailed recommendations for interchange, how to use JATS in the same way, and what is best tagging practice are being developed by groups such as Pub Med Central and JATS4R (JATS for Reuse).