BASALT · JOURNAL

What a PDF annotation is, and why comments vanish in other apps

2026-10-30 · what is a pdf annotation

A PDF annotation is an object attached to a page that sits on top of the page content instead of being part of it. Sticky notes, highlights, typed text boxes, drawn shapes, links and form fields are all annotations. Because each one is a separate object with its own settings, a reader can show it, hide it or leave it off the printout without changing the page underneath.

That's also why comments seem to vanish. The page is the same in every app, but each app decides which annotations to draw, and a flag or a missing drawing inside the annotation can make one reader skip it. The same objects also carry the name of whoever made them, which is worth knowing before you share the file.

Where annotations live in the file

Each page dictionary can have an /Annots entry, an array of references to annotation objects. If the entry is missing, the page has none. The page's visible content, which is a separate stream of drawing instructions, isn't touched by any of them.

An annotation dictionary holds what the reader needs to treat it as a thing you can click, move and delete. The usual entries are:

• /Subtype: the kind. Text (a sticky note), FreeText (a text box), Highlight, Underline, StrikeOut, Square, Circle, Ink (freehand drawing), Link, Widget (a form field), FileAttachment, Popup and Redact (a redaction mark).
• /Rect: the rectangle on the page that the annotation occupies.
• /Contents: the text, such as the comment itself.
• /T: the title, which by convention is the author's name, on markup annotations.
• /M: the modification date.
• /AP: the appearance stream, a small drawing that says how the annotation looks.
• /F: a set of flags that control display and printing.

Form fields are annotations too, with the subtype Widget. A field's answer is stored as data in the field, not in the page's content, which is worth knowing when you fill a PDF form on a Mac and send it on: the typed value travels with the file.

Why comments don't show in another app

Four causes cover almost every case.

First, the flags. In /F, each bit switches something on: bit 1 is Invisible, bit 2 Hidden, bit 3 Print, bit 6 NoView, bit 7 ReadOnly and bit 8 Locked. As numbers, Hidden is 2, Print is 4 and NoView is 32. An annotation with the Hidden bit set is not drawn or printed, and with NoView set it isn't shown on screen, though it can still print. An annotation without the Print bit never prints, a common reason comments are missing from a printout.

Second, the appearance stream. Many annotations carry an /AP entry that draws them, and a reader that relies on it shows the annotation exactly as the author saw it. When a file has no /AP, a reader must draw the annotation itself from /Rect, /Contents and its type, and different readers do that differently. One app may draw a note icon where another draws nothing.

Third, viewer settings. Many readers have a switch to show or hide comments, and some hide popup notes until you click the icon. A comment can be there and simply not in view.

Fourth, flattening. When an app flattens a file, the annotations are drawn into the page content and the objects are discarded. Printing to a new PDF usually does the same to whatever annotations the print includes. The marks show everywhere afterward, but they can't be edited, and the comment text and author usually go with the objects. Flattening a PDF on a Mac explains what survives.

How to see them on a Mac

Preview is the simplest check. Open the file, choose Tools > Show Inspector, and open the Annotations pane. Apple describes it as showing annotations made to a PDF. The list has the columns Type, Author, Date and Page. Check this pane for reviewers' names.

For a look at the structure, install qpdf with brew install qpdf. It only reads here. Make an expanded copy first, because annotation dictionaries can sit inside compressed object streams in PDF 1.5 and later files:

qpdf --qdf --object-streams=disable document.pdf expanded.pdf

Then count the annotations by kind:

grep -a -o -E '/Subtype */(Text|FreeText|Highlight|Underline|StrikeOut|Square|Circle|Ink|Link|Widget|FileAttachment|Popup|Redact)\b' expanded.pdf | sort | uniq -c

Each line is a count and a subtype. A Popup is the window that goes with a note, so notes often come in Text and Popup pairs. The count is of annotation objects in the file, which can be more than a page lists: on macOS 15, one note added through PDFKit came out as two Text and two Popup objects, while the page itself listed one of each. Links and form fields are annotations as well, so a count above zero doesn't mean anyone commented.

To read the details, print the lines that name people and dates:

grep -a -E '^ */(T|M|F|Contents) ' expanded.pdf

Lines such as /Contents 9 0 R are a page pointing to its drawing instructions, not a comment. In a test file with two notes, each annotation showed its text, a /T reviewer name and an /M date. One had /F 4 (Print only) and the other /F 2 (Hidden). The hidden note was still in the file with its author and date, though a reader that honors the flag won't draw it. Use qpdf --show-object= followed by an object number to print any single annotation as it is stored.

Reviewers' names and dates travel with the file

A PDF that went through review can carry a name and a time for every comment: the /T entry and the /M entry on each markup. They aren't in the document properties, so removing the author from the metadata leaves them in place. The same goes for notes that were deleted from view but not from the file, such as hidden ones above.

Before you send a file outside your organization, look at the Annotations pane, and remove what shouldn't leave. Removing comments and annotations from a PDF covers the options. Drawing a black box as an annotation is not redaction, because the text under it is still there; the black box redaction myth shows why.