Importing and Exporting Annotations in Instant JSON

Annotations can be imported and exported to a document using PSPDFKit’s Instant JSON format, which keeps all the important properties of annotations and supports long-term storage. Refer to the Instant JSON documentation for more details about the format.

A single annotation JSON can be generated by passing the annotation immutable record to the PSPDFKit.Annotations.toSerializableObject() method of our public API:

// Create and convert a rectangle annotation to Instant JSON.
const annotation = new PSPDFKit.Annotation.RectangleAnnotation({
  pageIndex: 0,
  boundingBox: new PSPDFKit.Geometry.Rect({
    left: 100,
    top: 150,
    width: 200,
    height: 75
  })
});
const annotationJSON = PSPDFKit.Annotations.toSerializableObject(annotation);

// Annotation Instant JSON.
{
  v: 1,
  pageIndex: 0,
  bbox: [100, 150, 200, 75],
  opacity: 1,
  createdAt: "1970-01-01T00:00:00.000Z",
  updatedAt: "1970-01-01T00:00:00.000Z",
  isCommentThreadRoot: false,
  strokeWidth: 5,
  strokeColor: "#2293fb",
  type: "pspdfkit/shape/rectangle",
};

The annotation JSON that’s obtained can later be deserialized using the counterpart to toSerializableObject(), PSPDFKit.Annotations.fromSerializableObject():

const annotation = PSPDFKit.Annotations.fromSerializableObject(annotationJSON);

Importing Annotations in Instant JSON

Annotations in Instant JSON can be imported in both Standalone and Server-Backed operational modes. This guide covers Instant JSON importing and exporting in Standalone mode. For Server-Backed mode, please see the importing and exporting in Server-Backed guide.

If the Document Editing component is included in the license, the applyInstantJson document operation can be used to import Instant JSON via instance.applyOperations():

instance.applyOperations([
  {
    type: "applyInstantJson",
    instantJson: {
      annotations: [
        {
          bbox: [100, 150, 200, 75],
          blendMode: "normal",
          createdAt: "1970-01-01T00:00:00Z",
          id: "01F73GJ4RPENTCMFSCJ5CSFT5G",
          name: "01F73GJ4RPENTCMFSCJ5CSFT5G",
          opacity: 1,
          pageIndex: 0,
          strokeColor: "#2293FB",
          strokeWidth: 5,
          type: "pspdfkit/shape/rectangle",
          updatedAt: "1970-01-01T00:00:00Z",
          v: 1
        }
      ],
      format: "https://pspdfkit.com/instant-json/v1"
    }
  }
]);

Importing Instant JSON annotations can also be achieved without the Document Editing license component using the PSPDFKit.Configuration#instantJSON setting:

PSPDFKit.load({
  ...otherOptions,
  instantJSON: {
    annotations: [
      {
        bbox: [100, 150, 200, 75],
        blendMode: "normal",
        createdAt: "1970-01-01T00:00:00Z",
        id: "01F73GJ4RPENTCMFSCJ5CSFT5G",
        name: "01F73GJ4RPENTCMFSCJ5CSFT5G",
        opacity: 1,
        pageIndex: 0,
        strokeColor: "#2293FB",
        strokeWidth: 5,
        type: "pspdfkit/shape/rectangle",
        updatedAt: "1970-01-01T00:00:00Z",
        v: 1
      }
    ],
    format: "https://pspdfkit.com/instant-json/v1"
  }
});

Exporting Annotations in Instant JSON

Annotations that have been saved can be exported in the Instant JSON format using the instance.exportInstantJSON() API method:

instance.exportInstantJSON();