docling-project / docling-project/docling-core

Feature: AttachmentItem schema + serializer support for embedded PDF files

Open
#712 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.