Matterhorn 28-013 · PDF/UA-1 UA1:7.18.5-3
IsMap links: server-side image maps in a PDF
A server-side image map requires pointing at a pixel, which is not possible without a mouse.
The condition, as the protocol states it. “An IsMap entry is present with a value of true but the functionality is not provided in some other way.”
Matterhorn Protocol 1.1, checkpoint 28, index 28-013, section UA1:7.18.5-3. The protocol marks this as requiring human judgement.
What a screen reader actually does
The functionality is unreachable by keyboard.
What IsMap does
A link annotation that opens a web address carries a URI action, and a URI action can have an /IsMap flag:
<< /Type /Annot
/Subtype /Link
/Rect [ 72 400 472 700 ] % a map of the city's districts
/Contents (District map)
/A << /S /URI
/URI (https://maps.example.gov/cgi-bin/districts)
/IsMap true >>
>>With /IsMap true, ISO 32000-1 has the viewer track where in the rectangle the user clicked, measured from its top-left corner, and append that position to the address. A click 120 points across and 85 down sends the browser to:
https://maps.example.gov/cgi-bin/districts?120,85The server decides from the numbers which district was meant. It is the PDF equivalent of HTML’s ismap attribute: a server-side image map.
What breaks
The link only works with a pointer. A keyboard user can reach it and activate it, but a keyboard has no position to give, so whatever the viewer sends is not a choice the user made. What comes back is whatever the server does with that: an error, a default region, or the wrong district. A screen-reader user is in the same position, with the added problem that the regions are only drawn, never named, so they cannot know what there is to choose from.
That is WCAG 2.1.1 Keyboard, and it is an old problem. The original US Section 508 web rules required “redundant text links” for each active region of a server-side image map, for exactly this reason.
The condition, and how to judge it
Condition 28-013 is an /IsMap true link whose functionality is not provided some other way. The flag alone is not a failure. The question for a person is whether everything the map does can be done without pointing at a pixel:
- Find out what the regions are. Click around the map, or ask whoever runs the server. Write down each destination: twelve districts, say, each with its own page.
- Look for those destinations elsewhere in the document. A list of district links under the map, an index at the back, a table of contents. If every region has an ordinary text link somewhere a reader will find it, the condition is met.
- If they are not there, add them. A list of plain links next to the map, one per region, is the standard answer. The map can stay for the people who use it.
Also check what the address does on its own, without coordinates. If the server answers the bare address with a usable text index of the regions, that may count as the other way in, provided the reader can find it and use it.
How to check it free
qpdf. Write the readable form and search for the flag:
qpdf --qdf --object-streams=disable guide.pdf readable.pdfLook for /IsMap true inside link annotations’ /A dictionaries.
Acrobat Pro has no documented way to see the flag. Adobe’s documentation of link actions covers Go to a page view, Open a file, Open a web page and Custom link (Add links to PDFs), and nothing about tracking the click position.
veraPDF has no test for this condition, because the protocol gives it no machine test.
How to fix it free, in Acrobat Pro
Add the alternative links. Adobe documents creating a link as Edit in the global bar → in the left pane under ADD CONTENT, More → Link → Add or edit a link, then drag a rectangle and choose Open a web page as the link action (Add links to PDFs). Do it once per region, over a line of text naming the region, with the region’s own address.
Links added that way are not tagged. In the Tags panel, choose Find from the options menu, which searches for unmarked links among other things, and tag each one (Edit document structure with the Content and Tags panels). 28-011 has the details. Then give each a description that names the region, which is 28-012.
Better, if the document is generated: have the producer write the list of region links in the first place.
What Taggart does
Taggart finds every link annotation whose action has /IsMap set to true and reports it for a person to decide:
A link annotation on page 1 sets /IsMap true (server-side image map). Confirm the same functionality is available without pointing at a pixel.
It is reported as needs a human decision, not as a failure, and there is no repair attached, because the repair is content: links that only someone who knows the map can write. The finding goes into the review queue. When you record your decision there (that the alternative links exist and where, or that they do not), the remediation report lists it with who made it, when, and the reason given. Until it is decided, the report stops at machine checks passed and the PDF/UA identifier is not written; a recorded decision is what settles it. Deferring it does not.
What the check looks for is narrow and exact: a link whose action sets /IsMap to true. It does not judge whether the alternative exists; that is the decision it hands you.
Taggart does not remove the flag either. That would not help anyone: the link would still go to the same server, now never with a position, and the map would stop working for the people who can use it.
How Taggart handles it
The protocol marks this condition as needing human judgement, so no validator can decide it outright. Taggart applies a heuristic to find the likely cases and reports each one as human decision for you to settle in the review queue. A heuristic finds what it was built to find and can miss the rest; what this one looks for is described above.
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
Is IsMap forbidden?
No. PDF/UA-1 allows it on condition that whatever the map does can also be done another way. That is why this is a judgement and not a machine check: software can find the flag, but only a person can tell whether the alternative exists.
Does a description in /Contents count as the alternative?
No. It tells a screen-reader user that the link is there and roughly what it is, which is condition 28-012. It does not let them choose a region of the map, and choosing is the functionality in question.
Can Taggart tell me what the regions are?
No. The regions exist only on the server, as whatever it does with the numbers it receives. Nothing in the PDF lists them, so the list of destinations has to come from clicking the map or from whoever runs the server.
Where this sits in the standards
| Standard | Reference |
|---|---|
| Matterhorn Protocol 1.1 | Checkpoint 28 (Annotations), index 28-013 |
| PDF/UA-1 (ISO 14289-1) | Clause 7.18.5-3 |
| WCAG 2.1 | 2.1.1 Keyboard — 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
- 28-011 A link annotation is not nested within a Link tagA link annotation must be a child of a Link structure element containing the link's text, joined by an object reference (/OBJR).
- 28-012 A link annotation does not include an alternate description in its Contents entryLink annotations need /Contents describing where the link goes.
- 28-004 An annotation has neither a Contents entry nor an alternative descriptionEvery non-widget annotation needs an accessible description, either in its own /Contents or in the /Alt of the structure element that encloses it.
Other conditions in checkpoint 28
Checkpoint 28 covers annotations. These are its other failure conditions; the ones without a link are in the rule set but do not have a written page yet.
- 28-001 An annotation is not in correct reading orderThe annotation's position in the structure tree does not match where it appears on the page.
- 28-002 An annotation is not a direct child of an Annot structure elementNon-widget, non-link annotations must sit inside an Annot structure element so they have a place in the reading order.
- 28-003 An annotation is used for visual formatting but is not tagged according to its semantic functionA Square or Line annotation used to draw a box round a callout is decoration and should be artifacted, or tagged for what it actually means.
- 28-004 An annotation has neither a Contents entry nor an alternative descriptionEvery non-widget annotation needs an accessible description, either in its own /Contents or in the /Alt of the structure element that encloses it.
- 28-005 A form field has neither a TU entry nor an alternative descriptionThe /TU tooltip is the accessible name of a PDF form field. Without it the field has no name at all — the visible label printed next to it is not connected to the control.
- 28-006 An annotation with subtype undefined in ISO 32000 does not meet 7.18.1A custom annotation subtype still has to be placed in the structure tree and described.
- 28-007 An annotation of subtype TrapNet existsTrapNet annotations are prepress artefacts and are forbidden in PDF/UA-1.
- 28-008 A page containing an annotation does not contain a Tabs entryAny page carrying annotations must declare a tab order. PDF/UA-1 requires /Tabs /S — tab order follows the structure tree.
- 28-009 A page containing an annotation has a Tabs entry with a value other than S/Tabs is present but set to /R (row order) or /C (column order) rather than /S (structure order).
- 28-010 A widget annotation is not nested within a Form tagEvery form control must sit inside a Form structure element.
- 28-011 A link annotation is not nested within a Link tagA link annotation must be a child of a Link structure element containing the link's text, joined by an object reference (/OBJR).
- 28-012 A link annotation does not include an alternate description in its Contents entryLink annotations need /Contents describing where the link goes.
- 28-014 CT entry is missing from the media clip data dictionaryThe media clip's content type (/CT) is required so a processor knows what it is being asked to play.
- 28-015 Alt entry is missing from the media clip data dictionaryMedia clips require an /Alt array giving a text description.
- 28-016 File attachment annotations do not conform to 7.11The file specification referenced by a FileAttachment annotation must carry both /F and /UF.
- 28-017 A PrinterMark annotation is included in the logical structureCrop marks and registration targets are production artefacts and must not appear in the structure tree.
- 28-018 The appearance stream of a PrinterMark annotation is not marked as ArtifactThe content inside a PrinterMark's appearance stream must itself be artifacted.
Check your own file. Taggart’s validator is free and unlimited — 75 of the 87 Matterhorn conditions software can decide, with the other 12 listed for you to confirm; no watermark, no expiry, and no account needed up to 60 pages.
Checked with Taggart on a generated file that fails this condition on . The Acrobat steps follow Adobe’s documentation and were not walked through by hand. Last updated .