Markup annotations need a description

PDF/UA check MARKUP_ANNOT_DESCRIPTION · Annotations · severity Medium · PDF/UA 8.9.2.3 Markup annotations

↩ Back to the rules index · WCAG cross-reference

Why it matters#

Markup annotations need a text description so screen readers can convey their content to users. Without a Contents entry, the annotation's purpose is unclear to assistive technology users.

What you will see#

A comment, highlight or stamp has no Contents text, so there is nothing for a screen reader to announce.

How to fix#

Add a Contents entry to the markup annotation dictionary describing its purpose (e.g. 'Highlight: submission deadline'); alt text on the enclosing structure element also satisfies this check. If the annotation has an RC entry, keep Contents textually equivalent to it.

Step-by-step guide#

1. Locate each flagged annotation via the Comments panel in Acrobat Pro (All tools > Comment), using the page numbers and preview images from the EQChecker report.
2. Path A - Contents entry: double-click the annotation to open its popup note and type a short description of its purpose, e.g. Highlight: submission deadline. Acrobat stores this note text in the annotation's Contents entry.
3. Path B - Alt on the enclosing structure element: select the annotation on the page, open the Accessibility tags panel and use Options > Find Tag from Selection, then open the enclosing element's Properties > Tag tab and fill in Alternate Text. Either path passes this check.
4. If the annotation carries rich text (an RC entry), keep Contents textually equivalent to it - 8.9.2.3 requires equivalence; editing the popup note in Acrobat keeps RC and Contents in sync.
5. If both a Contents entry and an Alt entry on the directly enclosing structure element end up present, make their values identical (8.9.4.2).

Verify: Re-run the EQChecker scan; MARKUP_ANNOT_DESCRIPTION should report zero errors.

Note: Per 8.9.2.3, Contents is mandatory only when the annotation's context is insufficient to convey its purpose, but adding a short description is always safe. Empty or whitespace-only Contents fails the check. Free text annotations display their Contents/RC as visible text and normally pass already. EQChecker only evaluates this check on annotations that are tagged (or skips artifacted ones).

WCAG success criteria#

1.1.1 Non-text Content — Level A#

All non-text content (images, icons, controls) needs a text alternative that conveys the same purpose, or be marked decorative so assistive tech can ignore it.

Understanding 1.1.1

Standards#

This check contributes to the following standards:

PDF/UA WCAG A EN 301 549