Custom tags, RoleMap and namespaces

Exporters may create tags named after source styles. PDF 1.7 uses RoleMap to associate custom structure types with standard types. ChapterHeading might map to H2 if that is the correct level in the document.

The mapping must match the content. Mapping every unknown tag to P may remove a technical error while stripping meaning from headings, lists and tables.

Sources: [1]

Suppose the source uses a style called “ReportSubheading” and export creates a tag with the same name. The name may make sense to editors, but the PDF reader needs a standardised meaning. If it introduces a subsection beneath H2, its intended role may be H3.

Check several things: is it associated with the right text, mapped to the correct standard type, positioned at the right heading level and followed by the right content? Correct role mapping cannot compensate for incorrect content association or a heading placed after its section.

Watch for reused style names. If “LargeText” means both headings and prominent monetary amounts, one mapping cannot correctly describe both. Repair the source semantics or individual tags more carefully. Do not change every occurrence without examining its content.

PDF 2.0 can identify namespaces for structure. This distinguishes standard structure types and other structural vocabularies. When a file contains older tag names, assess the namespace, role mapping and permitted relationships together. Comparing the tag name alone is insufficient.

Think of a namespace as identifying the technical vocabulary in which a term is used. Identically written names do not necessarily derive their meaning from the same rules. A PDF 2.0 review therefore needs more than the tag-name column in a simple export list.

Editors do not need to hand-write low-level syntax. Tools should create and preserve structure appropriate to the chosen target. When validation fails, however, the reported type, mapping and namespace need to be traceable to an actual file object. Use the applicable standard and tool documentation for the concrete repair.

Sources: [2], [3]

Merging PDFs from different systems can bring together custom tags with identical names but different intended meanings. Recheck structure and mapping after the merge, rather than relying only on checks of the individual inputs.

A useful test combines two samples where the same custom name represents different heading levels. Compare the merged heading list with both originals’ intended outlines. If every “Chapter” becomes H1 although one source used it for subsections, merging changed meaning despite identical-looking pages.