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 PSPDFKit Instant will result in a smaller file and better synchronization.

Importing XFDF

XFDF can be imported in both Server and Standalone modes.

Server-Backed Importing

PSPDFKit for Web Server-Backed 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, you can 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--

Follow the Server-Backed guides for an in-depth example.

Standalone Importing

To import XFDF when using Standalone mode, you can 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

You can export the annotations in the document in XFDF format both in Server-Backed and Standalone modes. In Server-Backed mode, XFDF exporting can be performed using the REST API or the client-side API. In Standalone mode, only the client-side API method is available.

HTTP Exporting

In Server-Backed mode, you can 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 Server-Backed and Standalone mode, you can 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 Standalone users: 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.

You can access the export function by clicking on 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 on the three dots to open the import menu, and then click on 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