Matterhorn 02-004 · PDF/UA-1 UA1:7.1-4
Remapping a standard tag redefines the vocabulary
A standard structure type appears as a key in the role map — for example /P mapped to /Span. Standard types must never be remapped; doing so redefines the vocabulary the whole file depends on.
The condition, as the protocol states it. “One or more standard types are remapped.”
Matterhorn Protocol 1.1, checkpoint 02, index 02-004, section UA1:7.1-4. Software can decide this one on its own.
What a screen reader actually does
Every element using the remapped type is announced with the wrong role, document-wide.
What a role map is for
The structure tree root carries a /RoleMap dictionary. It exists so a producer can use its own tag names and still be understood:
/RoleMap <<
/BodyText /P
/PullQuote /Quote
/Caption2 /Caption
>>A reader that has never heard of BodyText looks it up, finds P, and treats the element as a paragraph. This is the mechanism that makes custom tags legal at all — an unmapped custom name is a failure precisely because nothing can resolve it.
The rule is about direction. Custom names may point at standard types. Standard types may not point anywhere.
What breaks when a standard type is a key
/RoleMap << /P /Span >>That entry says: wherever this document uses P, mean Span.
Span is an inline element. P is a block. A reader resolving the map now treats every paragraph in the document as a run of inline text with no paragraph boundaries — so the document has no paragraphs at all, anywhere, and the reader announces one continuous run.
The same mechanism with worse consequences:
/H1 /Premoves the top of the outline. The heading list loses every level-one entry; nothing is announced as a heading./Table /Divtakes the document out of table mode entirely. EveryTRandTDbeneath it is orphaned from a grid that no longer exists, and the header associations go with it./Figure /Spanmakes images inline text, and their/Altstops being announced as an image description./L /Pflattens every list.
Not one of these is visible on the page. The file renders identically, and a reader that ignores the role map — some do — behaves correctly, which means the bug reproduces on some machines and not others.
What the user hears
Every element of the remapped type, announced with the wrong role, throughout the document. There is no partial version of this.
The characteristic report is a document that “reads as one long paragraph” or where “the headings list is empty even though the tags panel shows headings”. Both describe somebody looking at a Tags panel that shows H1, and a reader resolving H1 to something else.
How to check it free
Acrobat Pro. Tags panel → Options → Edit Role Map. The dialog lists the map. Anything in the left column that is a standard type is this condition. It is a short list to read and it takes a minute.
veraPDF reports it against clause 7.1 and names the offending keys.
PAC reports it under Logical Structure → Role mapping.
How to fix it free, in Acrobat Pro
- Tags panel →
Options → Edit Role Map. - Find each entry whose key is a standard type.
- Delete it.
Deleting is almost always right, and it is worth understanding why. Removing /P → /Span does not lose information: elements tagged P go back to meaning P, which is what the tag says and what the document’s author intended. The entry was adding a redefinition, not carrying meaning of its own.
The rare case where deletion is wrong is a document that genuinely used P elements as inline spans and relied on the remap to describe them. That is a document with two problems, and the second one — elements tagged as the wrong type — is not fixed by keeping the first.
Where Taggart differs
rolemap-repair is a safe fix and runs in the batch, because removing a redefinition of a standard type cannot lose meaning: it restores the type to what its own name says.
Taggart reports the blast radius rather than the entry, because the entry on its own does not convey the problem:
/RoleMap maps the standard type P to Span. 214 elements in this document use P.
Two hundred and fourteen paragraphs is a different sentence from “one role map entry is invalid”, and it is the one that tells a reviewer whether this file is worth arguing about.
It also separates this from 02-003, a circular mapping, and from 02-001, a custom tag that maps to nothing. All three are role-map failures and all three have different repairs — one deletion, one loop to break, one mapping to add — so reporting them as “role map problem” would hide the only useful part.
How Taggart handles it
Taggart detects this condition automatically. It is reported as a blocker, with the page, the structure path and the object id of every occurrence.
The fix is Repair the role map. It is mechanical, so “Fix All Safe” applies it in bulk with a diff and a single undo.
Whatever Taggart changes, the page still looks identical. Fixes edit the PDF object model, not the content streams, and every remediation is re-rendered and compared against the original at structural similarity ≥ 0.999 before you get the file back. A tool that quietly reflows your document is worse than no tool.
Frequently asked questions
What is a role map for, then?
Giving a custom name a standard meaning. A generator that emits BodyText and PullQuote maps them to P and Quote, and a reader that knows nothing about those names still knows what to do. That is the whole purpose, and it is a good one — it lets a producer keep its own vocabulary without losing meaning.
How does a standard type end up in there?
Almost always a merge. Two documents tagged by different tools are combined, the role maps are unioned, and one of them contained an entry that was harmless in its own file. It also happens when somebody edits a role map by hand to 'fix' something and reaches for the type they see rather than the one they meant.
Is it really document-wide?
Yes, and that is what makes it serious rather than tidy. The role map is one dictionary in the structure tree root. An entry mapping P to Span does not affect one paragraph; it changes what every P in the document resolves to.
Which types count as standard?
Everything ISO 32000-1 Table 333 defines: Document, Part, Sect, Div, P, H, H1 through H6, L, LI, LBody, Table, TR, TH, TD, Figure, Formula, Form, Link, Span, Quote, Note, Reference, BibEntry, Code, Artifact and the rest. None of them may appear as a key.
Where this sits in the standards
| Standard | Reference |
|---|---|
| Matterhorn Protocol 1.1 | Checkpoint 02 (Role Mapping), index 02-004 |
| PDF/UA-1 (ISO 14289-1) | Clause 7.1-4 |
| WCAG 2.1 | 1.3.1 Info and Relationships — Level A |
| EN 301 549 / Section 508 / ADA Title II | All three point at WCAG 2.1 Level AA for non-web documents, so a Level A or AA criterion here is in scope for each of them. |
Related conditions
- 02-001 Non-standard tag mapping does not terminate with a standard type A custom tag name is present in the role map but the chain of mappings never arrives at a structure type defined in ISO 32000-1, 14.8.4. Mapping may be indirect — a custom type may map to another custom type — but it must eventually terminate.
- 02-003 A circular mapping exists The role map contains a cycle: A maps to B, B maps back to A. Resolution never terminates.
- 14-001 Headings are not tagged Text that is visually a heading — larger, bolder, isolated — is tagged as a paragraph. The document has no navigable outline.
- 09-001 Tags are not in logical reading order The order of elements in the structure tree does not match the order a human would read the page. This is the single most common substantive defect in tagged PDFs and the one Acrobat's own tooling handles worst.
Other conditions in checkpoint 02
Checkpoint 02 covers role mapping. These are its other failure conditions; the ones without a link are in the rule set but do not have a written page yet.
- 02-001 Non-standard tag mapping does not terminate with a standard type A custom tag name is present in the role map but the chain of mappings never arrives at a structure type defined in ISO 32000-1, 14.8.4. Mapping may be indirect — a custom type may map to another custom type — but it must eventually terminate.
- 02-002 Role mapping is semantically inappropriate The role map terminates at a standard type, but the wrong one — a custom "Sidebar" mapped to Table, or "PullQuote" mapped to Figure.
- 02-003 A circular mapping exists The role map contains a cycle: A maps to B, B maps back to A. Resolution never terminates.
Check your own file. Taggart’s validator is free and unlimited — every machine-checkable Matterhorn condition, no page cap, no watermark, no account needed.
Verified against a real document on . Last updated .