jats - JATS XML Parser

A Python CLI tool for converting JATS (Journal Article Tag Suite) XML files to Markdown format, with support for extracting peer review comments and author responses.

Overview

jats parses JATS XML files from scientific publishers (bioRxiv, eLife, etc.) and converts them to clean, readable Markdown. It's particularly useful for working with preprint manuscripts and their associated peer review materials.

Key Features

Convert JATS XML articles to Markdown
Extract peer review comments and author responses from multi-article XML files
Support for bioRxiv manifest files (optional metadata)
Organize reviews and responses by revision round
Simple CLI interface with stdout or file output

Installation

Prerequisites

Python >=3.10

Install with uv (recommended)

cd jats
uv pip install -e .

Install with pip

cd jats
pip install -e .

Usage

Basic Conversion

Convert a JATS XML file to Markdown:

# Output to stdout
jats convert article.xml

# Output to file
jats convert article.xml -o article.md

# With bioRxiv manifest file (optional)
jats convert article.xml -m manifest.xml -o article.md

Extract Peer Reviews

Extract peer review comments and author responses from JATS XML files that include sub-articles (common in eLife and some bioRxiv articles):

# Extract reviews and responses to separate files
jats convert article.xml -o article.md -r output_base

# Creates:
# - output_base_reviews.md    (all review comments, organized by round)
# - output_base_responses.md  (all author responses, organized by round)

The -r flag extracts sub-articles with the following JATS article types:

Review comments: decision-letter, referee-report, editor-report, reviewer-report
Author responses: author-comment, reply

Reviews and responses are automatically organized by revision round using JATS4R peer-review-revision-round metadata (defaults to round 1 if not specified).

Examples

Convert bioRxiv Preprint

jats convert 2023.01.01.12345.xml -o paper.md

Convert eLife Article with Peer Reviews

# Convert main article and extract reviews
jats convert elife-12345-v1.xml -o paper.md -r elife-12345-v1

# Output files:
# - paper.md                        (main article)
# - elife-12345-v1_reviews.md      (peer review comments)
# - elife-12345-v1_responses.md    (author responses)

bioRxiv with Manifest

# manifest.xml provides additional metadata
jats convert article.xml -m manifest.xml -o article.md

Input File Format

jats expects JATS XML files following the JATS (Journal Article Tag Suite) standard. This format is used by:

bioRxiv and medRxiv preprint servers
eLife journal
PubMed Central (PMC)
Many other scientific publishers

JATS XML Structure

A typical JATS XML file contains:

<front>: Article metadata (title, authors, abstract)
<body>: Main article content organized in sections
<back>: References, acknowledgments, etc.
<sub-article>: Optional peer review materials (eLife, some bioRxiv)

Manifest Files (bioRxiv)

bioRxiv articles may include an optional manifest.xml file that provides:

Collection/category information
Version history
Links to published versions
Peer review URLs

Output Format

jats converts JATS XML to clean, readable Markdown with:

Article title as H1 heading
Authors with affiliations
Abstract
Body sections with appropriate heading levels
Inline figures with captions
References (when available)

Peer Review Output

When using -r, peer review materials are extracted to separate Markdown files:

Reviews file (*_reviews.md):

# Revision Round 1

## Reviewer 1

[Review content...]

---

## Reviewer 2

[Review content...]

Responses file (*_responses.md):

# Revision Round 1

## Author Response

[Response content...]

Development

Running Tests

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

Project Structure

jats/
├── jats/
│   ├── __init__.py
│   ├── main.py         # CLI entry point
│   ├── parser.py       # JATS XML parsing
│   ├── converter.py    # Markdown conversion
│   └── models.py       # Data models
├── tests/
│   ├── test_*.py       # Test files
│   └── *.xml           # Test fixtures
├── pyproject.toml      # Package configuration
└── README.md

See DEVELOPMENT.md for detailed development documentation and code style guide.

Known Limitations and Future Work

Source Data Files

Currently, <supplementary-material> elements (such as source data files for figures) are excluded from the markdown output. These typically appear as:

<supplementary-material id="fig6sdata1">
  <label>Figure 6—source data 1.</label>
  <caption>
    <title>PDF files containing original western blots...</title>
  </caption>
  <media mimetype="application" mime-subtype="zip" xlink:href="..."/>
</supplementary-material>

Future Enhancement: Add support for extracting and linking to source data files, including:

Source data download links
Separate source data manifest
Integration with figure references

JATS Resources

JATS Documentation
JATS4R (JATS for Reuse) - Recommendations for peer review tagging
bioRxiv JATS XML
eLife JATS XML

License

MIT

Support

For issues or questions, please open an issue on GitHub.

Release files for jats 0.2.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for jats 0.2.2
File	Size	Uploaded
jats-0.2.2.tar.gz	32.9 kB	Nov 18, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for jats 0.2.2
File	Interpreter	ABI	Platform	Reset
jats-0.2.2-py3-none-any.whl 30.6 kB Nov 18, 2025	Python 3	none	any	Details

Total release size: 63.6 kB

Release files / jats-0.2.2.tar.gz

Download URL	jats-0.2.2.tar.gz
Size	32.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`b9938285861a47e46d2aa49fc5f1b838be5076109fba0565f386c9eb55c618aa`
BLAKE2b-256 checksum How to use checksums	`b205d2386cd01e551d206742fe09da3ef63c54f254273ec7e9c091780b5e1080`
Upload date	Nov 18, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.5.7`

Release files / jats-0.2.2-py3-none-any.whl

Download URL	jats-0.2.2-py3-none-any.whl
Size	30.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`f38830bf480e56c0b2719638b240293d06cb23991747500267c7c7ee76161b28`
BLAKE2b-256 checksum How to use checksums	`53fd7000562e10db9075b938b703f4a6e82166f3496cec8ccb7756e44a5d64ad`
Upload date	Nov 18, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.5.7`