docling-project / docling-project/docling
Should DocLang XML round-trip a DoclingDocument losslessly?
- 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
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