[wittjeff]

Closes #4741. Addresses the reading side of #1826 (XMP metadata): the XMP packet is read on the docling-parse backend and /Info on the pypdfium2 backend, standard schemas only; custom namespaces, nested xmpMM structures, and metadata editing stay out of scope.

Problem

A PDF's catalog /Lang entry and its document properties (/Info dictionary, XMP packet) never reach the DoclingDocument. docling-parse exposes them in its document annotations (language, meta_xml), but the pipeline reads those only for the outline, and PdfDocumentBackend has no hook for document-level metadata.

Change

• PdfDocumentBackend.get_document_metadata() with an empty default, implemented for both PDF backends. pypdfium2 reads /Lang (FPDFCatalog_GetLanguage) and /Info; docling-parse reads /Lang and the XMP packet. /Info keys are mapped to the XMP names ISO 32000-2 Table 349 pairs them with (Title -> dc:title, Producer -> pdf:Producer, ...), and PDF date strings become ISO 8601, so both backends report one vocabulary.
• PdfPipelineOptions.attach_document_metadata (CLI --document-metadata). When on, the pipeline fetches the metadata while the backend is open and records it on DoclingDocument.body.meta at assembly, the document-level meta slot per docling-core#544:
  • body.meta.language = LanguageMetaField(code=<primary subtag>, created_by="pdf:/Lang"), so a declared language is distinguishable from a detected one;
  • pdf__lang custom field with the full BCP 47 tag (en-US), because HumanLanguageLabel accepts primary subtags only (docling-core#868);
  • one namespaced custom field per property: dc__title, dc__creator, pdf__producer, xmp__create_date, pdfuaid__part.
• New docling/utils/pdf_metadata.py follows the pdf_outline.py pattern: lazy pypdfium2 import so the service_client chain stays importable on docling-slim.

Why opt-in

docling-core's Markdown and HTML serializers still render body meta fields as content (docling-core#745): with the field set, export_to_markdown() appends confidence=None created_by='pdf:/Lang' code=<HumanLanguageLabel.EN: 'en'> as a paragraph. The option stays off by default until that fix is released and docling bumps its docling-core floor; the JSON export is already correct.

Tests

• tests/test_pdf_document_metadata.py (core lane): XMP flattening (rdf:Alt x-default, rdf:Seq join, attribute properties, unknown namespaces skipped, malformed packet), PDF date conversion, both backends on the new fixture tests/data/pdf/document_metadata.pdf (built with pypdf: /Lang, /Info, XMP) and on a plain PDF, and the attach semantics (existing meta kept, unknown primary subtag keeps only pdf__lang, empty metadata leaves body.meta unset).
• tests/test_pdf_document_metadata_pipeline.py (ml_pdf_model): end-to-end with the option on and off.
• make validate passes; tests/test_heading_hierarchy_bookmarks.py, tests/test_cli.py, tests/test_options.py, tests/test_backend_optional_dependencies.py pass locally.

Docs

docs/usage/advanced_options.md section "PDF document metadata"; the SDK and CLI references in the packaged usage skill.

🤖 Generated with Claude Code

[github-actions]

✅ DCO Check Passed

Thanks @wittjeff, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

🔴 1 of 2 protections blocking · waiting on 👀 reviews

	Protection	Waiting on
🔴	Require two reviewer for test updates	👀 reviews
🟢	Enforce conventional commit	—

🔴 Require two reviewer for test updates

Waiting for

• #approved-reviews-by >= 2

This rule is failing.

When test data is updated, we require two reviewers

• #approved-reviews-by >= 2

---

Show 1 satisfied protection

🟢 Enforce conventional commit

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[github-actions]

AI triage (advisory)

Checked commit fe043a5d57. The analysis read the diff only. It did not run code from this pull request.

The PR adds opt-in PDF document metadata extraction (attach_document_metadata) to both PDF backends, mapping /Lang, /Info, and XMP packet properties to DoclingDocument.body.meta, with a new docling/utils/pdf_metadata.py utility, a CLI flag --document-metadata, and focused unit and pipeline tests.

CI safety: no concern found. A maintainer must still approve CI.

2 related pull request(s) in the same code

PR	State	Signal	Assessment
#4654	open	changes the same code	related: PR 4654 adds OCR-based broken-text-layer replacement and touches pipeline_options.py, standard_pdf_pipeline.py, cli/main.py, and the agent skill references, but it solves a different problem and shares no overlapping logic with this PR's metadata extraction.
#4897	open	changes the same code	related: PR 4897 registers a new Nemotron VLM preset and adds --trust-remote-code; it touches cli/main.py and pipeline_options.py in different sections and solves a completely different problem.

_{The ai:* labels are advisory. They do not approve CI and they do not add tests:full. A new push runs this check again.}

[github-actions]

AI first review (advisory): no blocker found

This review covers the full diff at 32245ecccc. It read the code and did not run it.

The change adds opt-in PDF catalog language and document property extraction for both PDFium and docling-parse backends. Check that the custom property names on DoclingDocument.body.meta match downstream serializer expectations.

_{A maintainer makes the merge decision. This review never approves the pull request.}

[wittjeff]

The docling-core side that gates the default is now open: docling-project/docling-core#869 (Markdown and plain text stop rendering meta.language as prose; HTML emits <html lang> and per-element lang). Once that is released and docling's docling-core floor is bumped, attach_document_metadata can default to on in a follow-up.

[codecov]

Codecov Report

❌ Patch coverage is 92.85714% with 12 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/utils/pdf_metadata.py	93.91%	5 Missing and 4 partials ⚠️
docling/backend/pypdfium2_backend.py	60.00%	1 Missing and 1 partial ⚠️
docling/backend/pdf_backend.py	66.66%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[github-actions]

AI first review (advisory): blocker found

This review covers the full diff at 13cd6768a8. It read the code and did not run it.

An XMP packet that declares an entity or DOCTYPE makes the whole conversion fail when attach_document_metadata is on. The new extractor catches only ParseError. Check this error path first.

_{A maintainer makes the merge decision. This review never approves the pull request.}

[github-actions]

blocker: Hostile XMP packet fails the whole conversion

Trigger: the option is on, the backend is docling-parse, and the PDF has an XMP packet with an <!ENTITY ...> declaration, as in a billion-laughs payload. defusedxml forbids entities by default (forbid_entities=True). It raises EntitiesForbidden. DTDForbidden and ExternalReferenceForbidden exist too. All three derive from DefusedXmlException, which is a ValueError (defusedxml/common.py:18). They are not ElementTree.ParseError. The except ElementTree.ParseError block does not catch them.

Result: the error leaves get_document_metadata() and _build_document(). docling/pipeline/base_pipeline.py:110 catches it and sets ConversionStatus.FAILURE. The PDF's text and layout are lost because of a metadata property. The docstring says an unparsable packet yields no properties, and this case breaks that rule. Metadata is optional, and the input is untrusted PDF content.

Fix: also catch DefusedXmlException (from defusedxml.common) in parse_xmp_properties, log it, and return {}. Add a test with an XMP packet that has an entity declaration. The existing malformed-packet test covers only ParseError.