docling-project / docling-project/docling-core
Feature: AttachmentItem schema + serializer support for embedded PDF files
- Dominant language
- HTML
- Stars
- 282
- Forks
- 214
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 21
Description
## Context
Docling is adding PDF embedded file / attachment processing.
We need a first-class schema item for document attachments so they can appear in both JSON and markdown exports.
## Proposed schema change
Add a new DocItem subclass `AttachmentItem` with fields:
- `name: str` — attachment filename
- `mime_type: Optional[str]`
- `size: Optional[int]` — attachment payload size in bytes
- `target: Optional[str]` — relative path to the converted attachment (e.g. `.md`), or `None` if not converted
- `status: Literal["converted", "failed", "unsupported", "depth_limited"]`
- Optional `prov: ProvenanceItem` with page/bbox when anchored by a FileAttachment annotation
## Proposed serializer behavior
- Markdown: items with `prov` render inline as `[name](target)`; items without `prov` are collected into a trailing `## Attachments` section. Non-`converted` items render as plain text with a reason, no link.
- JSON: natural schema inclusion via `save_as_json`.
- HTML / doctags: graceful minimal handling (link when target is present).
## Backward compatibility
New optional item type; existing documents unaffected.
Implementation will be opened as a PR from fork: yonikremer/docling-core feat/attachments.
Contributor guide
Research direction
Start by locating the existing DocItem schema and serializer dispatch, then trace save_as_json and the Markdown, HTML, and doctags export paths. Done means AttachmentItem is included in the schema and JSON output, with the specified inline or trailing Markdown behavior and minimal link handling for HTML and doctags.
Written by the indexing model from the issue text.
Assessment
- Domain
- backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 52/100