Annotation Providers

The PSPDFAnnotationProvider protocol defines methods for getting and setting annotations. PSPDFKit is structured in a way that a document can have multiple such providers. Each document has one or more instances of PSPDFDocumentProvider, each of which has one PSPDFAnnotationManager which, in turn, contains one or multiple annotation providers.

By default, the annotationProviders array simply contains the fileAnnotationProvider. This provider will parse the PDF and load annotations from it, and it will also handle saving back into the PDF, subject to the value of annotationSaveMode.

The file annotation provider also handles our internal, NSCoder-based format for saving and loading annotations. This is an internal file format and it should not be used for long-term storage of annotations. PSPDFKit usually supports loading and saving using this format at least one version back. So, for example, v4 can load v3 but not v2 nor v5.

Transferring annotations to other clients

Annotations are only really great if they can be shared across multiple clients. For that, there are several options available.


PSPDFKit Instant is our in-house syncing solution for seamless collaboration for PSPDFKit-powered apps. It takes care not only of near-realtime annotation syncing, but also manages file download and other metadata such as bookmarks (Coming shortly after the 1.0 release). Instant is highly optimized for PSPDFKit and uses a deep API integration, faster, better and more reliable than anything you can achieve via writing your own code.


Annotations can be exported to JSON and imported back from it at a later time. Use the PSPDFJSONAdapter class with JSONDictionaryFromModel: to convert a PSPDFAnnotation object to a JSON dictionary, and convert it back using annotationFromJSONDictionary:documentProvider:error: on PSPDFAnnotation. Please take a look at "Exporting/Importing to/from JSON" for more details.

Please note that the current JSON format (as of 6.0) is iOS specific and not compatible with PSPDFKit for Web or Android. We're working on a better, cross platform format dubbed "Instant JSON" coming in a future update that is compatible with all platforms (Q4 2017)


XFDF is an XML-like standard from Adobe XFDF for encoding annotations and forms (see XFDF Overview). It is compatible with Adobe Acrobat and several other 3rd-party frameworks. PSPDFKit supports both reading and writing XFDF and also offers a PSPDFXFDFAnnotationProvider subclass that will save/load annotations to/from XFDF automatically. There are several examples in PSPDFCatalog and in our Guides that show the exact usage. This can be used in combination with PSPDFAESCryptoInputStream and PSPDFAESCryptoOutputStream to build an encrypted annotation store. XFDF is problematic for binary attachments such as sound annotations and images, which are saved inline and might make the file very large.


The PSPDFAnnotationProvider protocol can also be implemented to have a fully custom saving and loading. This is an advanced method and we recommend using PSPDFKit Instant instead, however if you have a very specific use case, take a look at the PSPDFContainerAnnotationProvider subclass. The latter implements several of the harder-to-get-right details of the annotation provider protocol. It's not recommended to use the annotation provider protocol directly.