Skip to content

PDF/A and PDF/UA: XMP from /Info, Print flag, link descriptions, struct attributes, PDF/UA-1 - #53

Open
serpentblade wants to merge 7 commits into
dskripchenko:mainfrom
serpentblade:fix/pdfa-conformance
Open

serpentblade wants to merge 7 commits into
dskripchenko:mainfrom
serpentblade:fix/pdfa-conformance

Conversation

@serpentblade

@serpentblade serpentblade commented Nov 2, 2026 •

Copy link
Copy Markdown
Contributor

PDF/A fixes and PDF/UA-1 support, found by validating real documents with veraPDF 1.30.3. The first three commits are the original PDF/A fixes; the next four let a tagged document pass PDF/UA-1. One commit per change.

PDF/A

1. XMP packet built from the /Info values. PDF/A requires every /Info entry to match its XMP property (ISO 19005-1 §6.7.3). The XMP was built from PdfAConfig alone: producer always dskripchenko/php-pdf, dates the render time, no Subject, Keywords or Creator. Any document that set a producer, creator or creation date failed PDF/A-1b, and the XMP changed on every render, even with a fixed creation date.

  • /Info is resolved once and the XMP written from it: dc:title, dc:creator, dc:description, pdf:Keywords, xmp:CreatorTool, pdf:Producer, xmp:CreateDate, xmp:ModifyDate.
  • The config's title and author still apply when the metadata has none, and now also go into /Info, as PdfXConfig's do.
  • Empty properties are left out instead of written as empty elements.
  • /Info dates are written in UTC. A date in another time zone was written with its local clock time but a +00'00' offset, so hours off.
  • PdfAConfig::xmpMetadata() keeps its signature and gains an optional $info array.

2. Print flag on links and form widgets. PDF/A requires /F with Print set on every annotation except a Popup (19005-1 §6.5.3, 19005-2 §6.3.2). Links and widgets had no /F, so any PDF/A document with a hyperlink or form field failed on 1b, 2b and 2u. All five link kinds and every widget now carry /F 4, as the signature widget already did.

3. Conformance references. pdfa-1b-annotated and pdfa-2b-annotated have external and internal links and every standard /Info entry. Both fail veraPDF without the fixes and pass with them, and verapdf.sh now checks them.

Markup annotations (text notes, highlights and so on) also lack /F, but they have no appearance streams either, which PDF/A requires as well (6.3.3), so I left them for a separate change.

PDF/UA

We tag documents through the low-level writer (addStructElement, beginStructContainer, marked content, artifacts), and the structure tree it builds already passes veraPDF's PDF/UA-1 structure rules. Four things were missing for a document to pass as a whole.

4. A description on links. PDF/UA requires /Contents on every link annotation (ISO 14289-1 §7.18.5). The five add*Link() methods take an optional $contents, written as a text string. Without it nothing changes.

5. Attribute objects on struct elements. A TH needs /Scope (or /Headers with IDs) so a reader knows which cells it heads (§7.5). addStructElement() and beginStructContainer() take an optional $attributes array, e.g. ['O' => 'Table', 'Scope' => 'Column'] → /A << /O /Table /Scope /Column >>. Strings are written as names and numbers as numbers. A missing owner, or a value that isn't a plain name, throws, so input can't break out of the dictionary.

6. Link elements in reading order. Every link's struct element went at the end of the root, holding only the annotation, so a screen reader met all the links after the document, detached from their text. Document::placeLinkInStructure($page) puts the page's most recent link where the call is made. Inside a Link container opened around the link text, the annotation joins that element, so it holds both the text and the OBJR (§7.18.5). Elsewhere a Link element goes under the innermost open container. Links that are not placed keep the old behaviour.

7. Document::enablePdfUa(). veraPDF failed every tagged document on 7.1-8, because php-pdf wrote XMP only for PDF/A and PDF/X. This method:

  • enables Tagged PDF;
  • writes XMP with pdfuaid:part 1 from the same /Info values as Add ExistingFormFiller: read, fill, flatten and stamp existing PDF forms #1. When PDF/A is on too, it adds pdfuaid to the PDF/A packet, with the extension schema PDF/A needs for a schema it doesn't predefine (19005-2 §6.6.2.3.2);
  • sets DisplayDocTitle, merged into any other viewer preferences;
  • gives pages with annotations /Tabs /S (§7.18.3) unless a tab order was set;
  • throws when the document has no title. Combining it with PDF/X also throws, since both write their own XMP packet.

The XMP builder moves from PdfAConfig into an internal XmpPacket so both use it. A PDF/A-only packet is byte-identical to before.

New references: pdfua-1 is a tagged document built on the low-level writer: headings, a paragraph whose link sits in its Link element with the text, a table with header scope, and artifacts. pdfa-2u-ua1 is the same document as PDF/A-2u too. verapdf.sh now accepts name:flavour, checks pdfua-1 against PDF/UA-1 and pdfa-2u-ua1 against both 2u and UA-1, and all pass. docs/en/CONFORMANCE.md lists them and says what veraPDF can't judge: alt text quality and reading order still need a person.

Not included: the high-level Engine's tagging doesn't pass PDF/UA yet. List items hold their content directly rather than in Lbl/LBody, header cells are TD, and links aren't placed. These changes make all of that possible, but I kept the Engine out of this PR.

addStructElement(), beginStructContainer() and endStructContainer() are marked @internal, yet they're the only way to tag content from outside the Engine, and we rely on them. Would you consider making them public?

Tests added for each change; full suite and phpstan pass. Every reference in scripts/conformance passes veraPDF 1.30.3.

🤖 Generated with Claude Code

serpentblade and others added 7 commits November 1, 2026 16:26
PDF/A requires every /Info entry to be equivalent to its XMP property
(ISO 19005-1 §6.7.3, ISO 19005-2 §6.6.2.3). The XMP packet was built
from PdfAConfig alone: its producer was always dskripchenko/php-pdf,
its dates the time of the render, and Subject, Keywords and Creator
were missing. A document that set metadata() — any producer, creator or
creation date — failed veraPDF on PDF/A-1b (6.7.3-1, -6, -7), and the
packet changed on every render, so the output was not reproducible
even with a fixed creation date.

The /Info values are now resolved once and the XMP packet is written
from them: dc:title, dc:creator, dc:description, pdf:Keywords,
xmp:CreatorTool, pdf:Producer, xmp:CreateDate and xmp:ModifyDate. The
config's title and author still apply when the metadata has none, and
are written to /Info as well, as PdfXConfig's are. Empty properties are
left out instead of written as empty elements.

/Info dates are written in UTC. A creation date in another time zone was
written with its local clock time but a +00'00' offset — hours off, and
a different instant from the XMP date.

PdfAConfig::xmpMetadata() keeps its signature and gains an optional
$info array.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Link annotations and form-field widgets were written without /F, so
their Print flag was off. PDF/A requires /F with Print set on every
annotation but a Popup (ISO 19005-1 §6.5.3, ISO 19005-2 §6.3.2), so a
PDF/A document with a hyperlink or a form field failed veraPDF
(6.5.3-2 on 1b, 6.3.2-1 on 2b and 2u). Without the flag a printed form
also leaves its fields blank.

All five kinds of link and every widget (text, checkbox, push, submit
and reset buttons, combo and list boxes, radio buttons) now carry
/F 4, as the signature widget already did.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
pdfa-1b-annotated and pdfa-2b-annotated have an external and an
internal link and set every standard /Info entry (Title, Author,
Subject, Keywords, Creator, Producer). The existing references set
neither, which is how the two previous fixes went unnoticed: both new
files fail veraPDF without them and pass with them. verapdf.sh checks
them with the others.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
PDF/UA requires every link annotation to have a description in its
/Contents entry, which assistive technology reads for the link
(ISO 14289-1 §7.18.5; veraPDF 7.18.1-2 and 7.18.5-2). There was no way
to set one, so no document with a link could be PDF/UA.

addExternalLink, addInternalLink, addNamedActionLink, addJavaScriptLink
and addLaunchLink take an optional $contents, written as a text string
(UTF-16BE when it isn't plain ASCII). Without it the annotation is
unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A struct element had no way to carry an attribute object (/A, ISO
32000-1 §14.8.5). PDF/UA needs one on table header cells: a TH needs
/Scope, or /Headers with IDs, so a reader can tell which cells it heads
(ISO 14289-1 §7.5). ColSpan, RowSpan and the list numbering style
live there too.

addStructElement() and beginStructContainer() take an optional
$attributes array, e.g. ['O' => 'Table', 'Scope' => 'Column'], written
as /A << /O /Table /Scope /Column >>. String values are names, numbers
are numbers. An object without an owner (O), or a name that isn't a
plain PDF name, throws, so a value can't break out of the dictionary.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every link's struct element was added at the end of the root, after all
the content, with only the annotation in it. A screen reader met the
links after the document, detached from their text, and a Link could
not hold the text it labels, which PDF/UA asks for (ISO 14289-1
§7.18.5: the link text and the annotation in one Link element).

Document::placeLinkInStructure($page) puts the link last added to
$page into the tree where it is called. Inside a Link container opened
around the link's text, the annotation joins that element, whose /K
then lists the text and the OBJR. Elsewhere a Link element is added
under the innermost open container. The annotation's /StructParent and
the ParentTree point at the placed element.

Links that are not placed keep the old behaviour, and the call does
nothing on an untagged document.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A tagged document could not claim PDF/UA. ISO 14289-1 §5 and §7.1 want
the Catalog's XMP metadata with pdfuaid:part, a dc:title and
DisplayDocTitle; php-pdf wrote XMP only for PDF/A and PDF/X, so veraPDF
failed every tagged document on 7.1-8 however well it was tagged.

Document::enablePdfUa() enables Tagged PDF and at render:

- writes an XMP packet with pdfuaid:part 1 from the same /Info values
  PDF/A uses (title, author, subject, keywords, creator, producer,
  dates), or adds pdfuaid to the PDF/A packet when PDF/A is enabled too,
  with the extension schema PDF/A needs for a schema it doesn't predefine
  (ISO 19005-2 §6.6.2.3.2);
- sets DisplayDocTitle, merged into any other viewer preferences;
- gives pages that have annotations /Tabs /S (§7.18.3) unless a tab
  order was set;
- throws without a document title. PDF/UA with PDF/X throws too, as both
  write their own packet.

The XMP builder moves out of PdfAConfig into an internal XmpPacket, so
both share it; a PDF/A-only packet is byte for byte as before.

New conformance references: pdfua-1, a tagged document built on the
low-level writer (headings, a paragraph whose link sits in its Link
element with the text, a table with header scope, artifacts), and
pdfa-2u-ua1, the same as PDF/A-2u too. verapdf.sh checks the first
against PDF/UA-1 and the second against both PDF/A-2u and PDF/UA-1;
all pass with veraPDF 1.30.3.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@serpentblade serpentblade changed the title fix(pdfa): XMP from /Info, Print flag on links and widgets PDF/A and PDF/UA: XMP from /Info, Print flag, link descriptions, struct attributes, PDF/UA-1 Nov 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant