Repository navigation
Improve parsing of JATS documents #3583
Description
Background
JATS (Journal Article Tag Suite) is a standardized XML format used to encode, publish, and archive academic and scientific literature. It provides a common set of tags to structure article text, metadata (like authors and affiliations), figures, and citations, allowing research to be shared seamlessly across platforms like PubMed, CrossRef, and SciELO.
Docling supports the parsing of JATS through the declarative backend JatsDocumentBackend.
The first version was released with version 2.23.0 on Feb 17, 2025. Since then, the DoclingDocument data model has evolved and it now supports features that rich JATS document contain but had to be ignored in the first version.
Goal
The goal of this issue is to review the JATS backend and implement the parsing of features in JATS documents that can currently be support with DoclingDocument.
Some of these features were marked as TODO in the code and thus they should be easy to locate and implement. They include:
- Footnotes @aaarif796 feat(jats): support fn-group footnotes #3636
- Styling (bold, italic, superscript,...) @taru-garg-2000 feat(jats/inline-formula): Support emphasis elements and Inline formulas #3726 @Kylinny fix(jats): preserve styling in abstracts and footnotes #4361
- List type (ordered vs unordered and its marker) @aaarif796 fix(jats): preserve nested list structure in list items #3619
- Nested lists and nested objects in lists @aaarif796 fix(jats): preserve nested list structure in list items #3619
- Inline formulas @taru-garg-2000 Enhance JATS backend with Inline Formula parsing #3656
- Abstract with multiple sections fix(jats): preserve structured abstract sections #3584 fix(jats): preserve structured abstract sections and fix nested list parent #4172
- Hyperlinks @CreoEnMi-p feat(jats): preserve external hyperlinks #4029
- Embedded images @teachershuang feat(jats): embed local figure images #4041
The new implementation should include extended tests and updated groundtruth files.
Activity
PeterStaar-IBM commentedon Jun 13, 2026
partially resolved by #3584
aaarif796 commentedon Jun 17, 2026
I'd like to continue working on issue #3583, specifically the remaining JATS list handling aspects such as list item labels and list types.
PeterStaar-IBM commentedon Jun 17, 2026
@aaarif796 please go ahead!
taru-garg-2000 commentedon Jun 17, 2026
Hi there! I would like to help with this feature, have opened a PR for footnotes side of things #3610
taru-garg-2000 commentedon Jun 17, 2026
Hi there! If
Inline formulasis still up for grabs I would like to help, or maybe styling since that would be required groundwork for formulas.ceberam commentedon Jun 17, 2026
Thanks @taru-garg-2000 , please go ahead.
Apologies for closing your PR #3610 (even though you were the first to suggest an implementation) since I initially thought you created #3636 after some Github technical issues.
Your contribution on the inline formulas will be nevertheless much appreciated!
taru-garg-2000 commentedon Jun 17, 2026
No worries 😃, happy to help where I can.
taru-garg-2000 commentedon Jun 19, 2026
Hi @ceberam following up on #3583 — I've opened #3656 to scope out the inline formula piece specifically and kick off discussion on the design. Please give it a read when you get a chance.
Thanks!
CreoEnMi-p commentedon Aug 19, 2026
Hi @ceberam, I'd like to work on the remaining Hyperlinks part of #3583.
I plan to keep the initial scope focused on preserving external JATS links such as
<ext-link xlink:href="...">in the generatedDoclingDocument, including links combined with inline formatting. I'll add focused regression tests and update the affected groundtruth if needed.I intend to leave internal
<xref>resolution and the currently flattened reference-citation handling out of scope for this change. Please let me know if that scope sounds good.ceberam commentedon Aug 19, 2026
Thanks @CreoEnMi-p ! That's the right way to go. For internal
<xref>we need to add a new feature, which we are already working on, so you can focus on the external links. Please, have a look at how this has been addressed in other backends in case you can reuse some utilities.teachershuang commentedon Aug 20, 2026
Hi @ceberam, I'd like to work on the remaining embedded images part of #3583.
For an initial focused PR, I propose preserving images referenced by
<fig><graphic xlink:href="...">and attaching the resolved image as anImageRefto the generatedPictureItem. I would cover local resources relative to a file-based JATS document and add focused regression tests.Remote URL fetching and inline graphics would remain out of scope unless you prefer otherwise. Does this scope sound appropriate?
PeterStaar-IBM commentedon Aug 20, 2026
@teachershuang go for it!
Kylinny commentedon Sep 24, 2026
Hi! I'd like to take on the Styling (bold, italic, superscript, ...) item from the checklist. I'll implement the parsing in the JATS backend with extended tests and updated groundtruth files, then open a PR. Let me know if you have a preferred approach before I start.
fix(jats): preserve styling in abstracts and footnotes
Kylinny commentedon Sep 24, 2026
Opened PR #4361 for the remaining
Styling (bold, italic, superscript, ...)item: it preserves inline styling in JATS abstracts (plain + structured) and footnotes, which were previously flattened to plain text. Tests extended and the affected e2e groundtruth files regenerated: #4361matssun commentedon Sep 29, 2026
We've been evaluating JATS source fidelity for downstream evidence extraction and have now re-tested the relevant cases against Docling 2.131.0.
First, a clarification: the recently merged work under this issue is working as scoped. In particular, #4029 preserves a normal body
<ext-link>in our synthetic control, and #4041 loads a local figure image whenfetch_images=Trueandenable_local_fetch=True. The remaining gaps we see are outside those PRs' stated scope.Using two PLOS JATS articles plus minimized controls, we found these residual cases:
<sub-article>is not walked. In these two articles, the 17 / 16 external links we originally counted are entirely in the published peer-review record, so none appears in the reading.author-notes.<xref>text survives, but the target is dropped. We see 110 / 42 instances in the two articles. I saw the earlier comment here that internal<xref>requires a new feature and is already being worked on — is there a public issue/PR we should follow or contribute tests to?fn-groupare not represented. In these articles that includesauthor-notesand 11table-wrap-footfootnotes.<alternatives>containing<mml:math>plus a graphic, with no<tex-math>, so both display and inline formulas remain absent from the reading.graphic/@xlink:href. The PLOS figures useinfo:doi/...references, so feat(jats): embed local figure images #4041 correctly does not fetch them; even for the local-image control that does load, the resulting image is embedded as adata:URI and the original source reference is no longer available.These observations are unchanged from 2.130.0 to 2.131.0 on the fixed corpus. We also have minimized synthetic controls that separate "the mechanism does not work" from "the source construct lies outside the currently walked region."
We don't want to duplicate active work or turn this umbrella issue into a collection of unrelated proposals. Would you prefer these residual cases to be split into separate follow-up issues, and are any of them already being addressed beyond the internal
<xref>work mentioned above?We're happy to contribute focused fixtures/tests or small implementation slices where they fit the existing
DoclingDocumentmodel.fix(jats): preserve styling in abstracts and footnotes (#4361)
ceberam commentedon Oct 6, 2026
Closing since all the tasks have been completed.