.PDF File Format – Interactive features

Annotations

An annotation is a dictionary tied to a rectangle on a page, listed in the page’s Annots. Every annotation can have these keys:

Markup annotations, the comment types, also have T (author, 1.1), Popup (1.3), CA (opacity, 1.4), RC (rich text, 1.5), CreationDate, IRT (the annotation it replies to) and Subj (1.5), RT and IT (reply type and intent, 1.6), and ExData (1.7).

Annotation types

A Redact annotation only marks content. Redaction is done when a program applies it, removes the content from the content streams and replaces the annotation with its overlay; a file that keeps the annotation still holds the content.

Appearance streams

How an annotation looks is a form XObject, its appearance stream, in the AP dictionary: N (normal, required when there is AP), R (rollover, mouse over it) and D (down, pressed). Each is a stream or, for fields with states such as a check box, a dictionary of streams by state name, with AS naming the current one, for example /Yes or /Off. The form’s BBox is mapped onto the annotation’s Rect. From PDF 2.0 an appearance stream is required for every annotation with a rectangle that is not empty, except Popup, Link and a few others; before that a viewer drew many types itself from their keys.

Annotation flags

Actions

An action is a dictionary with Type Action, S, its type, and Next, an action or array of actions to run after it. Actions are run by links, bookmarks, OpenAction, and the additional actions (AA) of the document, pages, annotations and fields, triggered by events such as opening a page, entering a field or changing its value.

SetState and NOP are obsolete early actions that should not be written. Viewers usually ask before Launch and may refuse it.

JavaScript

A JavaScript action, from PDF 1.3, holds its script in JS, a text string or a stream. Scripts run from document-level entries in the name dictionary’s JavaScript tree when the document opens, from OpenAction, and from field and page events. They use Adobe’s JavaScript for Acrobat API, which is described by Adobe, not by ISO 32000. Viewers other than Acrobat run few or none of them, and many security tools flag them. PDF/A forbids JavaScript.

Interactive forms (AcroForm)

The catalog’s AcroForm dictionary, from PDF 1.2, holds the form:

An XFA form describes the form in XML, which Acrobat builds and lays out itself. A file can be an AcroForm with XFA added, or, with NeedsRendering, a “dynamic” XFA form whose pages are only a placeholder. Most viewers other than Acrobat ignore XFA.

Fields

Fields form a tree, through Kids and Parent. A field’s full name joins the partial names T of it and its ancestors with dots: address.street. A field with one visible part is often merged with its widget annotation into one dictionary.

A button with neither Radio nor Pushbutton set is a check box.

Digital signatures

A signature, from PDF 1.3, is a signature field (FT Sig) whose value V is a signature dictionary. The signature covers the whole file as it was when signed, except the signature’s own bytes.

Each new signature is added by an incremental update, so earlier signatures still cover their own versions of the file. A reader checks a signature by hashing the bytes in ByteRange and verifying Contents against the hash; it should also check that ByteRange covers the whole file apart from Contents, and report what later updates changed.

• DocMDP (1.5): a certification signature, referred to from the catalog’s Perms, whose transform parameters P say what may change afterwards: 1 nothing, 2 filling in forms and signing (the default), 3 also annotations.
• FieldMDP (1.5): a signature that locks certain fields.
• Document security store (2.0, earlier an ETSI extension to 1.7): the catalog’s DSS holds Certs, OCSPs and CRLs, streams of certificates and revocation data, and VRI, which ties them to each signature, so that a signature can be checked long after the certificates have expired. With document timestamps, this is what PAdES long-term validation uses.

Embedded files and file specifications

A file specification names a file. It may be a string, or a dictionary:

The embedded file itself is a stream of Type EmbeddedFile, from PDF 1.3, with Subtype, its MIME type written as a name (/application#2Fxml), and Params: Size, CreationDate, ModDate and CheckSum, an MD5 of the data. Files are attached to the document through the name dictionary’s EmbeddedFiles tree, to a page through FileAttachment annotations, and, from PDF 2.0 (and PDF/A-3 before it), to the document, a page or any object through AF, associated files. An invoice in the Factur-X or ZUGFeRD form is a PDF/A-3 with its XML data attached this way.

PDF 2.0 also defines an unencrypted wrapper: a PDF whose only real content is an encrypted PDF embedded with AFRelationship EncryptedPayload, so that a reader that cannot decrypt it can still show a cover page.

Multimedia

• Sound and Movie annotations and actions (1.2) – the first media support, deprecated in PDF 2.0.
• Renditions (1.5) – a Screen annotation and Rendition actions play media clips, chosen by criteria such as the bit rate or the language, with players named by MIME type.
• 3D (1.6) – a 3D annotation holds a 3D stream of U3D (ECMA-363), or in later files PRC (ISO 14739-1), with views, lighting and cross-sections.
• Rich media (2.0, earlier as Adobe’s extension level 3) – a RichMedia annotation holds video, sound or 3D content and the settings for playing it. In Acrobat it played SWF through Flash, which has gone.