Introduction

A user can provide a specification of required modifications to a document in an XML-based format. The following nodes are expected as part of the declaration:

&lt;?xml version="1.0"?&gt;
&lt;documentAnnotations&gt;
    &lt;pages&gt;
        &lt;page id="1" pageWidth="612" pageHeight="792"&gt;&lt;/page&gt;
    &lt;/pages&gt;
&lt;/documentAnnotations&gt;

A <pages> element can contain a number of <page> elements, each containing an arbitrary number of the <annotation> elements. Each <page> element must have the following attributes:

Name	Type	Required	Description
`id`	integer	yes	A 1-based page number; annotations that are listed as child elements of a given `<page>` are only applied to the corresponding page of the target document.
`pageWidth`	floating point	yes	Page width. This attribute is only used for positioning of annotations which use absolute coordinates (such as `<line-rectangles>` data in text_hyperlink_annotation). This value can be arbitrary, as long as absolute coordinates specified in annotations are consistent with it.
`pageHeight`	floating point	yes	Page height. This attribute is only used for positioning of annotations which use absolute coordinates (such as `<line-rectangles>` data in text_hyperlink_annotation). This value can be arbitrary, as long as absolute coordinates specified in annotations are consistent with it.

Each <page> can contain an arbitrary number of the <annotation> elements.

Each <annotation> element defines a certain modification to a page content. A specific set of attributes depends on drawType attribute of the <annotation>.

Common Attributes

Each <annotation> element supports the following attribute set:

Name	Type	Required / Default	Description
`drawType`	string	yes	One of the supported draw types (see Draw Type Descriptions below) that defines what modification should an annotation apply to a page.
`x_percent`	float	0.0	X position of a bounding rectangle, in 0-to-1 based portion of a page width.
`y_percent`	float	0.0	Y position of a rectangle, in 0-to-1 based portion of a page height.
`width_percent`	float	0.0	Width of a bounding rectangle, in 0-to-1 based portion of a page width.
`height_percent`	float	0.0	Height position of a rectangle, in 0-to-1 based portion of a page height.

The set of x_percent, y_percent, width_percent, height_percent coordinates is referred to as a “bounding rectangle” in the draw type descriptions below.

Example XML

Below is a full working sample of a redaction XML containing one annotation for the 1st page that adds a black rectangle redaction to a redacted document:

&lt;?xml version="1.0"?&gt;
&lt;documentAnnotations&gt;
    &lt;pages&gt;
        &lt;page id="1" pageWidth="612" pageHeight="792"&gt;
            &lt;annotation drawType="rectangle_filled_redact"
                x_percent="0.043" y_percent="0.028"
                height_percent="0.093" width_percent="0.128" /&gt;
        &lt;/page&gt;
    &lt;/pages&gt;
&lt;/documentAnnotations&gt;

Image Binary Data

Some annotations add images to a document. The content of such images is provided in an XML as well. To support this, a <documentAnnotations> element can have a child element <stampImages> that can include an arbitrary number of <stampImage> elements, each having two required elements:

Name	Type	Description
`imageStampId`	string	ID of an image that will be used by annotations to reference to it.
`base64format`	string	Base64-encoded binary image data; this attribute uses the same format as HTML inline image does.

Example

&lt;documentAnnotations&gt;
    &lt;pages&gt;
        &lt;page id="1" pageWidth="612" pageHeight="792"&gt;
            &lt;annotation drawType="imagestamp"
                imageStampId="sample-stamp-id-1"
                x_percent="0.043" y_percent="0.028"
                height_percent="0.093" width_percent="0.128" /&gt;
        &lt;/page&gt;
    &lt;/pages&gt;
    &lt;stampImages&gt;
        &lt;stampImage imageStampId="sample-stamp-id-1"
                    base64format="data: image/png;base64,iVBORw0K...kJggg=="/&gt;
    &lt;/stampImages&gt;
&lt;/documentAnnotations&gt;

Custom Type Definitions

Color - in all attributes below “color” type means the attribute’s value can either be a “transparent” keyword, meaning no color at all should be applied for that piece of a redaction, or an integer value that represents a 24-bit RGB value of a desired color. This type does not support HTML hex color codes, such as “#F0F8FF” or HTML color names such as “AliceBlue”.

Draw Type Descriptions

arrow

Draws a line with a triangle-shaped head. Same set of attributes, the size of an arrowhead is hard-coded and it also has the same color as the line itself. An arrowhead is drawn at the END side of the line (see dragDirection property of the line drawType).

circle_filled

Draws an ellipse that fits into a bounding rectangle. Uses the same attributes as rectangle_filled.