Annotation Data Formats in iOS: XFDF vs. JSON

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

Separating annotations and form data from the underlying document

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.

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

Comparing Data Formats

XFDF Instant JSON
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 for use in third-party applications.

If you have a very specific use case, it’s also possible to use a custom data format, but this isn’t recommended.

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 forms. 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 to make it interoperable.

Instant JSON is 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, our solution for automatically synchronizing annotations from multiple concurrent users. PSPDFKit Instant is a licensable component that’s included as part of PSPDFKit Server, our solution for synchronizing documents and annotations and managing authentication.

Instant JSON can be used without licensing PSPDFKit Instant or PSPDFKit Server.

Learn more about the Instant JSON format.