docling-project / docling-project/docling

Support .cv resume files (PDF/A-3u with embedded canonical Markdown) as a first-class input format

Open
#3,567 2 comments 0 reactions 2 assignees Claimed by @ilanoh View on GitHub
Dominant language
Python
Stars
66.4k
Forks
4.8k
Avg merge
2d 21h
Merged PRs (30d)
84

Description

### Problem

`.cv` is an open resume file format: a valid PDF/A-3u that embeds, as PDF Associated Files (`/AF`, ISO 32000-2 §14.13), a clean canonical `resume.md` plus `resume.html`, an optional `resume.json`, and an optional `embeddings.cbor`. XMP metadata in a `cv:` namespace records `cv:version` and `cv:primaryPayload`. The media type is `application/vnd.cv+pdf`.

Today Docling treats these as ordinary PDFs and runs layout/OCR over the rendered page, discarding the lossless source that is already inside the file.

Spec and tooling: https://cvfile.org/spec/ and https://github.com/cvfile/cv

### Proposed solution

Detect `.cv` files and convert directly from the embedded canonical Markdown (lossless and instant) instead of parsing the visual PDF. Kept inside the existing seams:

- a new `InputFormat.CV` plus `FormatToExtensions` / `FormatToMimeType` entries in `docling/datamodel/base_models.py`;
- a content-sniff branch in `_DocumentConversionInput._guess_format` (`docling/datamodel/document.py`). A `.cv` shares the `pdf` extension and `%PDF` magic, so detection is by the `cv:` XMP namespace or the `/AF` markdown payload. This is the same disambiguation pattern already used for `application/zip` to DOCX/XLSX/PPTX;
- a `CvDocumentBackend(DeclarativeDocumentBackend)` in `docling/backend/cv_backend.py` that unwraps `resume.md` and delegates to the existing `MarkdownDocumentBackend`, wired via a `CvFormatOption(SimplePipeline + CvDocumentBackend)`.

No change to `StandardPdfPipeline`; opt-in via `allowed_formats`.

### Alternatives considered

- A short-circuit hook inside the PDF path. Rejected: it changes behavior for all PDFs and touches the ML hot path.
- An external wrapper package. Possible, but Docling has no third-party format plugin API, so in-tree is the only route to a supported format. Happy to do either.

### Additional context

The format is an open spec built on ISO 32000-2 Associated Files; detection and unwrap is about 200 lines (reference sniffer published as `cvfile-cv-detector` on PyPI, npm and Go). Detection is content-based and fully backward compatible: anything without the `cv:` or `/AF` markers still resolves to `InputFormat.PDF`.

I am ready to implement the backend, tests, and a `.cv` fixture, and to maintain it. Would you accept this in core, or would you prefer an external package? Happy to align on the approach before opening a PR.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.