Matterhorn 28-001 · PDF/UA-1 UA1:7.18.1-2
Annotation out of reading order: links announced too late
The annotation's position in the structure tree does not match where it appears on the page.
The condition, as the protocol states it. “An annotation is not in correct reading order.”
Matterhorn Protocol 1.1, checkpoint 28, index 28-001, section UA1:7.18.1-2. The protocol marks this as requiring human judgement.
What a screen reader actually does
A link or form field is announced somewhere other than where it belongs in the text.
Where an annotation’s reading position comes from
An annotation has no place in the reading order of its own. It is a dictionary in the page’s /Annots array: a rectangle, an action, an appearance. It enters the reading order through a structure element (<Link>, <Form> or <Annot>) that holds an /OBJR pointing at it. Where that element sits in the tree is where the annotation is read.
Nothing ties the element’s position to the rectangle’s. This is a page whose link is drawn on the second line and whose <Link> element was added last:
/Document
├── /H1 "Annual return 2026"
├── /P "Download the return form (PDF, 2 pages)" ← link drawn here
├── /P "Section 1: what to enter in box 1."
├── /P "Section 2: what to enter in box 2."
├── /P "Section 3: what to enter in box 3."
├── /P "Section 4: what to enter in box 4."
└── /Link OBJR → the link annotation ← read hereThe condition is an annotation whose element is not where it belongs: too late, too early, or in the wrong section altogether.
What the user hears
The heading, then “Download the return form (PDF, 2 pages)” read as an ordinary sentence with nothing to activate in it. Then four sections. Then, after everything else on the page, the link, detached from the words it was drawn over.
Tab order follows the same element. PDF/UA requires /Tabs /S on any page with annotations (28-009), which makes the viewer take keyboard order from the structure tree. A keyboard user tabbing through a form whose fields were tagged out of order jumps around the page in the order of their elements in the tree, not the order the fields appear.
Where it comes from
Annotations added after the document was tagged. Acrobat’s Tag Annotations option tags new comments and form fields as they are made, and Adobe describes where they go: “after the selected tag element” (Edit document structure with the Content and Tags panels). Whatever happened to be selected in the Tags panel decides the reading position.
Tools that append to the end of the tree. It is the easy place to put a new element, and it is wrong for nearly every annotation. Taggart’s own annotation repair used to do it, and on a real one-page document it had two links from the top of the page announced after all thirty-three paragraphs.
Edits after tagging. A link moved, or a form field redrawn, keeps its old element where it was.
How to check it free
Acrobat Pro’s Accessibility Checker does not decide this. Its Logical Reading Order rule is one Adobe tells you to verify manually, by comparing the order in the Tags panel with the order the document should be read in (Create and verify PDF accessibility).
The Tags panel is how you do that. Open it (Menu → View → Show/Hide → Side panels → Accessibility tags), choose Highlight Content from its options menu, and walk the tree. Each <Link>, <Form> and <Annot> element is read between its neighbours in the tree; compare that with where its annotation is drawn on the page. If they disagree, that is this condition.
Tab through the page with a screen reader running. With /Tabs /S, the order you are taken through links and fields is the structure order, so a jump backwards or forwards is visible straight away.
veraPDF does not test this condition, because the protocol gives it no machine test.
How to fix it free, in Acrobat Pro
Adobe documents moving a tag in the Tags panel (Edit document structure with the Content and Tags panels):
- Turn on Highlight Content, and find the annotation’s element. For a link, select its text on the page and use Find Tag From Selection.
- Drag the tag to where it belongs. A line shows the viable drop positions as you drag.
- Or choose Cut from the options menu, select the tag above the target, and choose Paste to put it at the same level, or Paste Child to put it inside.
- Tab through the page again to confirm.
For a link, the right place is inside the paragraph it is drawn over, next to the words it covers. For a form field, the right place is next to its label.
What Taggart does
The protocol gives this condition no machine test, so Taggart applies a heuristic and reports what it finds as a warning. For each annotation that has a structure element and a rectangle, it counts the elements earlier in the tree, on the same page, whose content starts more than 24 points below the middle of the annotation. Three or more, and it reports:
A /Link annotation on page 1 is placed after 4 block(s) of content that appear below it on the page, so it is announced later than it is reached.
That is the example above, and the fixture behind this page. The heuristic has limits worth knowing. It finds annotations read too late, not too early. It compares vertical position only, so on a two-column page it can flag a link at the top of the right column that is correctly read after the whole left column; that is why it is a warning for a person to confirm. And it only looks at annotations that are in the tree at all: an annotation with no element is 28-002, 28-010 or 28-011.
The repair is reading-order, which waits for your approval. It comes in two forms.
The reading-order editor. You move the element among its siblings, on a view of the page with numbered badges, and the repair applies that order. That is what clears the finding on the fixture. The editor reorders siblings; it does not move a <Link> into a paragraph. For that, use Acrobat’s Paste Child as above.
Reorder by page geometry. Taggart orders each element’s children by where their marked content sits on the page: row by row, siblings whose heights overlap read as one row, in the direction of the parent’s text. The children of tables, rows, lists and list items keep the order the author gave them. That puts a <Link> that holds its own text in the right place. A <Link> that holds nothing but the /OBJR has no marked content to sort by, and the sort puts it after its siblings, which is where it already was. On the fixture Taggart reports that the sort had nothing to move and points to the editor; for links like that, the editor is the way.
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 warning 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.
The fix is Repair reading order. 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
Does the order of the page's /Annots array matter?
Not for PDF/UA. A conforming page has /Tabs /S (conditions 28-008 and 28-009), which tells a viewer to take the tab order from the structure tree. So the structure element is what decides both where an annotation is read and where it is reached by Tab.
Why is this a warning rather than a failure?
Because the Matterhorn Protocol gives it no machine test: whether an annotation is in the right place is a judgement about the document. Taggart's check is a heuristic that finds the likely cases and puts them in front of a person. It does not pass the ones it cannot see.
Where should a link's element go?
Inside the paragraph whose words the link is drawn over, holding those words' marked content as well as the /OBJR to the annotation. Then the link is read at the right point, its text is its accessible text, and condition 28-011 is satisfied in the same move.
Can Taggart's own repairs cause this?
Its annotation repairs place each new element where the annotation's rectangle is: inside the element whose content it overlaps, or just before the first element that starts below it. Only when no content on the page overlaps it or lies below it does the element go at the end of the tree, and the change log line for each annotation says where it was put.
Where this sits in the standards
| Standard | Reference |
|---|---|
| Matterhorn Protocol 1.1 | Checkpoint 28 (Annotations), index 28-001 |
| PDF/UA-1 (ISO 14289-1) | Clause 7.18.1-2 |
| WCAG 2.1 | 1.3.2 Meaningful Sequence — 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. |
Guides that cover it
Related conditions
- 09-001 Tags are not in logical reading orderThe 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.
- 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-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-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-010 A widget annotation is not nested within a Form tagEvery form control must sit inside a Form structure element.
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-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-013 An IsMap entry is true but the functionality is not provided in some other wayA 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 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 .