Annotation Data Formats in Linux: XFDF vs. Instant JSON


PSPDFKit Processor has been deprecated and replaced by PSPDFKit Document Engine. All PSPDFKit Processor licenses will work as before and be supported until 15 May 2024 (we will contact you about license migration). To start using Document Engine, refer to the migration guide. With Document Engine, you’ll have access to robust new capabilities (read the blog for more information).

In addition to reading and writing annotations embedded into a PDF, PSPDFKit also allows you to use external files to manage annotations.

PSPDFKit supports reading and writing annotations in the following external data file formats:

  • XFDF (XML Forms Data Format)

  • Instant JSON

For most use cases, we recommend Instant JSON because it can store deleted annotations and has built-in support for comparing (diffing) changes to annotations. This makes it ideal for synchronizing annotations to a server, or across users, devices, or sessions. Instant JSON can be [converted to XFDF][convert to xfdf].

XFDF is best suited for importing data into the system or exporting it for integration with third-party PDF applications.

Comparing Data Formats

Compatible with third-party PDF applications *
ISO-standard format
Built-in support for comparing changes
Can store deleted annotations
Syntax Verbose Minimal
File size Larger Compact
Fully documented

* Can be [converted to XFDF][convert to xfdf] for use in third-party applications.

XFDF (XML Forms Data Format)

PSPDFKit has full support for reading and writing 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 many other third-party PDF applications.

XFDF is a representation of all annotation and form data inside a PDF document at a point in time. It doesn’t have a concept of differentials (diffs) for managing changes made by multiple users annotating the same PDF simultaneously, and it cannot store deleted annotations. This makes XFDF a challenging format to use for comparing changes, managing conflicts, and synchronizing annotations across users, devices, or sessions.

Instant JSON

Instant JSON is a format we created for bringing annotations and bookmarks into a modern format while keeping all important properties to make the Instant JSON spec work with PDF. It’s not directly supported by other frameworks; however, it can be easily [converted to XFDF][convert to xfdf] to make it interoperable.

Instant JSON is [fully documented][fully documented] and supports persistent storage. It’s designed for synchronizing annotations to a server, and across users, devices, or sessions.

The Instant JSON format is used by [PSPDFKit Instant][instant], our solution for automatically synchronizing annotations from multiple concurrent users. PSPDFKit Instant is a licensable component that’s included as part of PSPDFKit Document Engine, our solution for synchronizing documents and annotations and managing authentication.

Instant JSON can be used without licensing PSPDFKit Instant or PSPDFKit Document Engine.

Learn more about the [Instant JSON][fully documented] format.