How to avoid implementation dependent appearances of annotations and interactive form fields

Annotations such as notes and links belong to the most appreciated PDF features. Although they are easy to use from a user's perspective this is certainly not true from a developers perspective since it is often not clear how to render them.

In a PDF document the annotations are described in dictionaries which are attached to the corresponding page where they appear. An annotation dictionary can have an entry called appearance stream which describes how to present the annotation on the page. But this entry is optional.

The fields of interactive forms are based on widget annotations.When the contents and properties of a field are known in advance, its visual appearance can be specified by an appearance stream defined in the PDF file. In some cases, however, the field may contain text whose value is not known until viewing time. In such cases, the viewer application must construct an appearance stream dynamically at viewing time.

Furthermore, the interactive forms dictionary may contain an entry "NeedAppearances". This is a flag specifying whether to construct appearance streams and appearance dictionaries for all widget annotations in the document when the document is opened.

In general, if the appearance stream of an annotation is missing the reader has to create it on-the-fly from other entries (text, border, color, etc.) in the annotation dictionary. The PDF specification does not describe how to do it. Therefore, the appearance depends on the implementation unless the appearance stream is present.

Now, let's have a look at PDF/A. Although the PDF/A standard claims to guarantee a reliable and unambiguous presentation, appearance streams of annotations are still optional in PDF/A-1. On the other hand the color in the corresponding dictionary entries must be calibrated which certainly never was the intention. In PDF/A-2 this has been fixed as per my proposal as a delegate in the ISO working group. Appearance streams are required for all annotations and the colors used in it must be calibrated but not the colors of other dictionary entries.

The conclusion is self-evident: PDF writer software (creators, producers, interactive form tools, etc.) should always include appearance streams for annotations and interactive from fields in order to avoid unambiguous presentation.

Please let me know, whether this article was useful to you and post a comment.


  1. Now, if only Apple would get that…

    In fact, this should be part of PDF in general, and not only PDF/A-2.

    1. I agree. To find a majority in the ISO committee for this opinion would be difficult, however.