Skip to main content
Version: v2026.0.0

Annotations

Annotations are overlays that users place on document pages — sticky notes, highlights, stamps, redactions, and more. They are stored separately from the document binary: the original document is never modified. This is a deliberate architectural choice driven by regulatory requirements — in many industries (legal, finance, healthcare), preserving the original document exactly as received is a compliance obligation. Separating annotations from the document ensures the source content remains intact and auditable, while user markup lives in its own storage layer.

The XFDF standard​

ARender uses Adobe's XFDF (XML Forms Data Format) as its annotation serialization format. Every storage backend, the REST API, and the viewer all speak XFDF. This ensures interoperability with PDF-ecosystem tools and standards compliance.

An XFDF document wraps a list of annotation elements, each tied to a page. Here is a real example of a sticky note annotation:

<?xml version="1.0" encoding="UTF-8"?>
<xfdf xmlns="http://ns.adobe.com/xfdf/" xml:space="preserve">
  <annots>
    <text page="0" color="#FFFF00" date="D:20120411132756+02'00'"
      name="f96e338a-fad5-437a-8e5e-7424553c1632"
      rect="243.0695,133.3178,263.0695,151.3178" title="Dietrich.Roeben"
      creationdate="D:20120411132612+02'00'" opacity="1"
      subject="Sticky Note" icon="Comment">
      <contents-richtext>
        <body xmlns="http://www.w3.org/1999/xhtml"
          xfa:APIVersion="Acrobat:9.0.0" xfa:spec="2.0.2"
          xmlns:xfa="http://www.xfa.org/schema/xfa-data/1.0/">
          <p dir="ltr">
            <span style="font-size:10.0pt;color:#000000">
              Please make reference to the corporate document.
            </span>
          </p>
        </body>
      </contents-richtext>
      <popup page="0" rect="243.0695,-28.6816,409.9782,151.3178" open="yes"/>
    </text>
  </annots>
</xfdf>

Key attributes common to all annotation types: page (0-indexed page number), name (unique UUID), rect (bounding box coordinates), title (author), date/creationdate (timestamps), color, and opacity.

Annotation types​

Annotations fall into three broad categories:

CategoryTypes
TextualSticky note, highlight, strikeout, underline, freetext
ShapesStamp, line, square, circle, polygon, polyline, ink (freehand)
SpecialRedaction, link, bookmark

Each type carries its own set of properties (color, opacity, position, contents, etc.). See the annotation types reference for a complete list with property details.

Redaction​

Redaction annotations look like regular annotations in the XFDF layer, but they are architecturally distinct: they interact with document rendering, content streams, and authorization in ways that other annotation types do not. For this reason, redaction is covered in its own concept page.

See Redaction for the full conceptual model.

Last updated on