docling-project / docling-project/docling
Support .cv resume files (PDF/A-3u with embedded canonical Markdown) as a first-class input format
- 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
Assessment
This issue has not been assessed yet.