Matterhorn 28-011 · PDF/UA-1 UA1:7.18.5-1
Link annotation not inside 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).
The condition, as the protocol states it. “A link annotation is not nested within a <Link> tag.”
Matterhorn Protocol 1.1, checkpoint 28, index 28-011, section UA1:7.18.5-1. Software can decide this one on its own.
What a screen reader actually does
The link is announced with no text, or the text is announced with no indication that it is a link.
What is in the file
A link is two objects that have to be joined.
The annotation is the clickable region and the action:
19 0 obj
<< /Type /Annot
/Subtype /Link
/Rect [ 72 640 300 660 ]
/F 4
/Contents (Privacy notice, opens example.gov)
/A << /S /URI /URI (https://example.gov/privacy) >>
/StructParent 3
>>
endobjThe structure element is its place in the reading order, and it holds both the link’s text and a reference back to the annotation:
20 0 obj
<< /Type /StructElem
/S /Link
/P 9 0 R
/Pg 3 0 R
/K [ 5, % the link text (MCID 5)
<< /Type /OBJR /Obj 19 0 R /Pg 3 0 R >> % the annotation
]
>>
endobjCondition 28-011 fires when the annotation exists and that <Link> element does not. The rectangle is clickable and nothing else.
What the user gets
In NVDA’s links list (Insert + F7), the link is absent. Tabbing may reach the annotation, in which case the reader announces:
link
with no destination and no text. Where the surrounding sentence reads “see the privacy notice for details”, the words privacy notice are announced as ordinary body text, disconnected from anything clickable.
How to fix it free, in Acrobat Pro
Acrobat has a purpose-built command for this and it works well:
- Open the Tags panel.
- Select the tag containing the link text — usually the
<P>the sentence lives in. Options → Find→ choose Unmarked Links → Find.- Acrobat highlights each unmarked link annotation in turn. Click Tag Element.
- Acrobat creates a
<Link>element containing the text and an/OBJRto the annotation, in the right place in the tree.
That is the whole job for structure. For the description (condition 28-012):
- Right-click the link annotation on the page → Properties → the General tab has no description field, so instead:
- In the Tags panel, right-click the new
<Link>element → Properties → Alternate Text, and describe the destination.
Upstream is easier, as usual. Word and InDesign both export real hyperlinks as tagged <Link> elements automatically. The links that break are the ones added in Acrobat — with Edit → Link → Add or Edit or with Create Links from URLs — because those create the annotation without the structure.
Writing link text that survives being read out of context
WCAG 2.4.4 is about purpose “in context”, but a links list strips the context away. Three practical rules:
- Never “click here”, “read more” or a bare URL. A URL read character by character is thirty seconds of alphabet.
- Front-load the distinguishing word. Privacy notice (PDF, 240 KB) beats Download our privacy notice as a PDF.
- Two links with the same text must go to the same place. Otherwise the list has two identical entries with different destinations.
Where Taggart differs
Taggart reports the annotation, the page, and which of the two problems it has — no structure element, or the wrong one:
A link annotation on page 3 is not referenced from the structure tree, so it is not nested within a
<Link>tag and has no associated link text.
The structural fix is mechanical: Taggart creates the <Link> element, wires the /OBJR, and registers the annotation in the parent tree with a fresh /StructParent key. Because a newly created element has no natural position, it is appended at the end of the tree and the change log says so explicitly — open the reading order editor to place them correctly. Silently guessing where a link belongs in a sentence would be worse than leaving it visible.
The description is a human decision. Taggart will offer the target URI as a starting point if you ask for it, and marks every /Contents filled that way as derived from the target URI — review the wording.
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 Build link structure elements. 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
The link works when I click it. Why is that not enough?
Clicking is a mouse operation. A screen reader user reaches links through the links list or by tabbing, and both need the link to exist in the structure tree with text attached. A bare annotation is a rectangle on the page that happens to be clickable; to assistive technology it is invisible.
What is an OBJR?
An object reference. It is how a structure element points at something that is not marked content — an annotation, usually. The Link structure element holds the link's text as marked content and an /OBJR pointing at the annotation, which is what joins the two.
Do I need Contents as well as the Link tag?
Yes, they are separate conditions. The Link tag (28-011) puts the link in the reading order with its text. The /Contents entry (28-012) is an alternate description of where the link goes. A link whose visible text is 'click here' passes 28-011 and still fails WCAG 2.4.4 unless /Contents says something useful.
What about automatically generated URL links?
Acrobat's Create Links from URLs generates annotations with no structure at all, so a document run through it typically fails this condition on every link. It is a convenience feature, not an accessibility one.
Where this sits in the standards
| Standard | Reference |
|---|---|
| Matterhorn Protocol 1.1 | Checkpoint 28 (Annotations), index 28-011 |
| PDF/UA-1 (ISO 14289-1) | Clause 7.18.5-1 |
| WCAG 2.1 | 1.3.1 Info and Relationships — Level A |
| WCAG 2.1 | 2.4.4 Link Purpose (In Context) — 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-012 A link annotation does not include an alternate description in its Contents entry Link annotations need /Contents describing where the link goes.
- 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.
- 13-002 A link with a meaningful background lacks alternative text for both An image link — a button, a logo that navigates — needs alternative text that conveys both what the graphic shows and where the link goes.
- 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.
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-004 An annotation has neither a Contents entry nor an alternative description Every 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 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-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 page cap, no watermark, no account needed.
Verified against a real document on . Last updated .