Importing and exporting annotations in XFDF

XFDF is an XML-based standard from Adobe XFDF (ISO 19444-1:2016) for encoding annotations and form field values. It’s compatible with Adobe Acrobat and several other third-party frameworks.

ℹ️ Note: XFDF has various limitations. In most cases, using Nutrient Instant will result in a smaller file and better synchronization.

Importing XFDF

XFDF can be imported in both operational modes.

Importing with Document Engine

Nutrient Web SDK with Document Engine supports importing annotations from an XFDF file when uploading a document via the /api/documents endpoint. Send a multipart/form-data POST request including the PDF and the XFDF file to import the annotations in the given PDF file. This will replace all existing annotations in the uploaded PDF with the annotations from the uploaded Instant JSON file. If you want to add annotations to already existing ones instead of replacing them, set keep_current_annotations to true:

Request

POST /api/documents
Content-Type: multipart/form-data; boundary=customboundary
Authorization: Token token="<secret token>"

--customboundary
Content-Disposition: form-data; name="file"; filename="Example Document.pdf"
Content-Type: application/pdf

<PDF data>
--customboundary
Content-Disposition: form-data; name="attachment"; filename="attachment.xfdf"
Content-Type: application/vnd.adobe.xfdf

<annotations data>
--customboundary
Content-Disposition: form-data; name="keep_current_annotations"

true
--customboundary--

Refer to the Nutrient Web SDK with Document Engine guides for an in-depth example.

Importing in standalone Web SDK

To import XFDF when using Nutrient Web SDK, use the Configuration#XFDF option.

In addition to the Configuration#XFDF option, you can also set the Configuration#XFDFKeepCurrentAnnotations flag. This flag will make sure annotations that are already in the source PDF are kept and not replaced with those defined in the XFDF:

PSPDFKit.load({
  document: "https://your-server.com/some/document.pdf",
  XFDF:
    `<?xml version="1.0" encoding="UTF-8"?><xfdf xml:space="preserve" xmlns="http://ns.adobe.com/xfdf/"> ..`
});

Exporting to XFDF

Export the annotations in the document in XFDF format in both operational modes. For Web SDK with Document Engine, XFDF exporting can be performed using the REST API or the client-side API. For standalone Web SDK, only the client-side API method is available.

HTTP exporting

When using Nutrient Web SDK with Document Engine, export the current annotations of a document as an XFDF file via a GET request to /api/documents/:document_id/document.xfdf. To get the current annotation of a document’s layer, send a GET request to /api/documents/:document_id/layers/:layer_name/document.xfdf:

Request

GET /api/documents/:document_id/document.xfdf
Authorization: Token token="<secret token>"
$ curl "http://localhost:5000/api/documents/abc/document.xfdf" \
   -H "Authorization: Token token=<secret token>"

Response

HTTP/1.1 200 OK
Content-Type: application/vnd.adobe.xfdf

<XFDF data>

API exporting

In both operational modes, export the XFDF file through the client-side API using the Instance#exportXFDF method:

instance.exportXFDF().then((xfdf) => {
  console.log(xfdf); // => <?xml version="1.0" encoding="UTF-8"?><xfdf xml:space="preserve" xmlns="http://ns.adobe.com/xfdf/"> ...
});

XFDF works seamlessly with the annotation API. If you want to persist annotations whenever changes are made, we recommend you use the annotations.didSave event. This event will be triggered automatically and can be configured via Configuration#autoSaveMode.

Note for users of the standalone Web SDK: Instead of saving annotations to the backend, a save operation will persist annotations in memory until they’re either exported via Instance#exportXFDF or written to the PDF document when you export it using Instance#exportPDF. Unsaved annotations won’t be exported, so as to reflect the server behavior:

instance.addEventListener("annotations.didSave", async () => {
  const xfdf = await instance.exportXFDF();
  await fetch("https://your-server.com/xfdf", {
    method: "post",
    headers: {
      "Content-Type": "application/vnd.adobe.xfdf"
    },
    body: xfdf
  });
});

Exporting annotations to XFDF via Adobe Acrobat

Adobe Acrobat can export annotations into XFDF. The export menu is part of the Comments tool and is accessed by opening the tool in the sidebar.

Access the export function by clicking the three dots and then choosing Export All To Data File.

  1. At the bottom of the page, choose Acrobat XFDF Files.

  2. Select the directory you wish to save the XFDF file to and name the file.

  3. Click save.

A successful export will result in a file with an .xfdf extension.

Importing annotations to XFDF via Adobe Acrobat

The export function is part of the Comments tool and is accessed by clicking on its icon.

Click the three dots to open the import menu, and then click Import Data File.

Highlight the .xfdf file you wish to import and click Select.

The import function completes with the annotations being placed on the document.

Adobe Acrobat error conditions

Error description Screenshot
Damaged/missing document body
Damaged/missing description tag
Missing document flag