Matterhorn 28-006 · PDF/UA-1 UA1:7.18.2-1
Unknown annotation subtype: tag it and describe it
A custom annotation subtype still has to be placed in the structure tree and described.
The condition, as the protocol states it. “An annotation with subtype undefined in ISO 32000 does not meet 7.18.1.”
Matterhorn Protocol 1.1, checkpoint 28, index 28-006, section UA1:7.18.2-1. Software can decide this one on its own.
What a screen reader actually does
An unknown annotation type with no description is skipped.
What “undefined in ISO 32000” means
Every annotation has a /Subtype. ISO 32000 defines a fixed list of them: /Text, /Link, /FreeText, /Line, /Square, /Circle, /Polygon, /PolyLine, the text markups, /Stamp, /Caret, /Ink, /Popup, /FileAttachment, /Sound, /Movie, /Widget, /Screen, /PrinterMark, /TrapNet, /Watermark, /3D, /Redact, and in PDF 2.0 /RichMedia and /Projection. A plug-in or a specialist markup application can write a subtype of its own:
10 0 obj
<< /Type /Annot
/Subtype /ACMEReviewMark % not in ISO 32000
/Rect [ 400 735 520 755 ]
/F 4
/AP << /N 11 0 R >> % how it looks
>> % no /Contents, no /StructParent
endobjA viewer that does not know the type knows nothing about what it means. PDF/UA-1 clause 7.18.2 does not forbid it. It says such an annotation still has to meet the general annotation requirements of 7.18.1: be part of the structure tree, inside an <Annot> element, and carry a description. Condition 28-006 is a custom-subtype annotation that does not.
What a screen-reader user gets
Nothing, usually. With no structure element the annotation is not in the reading order, and with no description there is nothing to say about it except its type, which here is a name a vendor made up. Whatever the mark was for (checked, query, superseded) is visible on the page and absent from the reading.
Where it comes from
Plug-ins and specialist applications that add their own kind of mark: a review stamp, a measurement marker, a workflow flag. The software that defines the mark knows what it means; nothing obliges it to write that meaning down, or to put the mark in the structure tree, and a file made before anyone thought about tagging gets neither.
How to check it free
qpdf. Write the readable form and look at the /Subtype of every annotation:
qpdf --qdf --object-streams=disable plan.pdf readable.pdfSearch for /Type /Annot and compare each subtype with the list above.
veraPDF’s PDF/UA-1 profile has no rule aimed at unknown subtypes. Its general annotation rules under clause 7.18.1, nesting in <Annot> and a description in /Contents or /Alt, apply to every annotation, unknown types included.
Acrobat Pro’s Content panel lists each page’s annotations, and the Tags panel’s Find searches for unmarked annotations (Edit document structure with the Content and Tags panels). Adobe does not say how either presents a subtype Acrobat does not recognise.
How to fix it free
Ask the producing application first. If it can export its marks as standard annotations, or flatten them into the page, the problem goes away at source.
Tag it in Acrobat Pro. In the Tags panel, choose Find from the options menu, look for the annotation among the unmarked items, and use Tag Element with the type Annotation, the procedure Adobe documents for unmarked comments. To describe it, select the new tag, choose Properties from the options menu, and on the Tag tab type into Alternate Text. That satisfies the standard’s description rule, 28-004, but see below for what Taggart checks here.
Add /Contents by hand. In the readable qpdf file, add /Contents (Reviewer's tick: checked against survey) to the annotation dictionary, then repair the offsets and write a normal file:
fix-qdf readable.pdf > edited.pdf
qpdf edited.pdf plan-fixed.pdfWhat Taggart does
Taggart treats a subtype as defined if it is on the list above. For any other subtype, on an annotation not flagged Hidden or NoView, it checks two things and reports the first one that fails:
An annotation with the non-standard subtype /ACMEReviewMark on page 1 is not referenced from the structure tree, so it does not meet 7.18.1.
An annotation with the non-standard subtype /ACMEReviewMark on page 1 has no /Contents description, so it does not meet 7.18.1.
Two details of the check matter. It asks whether the annotation is in the structure tree, not under which element; an unknown subtype inside a <P> passes, and 28-002, which is the <Annot> rule, does not look at subtypes it does not know. And for the description it reads /Contents on the annotation, not /Alt on the element.
The structure half is repaired automatically. The repair is annotation-structure, marked safe, so Fix All Safe applies it. It creates an <Annot> element with an /OBJR to the annotation, places it where the annotation’s rectangle sits (inside the element whose content it overlaps, or before the first element below it, or at the end of the tree when there is neither, and the change log says which), and registers the annotation in the parent tree.
The description is not. Taggart does not invent one. After the structural repair, the same annotation is reported again, this time for its missing /Contents. The description has to come from a person, and the app does not yet take one for an annotation, so it goes in by hand — the /Contents edit under How to fix it free above — or in the program that made the mark. With the <Annot> element from the repair and a /Contents description both in place, this condition and 28-004 clear.
How Taggart handles it
Taggart checks for this condition automatically and reports it as a blocker, with where in the file it found it.
The fix is Place annotations in the structure tree. It is mechanical, so “Fix All Safe” applies it along with the others in one pass and lists what it changed. Your original file is never modified.
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
Are custom annotation types allowed in PDF/UA at all?
Yes. PDF/UA-1 does not ban them; it holds them to the same rules as every other annotation. They must be in the structure tree and they must be described, which is what this condition checks.
Is an /Alt on the <Annot> element enough?
For the standard's description requirement, yes: PDF/UA accepts either /Contents on the annotation or an alternative description on its element, which is condition 28-004. Taggart's check for this condition looks for /Contents on the annotation itself, so a description given only as /Alt clears 28-004 and leaves this finding open.
Which subtypes does Taggart count as defined?
The ones ISO 32000-1 lists, from Text and Link through Watermark, 3D and Redact, plus RichMedia and Projection, which came with ISO 32000-2. Any other subtype name is reported under this condition if it is missing either piece.
Does a hidden one count?
No. Taggart leaves out annotations flagged Hidden or NoView, and Popup annotations, as outside the annotation requirements. A hidden annotation is not presented to anyone, so there is nothing for a reader to miss.
Where this sits in the standards
| Standard | Reference |
|---|---|
| Matterhorn Protocol 1.1 | Checkpoint 28 (Annotations), index 28-006 |
| PDF/UA-1 (ISO 14289-1) | Clause 7.18.2-1 |
| 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 elementNon-widget, non-link annotations must sit inside an Annot structure element so they have a place in the reading order.
- 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-007 An annotation of subtype TrapNet existsTrapNet annotations are prepress artefacts and are forbidden in PDF/UA-1.
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-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 .