Skip to main content

Annotations

Annotations are overlays that users place on document pages — sticky notes, highlights, stamps, 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)
SpecialLink, 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.

Last updated on