docling-project / docling-project/docling

Should DocLang XML round-trip a DoclingDocument losslessly?

Open
#3,918 2 comments 0 reactions 0 assignees View on GitHub
question
Dominant language
Python
Stars
66.4k
Forks
4.8k
Avg merge
2d 21h
Merged PRs (30d)
84

Description

### Question

Should DocLang XML be expected to round-trip a `DoclingDocument` losslessly, or is it intentionally a semantic/readability projection?

Using `docling==2.117.0` and `docling-core==2.87.1`, I compared a document before and after this generic round trip:

```python
xml = document.export_to_doclang()
restored = DocLangDocDeserializer().deserialize_str(xml)

before = document.export_to_dict(coord_precision=None)
after = restored.export_to_dict(coord_precision=None)
```

The restored document was usable, but it was not structurally identical. I observed differences in several field classes:

- origin/document metadata
- page dimensions and exact coordinate values
- some table-cell metadata/location detail
- picture image references or payloads

I found the advanced `DocLangParams` options, including `add_table_cell_location`, `xsize`/`ysize`, and `image_mode`, and also found `save_as_doclang_archive(..., artifacts_dir=..., validate=...)`. It is not clear whether some parameter combination is intended to preserve the complete `DoclingDocument`, or whether these formats deliberately retain only the DocLang information model.

Could you clarify:

1. Is `DoclingDocument -> DocLang -> DoclingDocument` intended to be lossless?
2. If yes, which serializer/deserializer parameters preserve full metadata, original page geometry/precision, table-cell detail, and images?
3. Does the `.dclx` archive improve structural fidelity, or does it only package referenced artifacts?
4. If exact interchange/archival fidelity is required, is Docling JSON the recommended canonical format while DocLang is primarily a model-facing/semantic format?

A short note in the DocLang documentation about the fidelity guarantee and recommended configuration would also be very helpful.

Contributor guide

Open the contributing guide

Research direction

Start with the export_to_doclang and DocLangDocDeserializer APIs, then inspect DocLangParams and save_as_doclang_archive, including their existing documentation. Compare the documented fidelity of the listed options and archive behavior with the observed fields. Done means documenting the round-trip guarantee, relevant configuration, archive role, and recommended canonical format.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.