PDF/UA-2 Structure Authoring, Validation, and Repair

HotPDF can build, validate, and atomically repair mixed PDF 1.7 and PDF 2.0 structure semantics while preserving explicit namespace identity and bounded processing cost

Namespace-aware authoring

AddStructureElement assigns the PDF 2.0 standard structure namespace when a PDF/UA-2 role requires it, including the mandatory top-level Document element

AddStructureElementNS creates explicitly namespaced elements and AddStructRoleMapNS adds name or two-item array mappings that may resolve transitively across namespace boundaries

Namespace dictionaries are indirect, registered once by URI, and emitted through StructTreeRoot/Namespaces

Attributes and semantic helpers

Bounded one-pass validation

ValidatePDFUA2Structure returns every retained diagnostic in a THPDFUA2ValidationIssues array and returns False when at least one diagnostic has uisError severity

The validator resolves namespace-aware role maps with cycle detection and checks the top-level document, parent-child hierarchy, parent backlinks, attribute owners and revisions, annotation StructParent, parent-tree and OBJR ownership, associated files, headings, lists, tables, Ruby, Warichu, pronunciation hints, formulas, and MathML

Document checks cover a specific Catalog language, marked status, suspect status, displayed title, XMP title and PDF/UA identification by namespace URI, Unicode private-use characters in human-readable strings, and optional-content configuration names and actions

Annotation checks cover page tab order, structure ownership and roles, descriptions, artifact states, appearance-stream marked-content references, rich-content equivalence, file relationships, and prohibited subtypes

Form checks cover reachable field identity, inherited field properties, widget context and ownership, labels, alternate actions, rich values, choice options, zero-area widgets, multi-widget fields, and the prohibition on XFA

Navigation checks cover structure destinations with SD precedence, outlines, embedded-file descriptions, nested page-label number trees, required page index zero, label styles, and valid label starting numbers

Table validation expands positive row and column spans only within MaxObjects, rejects intersecting cells and irregular row or row-group geometry, resolves Headers within the owning table, detects duplicate, self, and cyclic header references, and accepts implicit associations only when Scope or first-row and first-column placement determines them

List validation recognizes the complete PDF 2.0 ListNumbering set, enforces label semantics, checks ContinuedList and ordered same-level ContinuedFrom references, and rejects continuation cycles or direct real content outside Lbl and LBody

Ruby children must be RB,RT or RB,RP,RT,RP, Warichu children must be WP,WT,WP, pronunciation entries retain their PDF object types, and every pronunciation lexicon must be an indirect embedded PLS Filespec

Indirect-object scanning, traversal depth, role-map depth, expanded table cells, retained issue count, and hostile collection processing are bounded so validation remains predictable for untrusted structure trees

Shared compliance findings

The THPDFComplianceFindings validation overload returns the same diagnostics with a shared profile, severity, stable rule ID, standard clause, logical path, indirect object number, and zero-based page index

The detailed repair overload compares bounded pre-repair and post-repair findings to identify applied, unresolved, rolled-back, or failed repair actions and appends counted repair-family summaries

ComplianceFindingsToJSON preserves deterministic order under the versioned hotpdf.compliance.findings.v1 schema and represents unknown object or page locations as null

Atomic structure repair

RepairPDFUA2Structure runs inside a copy-on-write graph transaction, canonicalizes duplicate or unregistered namespace dictionaries, rewrites structure and role-map namespace references, repairs standard structure namespaces, normalizes structure attribute namespaces and revisions, and repairs deterministic list, table, Ruby, Warichu, pronunciation, alternate-text, language-inheritance, heading-order, and Artifact-tag defects

After mutation the same validator checks the candidate graph, and the default policy rolls back every change when any PDF/UA-2 error remains

• Duplicate namespace URIs collapse to one indirect dictionary only when their namespace-aware role mappings agree
• Valid referenced namespaces can be registered without repeatedly scanning the structure tree
• Standard attribute owners shed invalid namespace entries, while custom owners require an explicit CustomAttributeNamespaceURI when their namespace cannot be inferred
• Negative or fractional element revisions become zero, invalid attribute-array revisions become zero, and orphan revision entries are removed
• Recognizable list numbering is restored, label-bearing lists receive a non-None numbering semantic, valid continuation references receive ContinuedList=true, and a single misplaced caption moves to the first position
• Invalid table spans become one, Scope is removed from data cells, and invalid, cross-table, self, or duplicate Headers entries are removed without inventing replacement associations
• Ruby and Warichu children are reordered only when the exact required multiset already exists
• Wrongly typed pronunciation hints are removed, invalid lexicon references are pruned, and valid embedded lexicon streams receive the PLS MIME subtype
• Missing Alt values use an existing title, expansion text, or same-MCID extracted text before any caller-supplied fallback, and the empty default never invents descriptions
• A valid root or caller-supplied BCP-47 language can become the Catalog language so redundant or invalid descendant entries inherit safely
• First-heading and skipped-level defects are closed in document order, with optional independent heading starts inside DocumentFragment
• Artifact structure roles are aligned with their marked-content tags in producer page content and loaded content streams
• Ambiguous table geometry, missing semantic children, conflicting identifiers, and unresolved reading semantics remain errors and trigger the default rollback
• MaxObjects and MaxRepairs fail closed before untrusted graphs can force unbounded work

Validation policy

Start with THPDFUA2ValidationOptions.Default and change only the workflow-specific decisions

THPDFUA2HeadingPolicy selects heading treatment, THPDFUA2IssueSeverity distinguishes warnings from errors, and each THPDFUA2ValidationIssue carries a stable code, structure path, severity, and message

• HeadingPolicy can ignore skipped levels, retain them as warnings, or require sequential levels
• AllowDocumentFragmentHeadingStarts resets heading context inside DocumentFragment
• CheckDocumentSemantics enables Catalog, metadata, optional-content, and embedded-file checks
• CheckHumanReadableStrings rejects Unicode private-use characters in user-facing document strings
• CheckAnnotationSemantics enables annotation ownership, role, appearance, description, and flag checks
• CheckFormSemantics enables AcroForm, field, widget, value, label, action, and option checks
• CheckNavigationSemantics enables structure-destination, outline, and page-label checks
• RequireListLabels requires one Lbl for numbered list items
• RequireExplicitTableHeaderAssociations reports data cells that rely only on header scope inference
• CheckListSemantics enables complete PDF 2.0 numbering, continuation, caption, label, body, and content-placement checks
• CheckTableSemantics enables bounded grid, span, row-group, header-scope, and table-local association checks
• CheckRubyWarichuSequences enables exact direct-child sequence checks for East Asian inline structures
• CheckPronunciationHints enables structure hint and embedded PLS lexicon checks
• RequireStructureAssociatedFiles requires every catalog associated file to be reachable from a structure element
• RequireFormulaTextAlternative requires formula text alternatives unless associated MathML is present
• MaxObjects bounds the indirect-object scan before traversal begins
• MaxIssues bounds retained diagnostics without hiding the final success or failure result

Recommended workflow

1. Enable PDFUACompliance, select PDFUAPart = 2, and set Lang before BeginDoc
2. Create one top-level Document and build semantic children with standard or explicitly namespaced roles
3. Register annotations and associated files through their structure helpers, write pronunciation hints with SetStructurePronunciation, and add PLS files in desired lookup order with AddPronunciationLexicon
4. Run ValidatePDFUA2Structure before EndDoc when the application needs all diagnostics at once, call RepairPDFUA2Structure for deterministic namespace, structure, and accessibility repairs, and select the shared finding overload when CI requires standard JSON
5. Resolve every error before output because EndDoc also enforces the strict default policy for PDF/UA-2 documents

See also: Automatic layout structure, THPDFUA2ValidationOptions, ValidatePDFUA2Structure, RepairPDFUA2Structure, ComplianceFindingsToJSON, SetStructurePronunciation, AddPronunciationLexicon, AddStructureElement, BeginTaggedContentForStructure, AppendStructureMarkedContent