Skip to content
SilktideHelp

PDF role mapping

Silktide checks that any custom tag names a PDF invents are explained. A document may name its own tags, but each one has to point at one of the standard structure types the PDF format defines, or nothing reading the document knows what it is for.

The lookup table that does the pointing is the . This check reports three ways it goes wrong: a custom tag with no entry at all, a standard tag remapped to mean something else, and a role map that loops back on itself so a tag never resolves to anything real.

Why this matters

A tag name is a label, not a meaning. When a design tool exports a heading as SubtitleBlue and never says that SubtitleBlue is a level-two heading, receives a word it has no rules for. Depending on the reader, that content is announced as an ordinary paragraph or skipped, and either way it stops being a heading: it disappears from the document outline, so it cannot be navigated to and cannot be used to skim.

Remapping in the other direction is more damaging, because the document confidently states something untrue. A Table remapped to a paragraph type tells a reader there is no table on the page, and the reader believes it. The cells are then read as running prose, with no rows, no columns, and no headers.

A circular role map is a structural fault rather than a subtle one. Tags never resolve, and some readers and validators reject the structure tree outright, which takes the document from partly accessible to not accessible at all.

This is the sort of problem that comes from the authoring tool rather than from anything the author did, which is exactly why it needs checking: nobody chose it, so nobody thinks to look for it.

How to fix it

  1. Prefer standard tags. If the content is a heading, tag it H1 to H6; if it is a list, tag it L. A custom name is only worth having when the standard vocabulary genuinely has no equivalent, which is rare in ordinary documents.
  2. Map every custom tag you do keep to the standard type that matches what it is, so SubtitleBlue resolves to a heading.
  3. Remove role map entries that redefine standard tags. A standard tag already means the right thing; overriding it can only make the document less accurate.
  4. Break any loop so every custom tag ends at a standard type rather than at another custom one.
  5. Re-export from the source with PDF/UA output enabled, which usually clears all of this at once, or run Silktide remediation, which rebuilds the structure using standard types only. See How PDF remediation works.

Role maps are edited in a PDF editor's tag panel rather than in the visible document, so this is one of the repairs where re-exporting from the original file is usually less work than fixing the PDF.

How Silktide tests this

  1. Find the PDF documents linked from your website, and analyse each unique file once, however many pages link to it.
  2. Collect the structure types the document uses, and the role map entries it declares.
  3. Report the document when a non-standard type has no valid mapping, when a standard type is remapped to a different type, or when following the map leads in a circle.
  4. Report each document once, however many tags are affected.

Troubleshooting

This is reported but the document reads correctly for me

Readers differ in how forgiving they are. Some infer a role from context and get away with it; others do not, and the ones people rely on for long documents tend to be the strict ones. A document that only works in the reader you happen to test with is a document that works by luck.

Why is this a PDF/UA requirement rather than a WCAG one

Because it is a rule about how the file is built rather than about what the reader experiences, and WCAG describes outcomes. The outcome it protects - content keeping its real meaning - is covered by WCAG through the checks that examine headings, lists, and tables directly. See Understanding PDF accessibility for how the two standards divide the work.

Learn more

Last updated

Was this page helpful?

PDF role mapping | Silktide Help