Sharing Annotations with Instant JSON

With today’s releases, we’re introducing a new, open JSON format that is supported on all platforms. Instant JSON is our approach to bringing annotations into a sane format while ensuring full compatibility with the PDF format. It is fully documented and backward compatible.

PSPDFKit Instant or Instant JSON?

Instant is our real-time, multi-user sync solution. It works across all our platforms and is the perfect technology if you’re building an app where protecting against data loss, having your data in sync, and/or allowing multiple users to work on the same document is important (i.e. an app for collaborating during board meetings).

We’ve engineered Instant to work reliably, even when you’re on a slow or flaky network connection. Additionally, network usage is highly optimized and documents can still be edited even when a user is offline. If you add images or stamps, they are treated as separate assets and fetched separately, so that someone adding large images doesn’t block the sync process.

Instant uses our own PSPDFKit Server for coordination and storage. It’s designed for easy deployment either on-premises or to any of the major cloud providers.

We are continually improving the Instant SDK, and new features are added with almost every release. Advanced features, such as detailed audit logging, document encryption, and presence (i.e. the ability to see if somebody else is also looking at the document) are already planned for 2018.

Instant JSON

Not every use case requires Instant’s reliability, file management, multi-user syncing/merging, or audit logging. As such, we built Instant JSON for cases where there’s no central server, or where annotations do not need to be shared between different users. Instant JSON collects any and all changes to a PDF (including annotation additions, edits, and deletions) and can apply this changeset to a PDF stored on a different device without suffering any data loss.

Instant JSON needs to be applied before the document is presented, as it’s not designed to allow real-time updates.

PDF changes such as annotations are stored by Instant JSON in a separate JSON file. This means that a PDF document will only need to be transferred once and all changes will be added as an overlay to the existing PDF. This approach significantly reduces bandwidth, since you only need to transfer the JSON file instead of the complete PDF.

Instant JSON comes with a detailed specification, including Flow type declarations.

iOS JSON Deprecation

PSPDFKit for iOS includes a way to serialize annotations and form objects to JSON. This format is unique to the iOS platform and serializes objects in a way that is very close to how they are represented in Objective-C. It’s a moving format and, as such, not designed for long-term storage. It’s compatible with the two most recent versions of the SDK (the current and previous major releases). With the release of Instant JSON, we are deprecating our legacy iOS JSON format. Depending on your use case, we suggest considering the adoption of Instant JSON or XFDF. (XFDF is available on iOS and Android and coming to Web in Q1 2018.)


Instant JSON is available with the following releases:

Note: Older versions of PSPDFKit for Web use an older version of this JSON format. Make sure you update all products and reference our Web 2017.8 Migration Guide.