Checkpoint 02: Role Mapping

When PDFs use custom or non-standard tag names, those tags must correctly map to standard PDF roles so that assistive technologies can interpret them properly.

What This Means

PDF/UA defines a set of standard structure elements (tags) like P (paragraph), H1-H6 (headings), Table, Link, and Figure. These standard tags have well-defined meanings that screen readers understand.

Sometimes PDFs use non-standard tags. This happens when:

• Authoring tools create custom tags (like "Heading" instead of "H1")
• Documents are converted from other formats with proprietary structures
• Designers use custom tags for styling purposes

When non-standard tags are used, the PDF must include a Role Map that tells assistive technology how to interpret those custom tags. The role map says "treat my custom 'Title' tag as an H1" or "interpret 'BodyText' as a P."

Why It Matters

Without correct role mapping:

• Screen readers cannot identify content types, leading to flat, unstructured announcements
• Navigation features fail because headings, lists, and tables are not recognized
• Users cannot use shortcuts like jumping to the next heading or table
• Document structure becomes invisible to assistive technology users

Role mapping is essential for interoperability. It ensures that regardless of what internal tag names a PDF uses, assistive technologies can still understand the document structure.

Common Violations

The Matterhorn Protocol defines four failure conditions for role mapping.

02-001: Non-standard Role Does Not Map to a Standard Role (Machine Testable)

What's Wrong: A custom tag is used in the document, but no role mapping exists to connect it to a standard PDF structure element. Assistive technology will not know how to interpret this content.

How to Identify:

• PDF/UA validators will flag unmapped non-standard tags
• Check the role map in the document structure
• Look for custom tag names in the Tags panel that do not appear in the role map

How to Fix:

Option 1: Add a Role Mapping

1. Open Tools > Accessibility > Reading Order
2. In most cases, Adobe Acrobat will prompt you to fix role mappings
3. Alternatively, use the Preflight tool with a PDF/UA fixup

Option 2: Replace Non-standard Tags

1. In the Tags panel, right-click the non-standard tag
2. Select Properties
3. Change the Type to a standard PDF/UA tag
4. Repeat for all instances

Option 3: Edit Role Map via Preflight

1. Go to Tools > Print Production > Preflight
2. Click the Options icon (wrench)
3. Select Create Fixup
4. Create a fixup that adds role mappings for your custom tags

Common mappings needed:

02-002: Non-standard Role Maps to Inappropriate Standard Role

What's Wrong: A custom tag has a role mapping, but it maps to the wrong standard element. For example, a custom "Heading" tag might incorrectly map to "P" (paragraph) instead of "H1."

How to Identify:

• This requires human review of the role map
• Compare visual appearance and semantic meaning to the mapped role
• Check if headings are mapped to paragraph, or lists mapped to spans

How to Fix:

1. Use Tools > Print Production > Preflight
2. Create a custom fixup to modify the role map
3. Correct the mapping to use the appropriate standard role

When evaluating mappings, consider:

• Does the visual presentation match the semantic role?
• Would a screen reader user expect this content to behave like the mapped element?
• Can users navigate to this content using structure-based navigation?

02-003: Circular Role Mapping (Machine Testable)

What's Wrong: The role map creates a circular reference where tag A maps to tag B, and tag B maps back to tag A (or through a chain back to A). This creates an infinite loop that breaks assistive technology.

How to Identify:

• PDF/UA validators will detect circular mappings
• Symptoms include screen readers hanging or crashing
• Check the role map for chains that loop back

How to Fix:

1. Export the role map using a PDF editing tool or library
2. Identify the circular reference chain
3. Break the loop by:
   • Removing one of the mappings
   • Mapping one of the tags directly to a standard role
4. Verify with a PDF/UA validator after fixing

Example of circular mapping:

CustomHeading -> MyH1 -> CustomHeading  (circular!)

Correct structure:

CustomHeading -> H1  (maps to standard)
MyH1 -> H1          (maps to standard)

02-004: A Standard Role Has Been Remapped (Machine Testable)

What's Wrong: A standard PDF role (like P, H1, or Table) has been remapped to something else. Standard roles should never be remapped because they already have defined meanings.

How to Identify:

• PDF/UA validators will flag remapped standard roles
• Check the role map for entries where the source is a standard PDF tag
• This error is common in documents converted from other formats

How to Fix:

1. Remove the role mapping entry for the standard tag
2. Standard tags should never appear as the source (left side) of a role mapping
3. Use Preflight or a PDF library to edit the role map

Invalid example:

H1 -> Title  (remapping a standard role - WRONG!)

Role maps should only have non-standard tags on the left:

Title -> H1  (correct - custom tag maps to standard)

How to Fix in Adobe Acrobat

Adobe Acrobat Pro has limited direct role map editing capabilities, but several approaches work.

Checking the Current Role Map

1. Open Tools > Print Production > Preflight
2. Select a PDF/UA profile
3. Run the check
4. Look for role mapping errors in the results

Replacing Non-standard Tags

The simplest fix is often to replace non-standard tags with standard ones:

1. Open the Tags panel (View > Show/Hide > Navigation Panes > Tags)
2. Find tags with non-standard names
3. Right-click each tag and select Properties
4. Change the Type to the appropriate standard tag:
   • Use H1-H6 for headings
   • Use P for paragraphs
   • Use L, LI, Lbl, LBody for lists
   • Use Table, TR, TH, TD for tables
   • Use Link for hyperlinks
   • Use Figure for images

Using Preflight Fixups

1. Go to Tools > Print Production > Preflight
2. Click the wrench icon to open Preflight options
3. Select Create Fixup
4. Name your fixup (e.g., "Fix Role Mappings")
5. Add conditions and fixes for role map issues
6. Save and run the fixup

Using JavaScript for Complex Fixes

For advanced users, Acrobat's JavaScript console can modify role mappings:

1. Go to Tools > JavaScript > JavaScript Console
2. Access document structure through the Acrobat JavaScript API
3. Modify the StructTreeRoot to add or correct role mappings

Note: This requires advanced knowledge of the PDF structure and Acrobat JavaScript.

How to Fix in Microsoft Word

Preventing role mapping issues starts with proper document creation.

Use Built-in Styles

Word's built-in styles map correctly to standard PDF tags:

1. Always use styles from the Styles gallery
2. Avoid creating custom styles unless necessary
3. If you create custom styles, base them on built-in styles

Avoid Custom Formatting

Custom formatting that mimics structure (like bold, large text) without using styles creates problems:

Wrong:

• Making text bold and large to look like a heading
• Using tab characters to create list indentation
• Drawing boxes to look like tables

Right:

• Apply Heading 1, Heading 2, etc. styles
• Use built-in list features
• Insert actual tables

Export Settings

When saving as PDF:

1. Go to File > Save As and choose PDF
2. Click Options
3. Ensure Document structure tags for accessibility is checked
4. This preserves Word's structure as standard PDF tags

Testing Your Fix

Automated Validation

1. Adobe Acrobat:

   • Go to Tools > Accessibility > Accessibility Check
   • Select PDF/UA-1 as the standard
   • Run the check and review role mapping errors

2. PAC (PDF Accessibility Checker):

   • Open your PDF in PAC
   • Run the PDF/UA check
   • Check the Matterhorn Protocol section for Checkpoint 02

Manual Verification

1. Open the Tags panel in Acrobat
2. Review all tag names
3. Verify each non-standard tag has a logical mapping
4. Check that no standard tags are remapped

Screen Reader Testing

1. Open the PDF in a screen reader
2. Use navigation shortcuts:
   • H to jump through headings
   • T to jump through tables
   • L to navigate lists
3. If navigation does not work, role mapping may be the issue

Validation Checklist

• All non-standard tags map to appropriate standard roles
• No circular mappings exist
• No standard roles are remapped
• Screen reader navigation works correctly
• PDF/UA validation passes for role mapping

Additional Resources

Official Standards and Guidelines

• W3C WCAG 2.1 Success Criterion 1.3.1: Info and Relationships
• W3C WCAG 2.1 Success Criterion 4.1.1: Parsing
• W3C WCAG 2.1 Success Criterion 4.1.2: Name, Role, Value
• PDF Association Matterhorn Protocol 1.02

Technical References

• ISO 32000-1: PDF Standard Role Map
• ISO 14289-1: PDF/UA-1 Structure Requirements
• PDF 1.7 Reference: Structure Tree

Tools

• PAC (PDF Accessibility Checker) - Free PDF/UA validation
• Adobe Acrobat Preflight - Advanced PDF analysis
• veraPDF - Open source PDF/UA validator

This documentation is based on the Matterhorn Protocol 1.02, the definitive reference for PDF/UA validation. For the most current information, consult the PDF Association and W3C WCAG guidelines.