What Are PDF Annotations?

This article was first published in January 2018 and was updated in June 2024.

This post will discuss what PDF annotations are, exploring which types of annotations are defined by the PDF specification. It will also look into how annotations are represented inside a PDF document. Finally, it will outline how PSPDFKit maps this representation to an easy-to-use annotation model.

Content displayed as a PDF page isn’t suitable for easy editing, but the PDF specification defines a comprehensive set of objects that can be added to PDF pages without changing the page content. These objects are called annotations, and their purpose ranges from marking up page content to implementing interactive features such as forms.

PDF viewers usually allow the creation and editing of various annotation types, e.g. text highlights, notes, lines, or shapes. Regardless of the annotation types that can be created, PDF viewers conforming to the PDF specification should also support rendering for all annotation types.

Annotation Types

The PDF specification defines two categories for annotations:

• Markup annotations that are primarily used to mark up the content of a PDF document

• Non-markup annotations that are used for other purposes — these include interactive forms and multimedia

Text Markup

The simplest types of markup annotations are text markup annotations for marking up page text. These include text highlight, underline, or strikeout annotations.

Drawing Annotations

Different annotations can be used for drawing on top of a PDF page. These include:

• Square and circle annotations for drawing squares/rectangles and circles/ellipses

• Line annotations for drawing lines

• Polygon and polyline annotations for drawing polygonal lines

• Ink annotations for completely freeform drawing connecting a list of points into Bézier curves

All of these support the usual drawing properties such as color, line thickness, fill color (for filled shapes), or line styles (e.g. dotted, dashed).

Stamp Annotations

Stamp annotations can be used when simple shapes drawn with drawing annotations aren’t sufficient — for example, when you want to draw a complex raster or vector image.

Text Annotations

Two annotation types can be used to add notes to the page:

• Text annotations for adding sticky notes

• Free-text annotations for adding a floating text box

Multimedia Annotations

Annotations can also be used to add multimedia content to the page. This includes sound annotations, movie annotations, and even 3D content.

Widget Annotations

Widget annotations are used to implement interactive forms. These include buttons, checkboxes, combo boxes, and more.

The PDF Annotation Model

A PDF document is a collection of data objects organized into a tree structure. The document tree is formed from dictionaries of key-value pairs that can contain other dictionaries as values. An example of another PDF object is a content stream that contains lists of drawing operations or binary image data.

The top-level dictionary in a PDF document contains a list of pages in the document. Each page is represented by its own dictionary that contains separate entries for page content and for annotations associated with the page. Similarly, annotations are also represented by their own dictionaries. Each annotation dictionary contains at least two keys:

• Rect specifies the rectangle where the annotation is going to be positioned on the page. This rectangle is in the PDF page coordinate system, which has its origin in the bottom-left corner of the page, with the x axis pointing to the right and the y axis pointing up. Read more in our coordinate space guide.

• Subtype specifies one of the supported annotation types.

The annotation type specifies which additional keys can be present in the annotation dictionary and which keys are required.

Below is an example of a page dictionary:

46 0 obj
<<
    /Type       /Page                       % Specifies that this dictionary defines a page.
    /Annots     [207 0 R, 208 0 R, 209 0 R] % Contains a list of references to annotation objects on this page.
    /Contents   501 0 R                     % Reference to page content stream.
    /MediaBox   [0, 0, 595, 842]            % Page dimensions.
    % Other page properties
>>

Here’s an example of a single annotation dictionary:

207 0 obj <<
    /Type       /Annot                               % Specifies that this dictionary defines an annotation.
    /Subtype    /Highlight                           % Specifies annotation type.
    /Rect       [52.9556, 728.343, 191.196, 743.218] % Annotation bounding box in page coordinates.
    /C          [1.0, 1.0, 0.0]                      % Annotation color.
>>

You can find all the details about how annotations are stored inside PDF documents in section 8.4 of Adobe’s PDF specification.

Appearance Streams

Annotations may contain properties that describe their appearance — such as annotation color or shape. However, these don’t guarantee that the annotation will be displayed the same in different PDF viewers. To solve this problem, each annotation can define an appearance stream that should be used for rendering the annotation. An appearance stream is a set of drawing commands that tells a PDF viewer precisely how to render an annotation (independent of the visual properties defined in the annotation’s dictionary). The PSPDFKit SDK allows you to parse and create appearance streams.

PSPDFKit Annotation Model

The PDF annotation model is quite complex. The PSPDFKit SDK provides a facade that exposes annotation dictionaries as regular objects of your programming language of choice. It hides implementation details and complex interactions between various annotation properties. This makes it easy for our customers to work with annotations without any prior knowledge of the PDF file format.

Additional Resources

PSPDFKit offers a wealth of resources to help you master PDF annotations. Here are a few to get you started:

• Annotation guides — Detailed guides on how to work with annotations in PSPDFKit SDKs.

• Instant JSON reference — Learn more about PSPDFKit’s serialization format for annotations and forms.

• Annotations demo — Try our annotation features with this live demo.

FAQ

Here are a few frequently asked questions about annotations.

What Are PDF Annotations?

PDF annotations are objects added to a PDF document to provide additional information or interactive elements without altering the original content. They include highlights, notes, shapes, and multimedia elements.

How Do I Annotate a PDF?

To annotate a PDF, open a document in a PDF viewer or editor, select the desired annotation tool, and apply the annotation to the document. Save the document to preserve the changes.

How Do I Annotate a PDF Programmatically?

To annotate a PDF programmatically, use the annotation editing APIs provided by PSPDFKit SDKs or import annotations in Instant JSON or XFDF formats.

What Types of Annotations Can Be Added to a PDF?

The PDF specification includes text markup annotations (highlights, underlines), drawing annotations (shapes, lines), stamp annotations, text annotations (sticky notes, text boxes), multimedia annotations (sound, video), and widget annotations (interactive forms).

Can All PDF Viewers Handle Annotations?

Most PDF viewers conforming to the PDF specification can render all types of annotations. However, the editing capabilities might vary between viewers.

What Is an Appearance Stream of a PDF Annotation?

An appearance stream is a set of drawing commands that defines how an annotation should be rendered in a PDF viewer, ensuring consistent appearance across different viewers.

Author

Tomáš Šurín Server and Services Engineer

Tomáš has a deep interest in building (and breaking) stuff both in the digital and physical world. In his spare time, you’ll find him relaxing off the grid, cooking good food, playing board games, and discussing science and philosophy.