Custom tags must be role-mapped

PDF/UA check CUSTOM_TAG_MAPPING · Structure & other · severity High · PDF/UA 8.2.4 Structure types

↩ Back to the rules index · WCAG cross-reference

Why it matters#

Custom tags (like 'MyParagraph') must map to standard tags (like 'P') so screen readers understand them. Without mapping, custom tags are treated as unknown content and may be skipped.

What you will see#

The document uses non-standard tag names that are not mapped to standard structure types.

How to fix#

Add an entry to the RoleMap dictionary in the structure tree root mapping each custom tag to a standard structure type (e.g. MyParagraph to P). In Acrobat: Tags panel options menu > Edit Role Map.

Step-by-step guide#

1. List the unmapped custom tag types from the EQChecker report (e.g. MyParagraph).
2. Open the role map editor: Accessibility tags panel > Options menu > Edit Role Map.
3. Add an entry per custom type mapping it to the closest standard structure type (MyParagraph to P, Chapter to Sect or H1, and so on). Chains through other custom types are legal as long as they terminate at a standard type - EQChecker follows transitive mappings.
4. If a custom type carries no semantics of its own, map it to NonStruct (ISO 14289-2 8.2.5.10); its descendants keep their meaning while the wrapper is treated as neutral.
5. Remember that mapped elements inherit the target type's obligations - containment rules per ISO/TS 32005 and any 8.2.5 clause for that type (e.g. mapping to Caption incurs Caption placement rules) - so review the affected elements after mapping.
6. For namespace-scoped mapping (RoleMapNS, PDF 2.0), Acrobat only edits the classic RoleMap dictionary; when the mapping must live in a namespace role map, regenerate the PDF from the source application with an export pipeline that writes the correct namespace role mapping.
7. Alternative: retag the elements directly with standard types via the Tags panel or the Reading Order tool and drop the custom types entirely.

Verify: Re-run the EQChecker scan: CUSTOM_TAG_MAPPING should pass with every custom type resolving, directly or transitively, to a standard type.

Note: ISO 14289-2 8.2.4 requires all structure elements to belong to, or be role-mapped into, the PDF 1.7, PDF 2.0, or MathML namespace. Elements with no explicit namespace must resolve to a unique PDF 1.7 type, and Note is not a permitted target despite being a PDF 1.7 type (8.2.4 NOTE 2). Mapping to a semantically wrong type just trades this error for containment or usage errors.

Fixing it in your authoring tool#

WCAG success criteria#

1.3.1 Info and Relationships — Level A#

Structure and relationships conveyed visually (headings, lists, tables, labels, groups) must also be available programmatically.

Understanding 1.3.1

Standards#

This check contributes to the following standards:

PDF/UA WCAG A EN 301 549