Image Reference Handling#

ImageRef is the Pydantic model used throughout DoclingDocument to represent an image attached to a PictureItem or PageItem. It is defined in docling_core/types/doc/common/reference.py and carries four fields: mimetype, dpi, size (Size), and uri (Union[AnyUrl, Path]).

URI Schemes#

The uri field accepts three practical forms 1:

Scheme handling is not enforced by a Pydantic validator on the field itself — it is enforced at runtime when .pil_image is accessed 2.

pil_image Property — Scheme Dispatch#

pil_image returns a PIL.Image.Image (or None) and implements all scheme-specific logic:

• file:// URI: Opens the file only if settings.allow_image_file_uri is True; otherwise raises ValueError. After the guard, calls _ensure_within_size_limit() before opening 3.
• data: URI: Splits on ,, base64-decodes the payload, then checks the decoded byte length against settings.max_image_decoded_size before opening with PIL 4.
• Bare Path: Calls _ensure_within_size_limit() then opens with PIL 5.
• HTTP/HTTPS (and any other remote scheme): Explicitly not fetched. A source comment reads: "HTTP(S) and other remote schemes are intentionally not fetched. If remote fetch is enabled, it must use host allowlists and block private, link-local, and cloud-metadata addresses (SSRF controls)." 6

Construction Helper#

ImageRef.from_pil(image, dpi) is the canonical factory method for building an ImageRef from a PIL.Image. It encodes the image to PNG using cv2 (if installed) or PIL, produces a data:image/png;base64,… URI, and caches the PIL object in _pil to avoid re-decoding.

Security Settings#

Runtime behaviour is controlled by CoreSettings in docling_core/utils/settings.py, configurable via environment variables with the prefix DOCLINGCORE_:

The size guard is implemented in _ensure_within_size_limit(path, *, max_size, label) in docling_core/types/doc/utils.py: it calls path.stat().st_size and raises ValueError if the file exceeds max_size.

MIME Type Validation#

The mimetype field is validated by validate_mimetype, which checks the value against mimetypes.types_map.values() and rejects unknown MIME types.

Key Source Files#