DocLang Format#

DocLang is an XML-based semantic markup format designed for LLM/VLM compatibility. It is currently at version 0.7, uses the namespace https://www.doclang.ai/ns/v0 1, and supports bidirectional conversion — serving as both an input and output format in Docling alongside Markdown, JSON, HTML, and DocTags.

Its XML vocabulary is purpose-built to encode the full semantics of a DoclingDocument: spatial location data, nested document structure, inline formatting, tables, lists, key-value regions, and cross-page threading for split elements.

Token Vocabulary#

The complete vocabulary is defined in _doclang_utils.py via the DocLangToken enum and organized into categories by DocLangCategory 2:

Bounding boxes are encoded as four sequential <location value="N"/> self-closing tokens (x0, y0, x1, y1) normalized to a default resolution of 512 3 4.

Headings support level attributes (1–6); level 1 is emitted as a bare <heading> tag 5. Lists use class="ordered" or bare <list> for unordered 6. Code blocks map language labels to GitHub Linguist keys. The root element <doclang version="0.7"> optionally carries an xmlns attribute 7.

A minimal valid DocLang document looks like:

<doclang>
  <heading>DocLang Title</heading>
  <text>Hello world</text>
  <table>
    <fcel/><text>H1</text><fcel/><text>H2</text><nl/>
    <fcel/><text>C1</text><fcel/><text>C2</text><nl/>
  </table>
</doclang>

8

Input: Reading DocLang Files#

File extensions: .dclg, .dclg.xml 9
InputFormat enum: InputFormat.XML_DOCLANG 10

The entry point is DocLangDocumentBackend in docling/backend/xml/doclang_backend.py. It reads the file as UTF-8 text and delegates to DocLangDocDeserializer.deserialize_str() from docling-core. The deserializer parses the XML, walks the element tree, and populates a DoclingDocument via the builder API. Threading (<thread thread_id="..."/>) is resolved via a registry to merge cross-page continuations 11.

Usage:

from docling.document_converter import DocumentConverter
from docling.datamodel.base_models import InputFormat

result = DocumentConverter(
    allowed_formats=[InputFormat.XML_DOCLANG]
).convert("my_document.dclg")

12

DocumentConverter.convert_string() is also supported, passing format=InputFormat.XML_DOCLANG 13.

Output: Exporting to DocLang#

OutputFormat enum: OutputFormat.DOCLANG and OutputFormat.DCLX (archive) 14

DoclingDocument exposes three export methods in document.py:

The serializer is DocLangDocSerializer in docling_core/transforms/serializer/doclang.py, configured via DocLangParams. Key parameters include:

• add_location (default True): embed <location> bounding-box tokens
• add_page_break (default True): emit <page_break/> between pages
• add_named_groups (default False): when True, a plain GroupItem is emitted as a <group> element carrying its name and label, so the grouping survives a round trip. When False, the group is transparent and only its children are emitted
• pretty_indentation (default 2 spaces): human-readable formatting
• image_mode (default PLACEHOLDER): controls how picture data is embedded
• include_version (default True): add version="0.7" to root tag

Serializer / Deserializer Architecture#

The symmetric implementation lives in docling-core:

The serializer uses specialized sub-serializers for each content type: DocLangTextSerializer, DocLangTableSerializer, DocLangListSerializer, DocLangPictureSerializer, and DocLangKeyValueSerializer 15.

Roundtrip fidelity is tested in tests/test_backend_doclang.py: exporting a DoclingDocument to DocLang XML and re-importing it must produce identical text content, table grids, and item labels 16.

Relation to DocTags#

DocLang is distinct from DocTags, which is the XML-like token format emitted by vision models such as SmolDocling. DocTags uses <loc_N> bounding-box tokens and is loaded via DoclingDocument.load_from_doctags(). DocLang is a richer, standards-compliant XML format with explicit namespace, version, OTSL table encoding, and threading support — targeting both human readability and LLM token-level processing.