DocItemLabel Type System#

DocItemLabel is the primary enum that classifies every content-bearing element in a DoclingDocument. It is defined as a str enum in docling_core/types/doc/labels.py and is the value stored in every DocItem.label field.

DocItemLabel Enum Values#

The full label set 1:

Each label has a canonical RGB color for visualization, accessible via DocItemLabel.get_color(label).

Base Class: DocItem#

DocItem (in docling_core/types/doc/items/node.py) is the Pydantic base for all content elements. It declares the label field as an open DocItemLabel 2:

class DocItem(NodeItem):
    label: DocItemLabel
    prov: list[ProvenanceItem] = []
    ...

Subclasses narrow this field using typing.Literal to enforce a restricted set of valid labels at Pydantic validation time.

Concrete Item Classes and Their Label Constraints#

Each specialized item class pins label to one or more DocItemLabel values via Literal. This makes it impossible to construct, say, a TitleItem with label=DocItemLabel.CODE.

TextItem — multi-label catch-all#

TextItem accepts 14 labels: CAPTION, CHECKBOX_SELECTED, CHECKBOX_UNSELECTED, FOOTNOTE, PAGE_FOOTER, PAGE_HEADER, PARAGRAPH, REFERENCE, TEXT, EMPTY_VALUE, FIELD_KEY, FIELD_HINT, MARKER, and HANDWRITTEN_TEXT. It also carries orig, text, optional formatting, and optional hyperlink fields.

Single-label text subclasses#

All inherit from TextItem and narrow the label to exactly one value 3:

CodeItem#

CodeItem inherits from both FloatingItem and TextItem, pinning label to CODE. It adds code_language: CodeLanguageLabel (see CodeLanguageLabel for the 50+ supported language values).

TableItem — two accepted labels#

TableItem (in docling_core/types/doc/items/table/table.py) accepts either TABLE or DOCUMENT_INDEX, defaulting to TABLE.

PictureItem — two accepted labels#

PictureItem (in docling_core/types/doc/items/picture/picture.py) accepts either PICTURE or CHART (the latter is deprecated), defaulting to PICTURE.

Form and key-value items#

Defined in docling_core/types/doc/items/form.py and key_value.py:

Related Label Enums in labels.py#

DocItemLabel is not the only label enum in labels.py. The file also contains:

• GroupLabel — used by GroupItem container nodes (LIST, ORDERED_LIST, CHAPTER, SECTION, SLIDE, FORM_AREA, etc.). GroupItem uses GroupLabel, not DocItemLabel.
• PictureClassificationLabel — fine-grained classification for pictures (chart types, photographs, barcodes, chemistry structures, etc.), stored in picture metadata rather than in the label field.
• TableCellLabel — COLUMN_HEADER, ROW_HEADER, ROW_SECTION, BODY — applied to individual table cells.
• CodeLanguageLabel — programming language identifier for CodeItem.code_language.
• HumanLanguageLabel — BCP-47 two-letter language tags.

Key Design Pattern#

Subclasses use # type: ignore[assignment] to suppress mypy warnings when narrowing the inherited label type 4. This is the standard pattern throughout the items package — Pydantic enforces the Literal constraint at runtime, and mypy's type-narrowing complaint is suppressed.

Import Path#

from docling_core.types.doc.labels import DocItemLabel

DocItemLabel is also re-exported from docling_core.types.doc 5.