Matterhorn 28-004 · PDF/UA-1 UA1:7.18.1-4
Links and annotations announced as "link" and nothing else
Every non-widget annotation needs an accessible description, either in its own /Contents or in the /Alt of the structure element that encloses it.
The condition, as the protocol states it. “An annotation, other than of subtype Widget, does not have a Contents entry and does not have an alternative description (in the form of an Alt entry in the enclosing structure element).”
Matterhorn Protocol 1.1, checkpoint 28, index 28-004, section UA1:7.18.1-4. Software can decide this one on its own.
What a screen reader actually does
The annotation is announced with its type and nothing else.
What is in the file
Annotations live on the page, in /Annots. Structure lives in the structure tree. The two are connected by an OBJR — an object reference element — sitting inside a structure element, usually Link or Annot.
/Link
├── (marked content) "the annual report"
└── /OBJR → 12 0 R ← the /Annot dictionaryFor the annotation to be describable, one of two things must be true:
- the annotation dictionary has a
/Contentsstring, or - the structure element that encloses the
OBJRhas an/Alt.
If neither, the condition fires. Widget annotations — form controls — are excluded, because they carry their description in /TU and are covered separately.
What the user hears
A screen reader announces an annotation by type, then by description. Without a description it has only the type:
link
link
link
That is the sound of a page of navigation, and it is the single most common accessibility complaint about PDFs that otherwise validate. Three links in a paragraph, each announced identically, in a links list that shows three identical entries.
Where the link wraps visible text and the structure is correct, the reader has the text to fall back on and announces “link, the annual report”. This condition fires in the cases where it cannot:
- A link on an image. A logo linking to a home page, an icon linking to a download. There is no text inside the
Linkelement. - A link whose annotation is not inside the structure tree at all. Extremely common in files where links were added after tagging, or auto-detected by
Tools → Edit PDF → Link → Auto-detect URLs. - A stamp, comment or file-attachment annotation. These have no text by nature, and carry their meaning entirely in
/Contents. - A popup or a markup annotation left in from review. Usually should be flattened or deleted rather than described.
Where it comes from
Auto-detected URLs are the biggest single source. Acrobat’s URL detection creates /Link annotations on the page with no /Contents and no structure elements around them. The links work for a mouse and are invisible to the structure tree.
Word and InDesign both produce properly structured links from their own hyperlink features — a Link element containing the text and an OBJR. What they cannot do is describe a link whose visible content is an image, because the description would have to come from the image’s alt text, and the two are separate fields in both applications.
How to check it free
Acrobat Pro’s Accessibility Check reports this under Forms and Media → Links as Tagged Links — Failed. The right-click Show in Tags Panel on a reported link takes you to the element, or tells you there is not one.
Read the links list, not the page. In Acrobat’s reader view, or any screen reader, open the list of links and read it on its own. A links list full of “link” entries, or full of raw URLs, is the failure this condition describes, and it is faster to see than to validate.
veraPDF reports it against clause 7.18.1.
How to fix it free, in Acrobat Pro
For a link on an image or with no usable text:
- Tags panel → find the
<Link>element (or create one around the content). - Right-click → Properties → Tag tab.
- Fill in Alternate Text with what the link does — Annual report 2025 (PDF, 2 MB), not click here and not the URL.
For a comment, stamp or attachment:
- Right-click the annotation on the page → Properties → General tab.
- Fill in the Description field. That writes
/Contents.
For auto-detected links with no structure at all, the honest repair is usually to delete them and add real hyperlinks in the source document, because a link Acrobat detected from a string of text is not associated with any structure and adding one by hand per link does not scale past a few.
Writing the description. It says where the link goes and what is there — the same rule as web link text. Annual report 2025 is a description. More is not. https://example.gov/docs/ar-2025-final-v3.pdf is technically a description and is read out character by character by some readers, which is worse than nothing.
Where Taggart differs
annotation-descriptions is not a safe fix and never runs from a batch, because a description is content and Taggart does not write content it invented.
What it does is narrow the work. For each undescribed annotation it reports the type, the page, the target where there is one, and the text inside or immediately around the annotation’s rectangle — so the person writing descriptions is reading candidate text rather than opening each annotation to see what it is. Where the same target appears on many pages, they are grouped, so a logo linking to the same URL on forty pages is one decision.
It also separates the two repairs the condition hides. An annotation that has no description is one problem; an annotation that is not in the structure tree at all is a different one, reported as 28-002, and describing it would not help until it is placed. Taggart fixes the placement — that part is mechanical — and then asks for the words.
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 Add annotation descriptions. It changes what the document means, so Taggart proposes it and waits for your approval rather than applying it unattended.
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
My link tag contains the visible text. Is that not the description?
It is the link's text, and a reader announces it — but only when the Link structure element actually contains the text's marked content and the annotation is properly associated through an OBJR. Where the annotation sits outside the tagged text, or where the link covers an image with no text at all, there is nothing to announce and this condition fires.
Contents or Alt — which should I use?
Contents, on the annotation, when the description belongs to the annotation itself: a comment, a stamp, a file attachment. Alt, on the enclosing structure element, when the annotation is part of the reading flow: a link around an icon, a link on a logo. The standard accepts either, and for links the Alt route is what Acrobat's interface actually offers.
Does this apply to form fields?
No — widget annotations are explicitly excluded here, because form controls carry their description in /TU instead. That is a separate condition.
What about link annotations with no visible content, over whitespace?
They still need a description, and they usually should not exist. A link covering empty page area is a hit target a sighted user cannot see and a screen reader user cannot avoid. Deleting it is normally the better repair.
Where this sits in the standards
| Standard | Reference |
|---|---|
| Matterhorn Protocol 1.1 | Checkpoint 28 (Annotations), index 28-004 |
| PDF/UA-1 (ISO 14289-1) | Clause 7.18.1-4 |
| WCAG 2.1 | 1.1.1 Non-text Content — Level A |
| WCAG 2.1 | 4.1.2 Name, Role, Value — 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-002 An annotation is not a direct child of an Annot structure element Non-widget, non-link annotations must sit inside an Annot structure element so they have a place in the reading order.
- 28-005 A form field has neither a TU entry nor an alternative description The /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-008 A page containing an annotation does not contain a Tabs entry Any page carrying annotations must declare a tab order. PDF/UA-1 requires /Tabs /S — tab order follows the structure tree.
- 13-004 Figure tag alternative or replacement text missing A Figure element has neither /Alt nor /ActualText. Every Figure must have one or the other; if the image is decorative it should be an artifact instead of a Figure.
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 order The 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 element Non-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 function A 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-005 A form field has neither a TU entry nor an alternative description The /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.1 A custom annotation subtype still has to be placed in the structure tree and described.
- 28-007 An annotation of subtype TrapNet exists TrapNet annotations are prepress artefacts and are forbidden in PDF/UA-1.
- 28-008 A page containing an annotation does not contain a Tabs entry Any 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 tag Every form control must sit inside a Form structure element.
- 28-011 A link annotation is not nested within a Link tag A 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 entry Link annotations need /Contents describing where the link goes.
- 28-013 An IsMap entry is true but the functionality is not provided in some other way A server-side image map requires pointing at a pixel, which is not possible without a mouse.
- 28-014 CT entry is missing from the media clip data dictionary The 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 dictionary Media clips require an /Alt array giving a text description.
- 28-016 File attachment annotations do not conform to 7.11 The file specification referenced by a FileAttachment annotation must carry both /F and /UF.
- 28-017 A PrinterMark annotation is included in the logical structure Crop 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 Artifact The content inside a PrinterMark's appearance stream must itself be artifacted.
Check your own file. Taggart’s validator is free and unlimited — every machine-checkable Matterhorn condition, no watermark, no expiry, and no account needed up to 60 pages.
Verified against a real document on . Last updated .