Document Metadata#

Document metadata in Docling is structured through a hierarchy of Pydantic models rooted at BaseMeta, defined in docling_core/types/doc/document.py. Every document node carries an optional meta field typed to the appropriate subclass; all fields default to None.

Class Hierarchy#

_ExtraAllowingModel
└── BaseMeta
    └── FloatingMeta
        └── PictureMeta

Document items reference their metadata type directly:

• NodeItem.meta: Optional[BaseMeta]
• FloatingItem.meta: Optional[FloatingMeta]
• PictureItem.meta: Optional[PictureMeta]

Standard Fields on BaseMeta#

All standard fields inherit from BasePrediction, which adds confidence (0–1) and created_by provenance 1.

BaseMeta.has_content() 7 returns True if any field holds meaningful (non-None) data, recursively checking nested models, dicts, and lists.

The canonical enum of all standard field names is MetaFieldName, kept in sync with the BaseMeta class hierarchy.

Custom Metadata Extension (Namespace Convention)#

All meta classes inherit from _ExtraAllowingModel, a Pydantic BaseModel with extra="allow". Extra fields are the extension point for custom metadata, but they must follow a strict naming convention enforced at validation time.

Format: namespace__field_name — two underscores (__) separate the namespace from the field name 8.

Example: my_corp__max_size, acme__doc_version

Rules enforced by _validate_field_names:

• Custom (extra) fields must match namespace__field_name — both parts non-empty.
• Standard (declared) fields must not contain __.
• The same check runs in __setattr__ when fields are set after construction.

Utility helpers are in MetaUtils:

• MetaUtils.create_meta_field_name(namespace=..., name=...) — returns the correctly formatted key.
• _ExtraAllowingModel.set_custom_field(namespace, name, value) — calls create_meta_field_name and sets the attribute, returning the key.
• _ExtraAllowingModel.get_custom_part() — returns only the extra (non-declared) fields as a dict.

The reserved namespace "docling_legacy" 9 is used internally when migrating deprecated annotations fields on PictureItem to the new meta structure 10.

Key Source Files#