Citation Data Modeling in DoclingDocument#

Docling has no dedicated citation schema with structured bibliographic fields (author, title, year, DOI, etc.). Instead, bibliography entries are stored as plain-text items carrying the DocItemLabel.REFERENCE label — a label introduced specifically for markup-based formats such as HTML and Word 1.

Representation: TextItem with REFERENCE label#

A bibliographic entry is a TextItem whose label is DocItemLabel.REFERENCE. TextItem provides two string fields — orig (untreated text) and text (sanitized text) — but no structured subfields for citation metadata 2. The full reference text is stored as a single opaque string.

Items are added via the standard add_text() method:

doc.add_text(label=DocItemLabel.REFERENCE, text="Smith et al., 2023. ...")

add_text() allocates a JSON Pointer self_ref (#/texts/{index}) and appends the item to the document's flat texts list 3.

Linking: Generic JSON-Pointer References via RefItem#

Cross-references in DoclingDocument are expressed as RefItem objects, each holding a $ref field containing a JSON Pointer string (e.g. #/texts/5) validated against _JSON_POINTER_REGEX. This is the same mechanism used for all inter-item links — captions, footnotes, tree parent/child edges — not a citation-specific mechanism.

RefItem.resolve(doc) dereferences the pointer back to the live object by splitting the path and indexing into the corresponding document collection (e.g. doc.texts[5]).

FloatingItem (tables, pictures) carries a references: list[RefItem] field alongside captions and footnotes. This field is the intended attach-point for linking a figure or table to the bibliography entries that cite it, but it accepts any RefItem pointer — no type-constraint restricts it to REFERENCE-labeled text 4.

FineRef: Span-level Precision#

FineRef extends RefItem with an optional range: tuple[int, int] that captures a character span (start_inclusive, end_exclusive) within the referenced item. As of the current codebase, FineRef is used for comments (not citations) to mark which portion of a target item a comment applies to 5. The mechanism is structurally capable of associating an in-text marker span with a bibliography entry, but this is not wired up in existing converters.

Implications for Downstream Use#

Downstream code that needs structured citation data (e.g. RAG pipelines, bibliometric analysis) must resolve REFERENCE-labeled items by iterating doc.texts, filtering by label, and parsing the raw string content itself.

Key Source Files#