Skip to content
Annotorious

Annotation

The Annotation interface represents an annotation in Annotorious.

interface Annotation {
  id: string;
  target: AnnotationTarget;
  bodies: AnnotationBody[];
  properties?: {
    [key: string]: any;
  }
}

The Annotorious model aligns closely with the W3C Web Annotation Data Model, but has a few key differences and simplifications which are explained in detail in this guide.

Example

Here’s an example of a typical annotation object:

{
  id: '97d01785-bdc3-46ec-94d6-c03700c72d7c',
  bodies: [
    {
      id: '5883e985-5b62-412b-b114-471b8b77c48d',
      annotation: '97d01785-bdc3-46ec-94d6-c03700c72d7c',
      purpose: 'commenting',
      value: 'This is an interesting area!',
      creator: {
        id: 'aboutgeo',
        name: 'Rainer'
      },
      created: new Date('2023-08-23T10:30:00Z')
    }
  ]
  target: {
    annotation: '97d01785-bdc3-46ec-94d6-c03700c72d7c',
    selector: {
      type: 'RECTANGLE',
      geometry: {
        x: 100,
        y: 100,
        w: 100,
        h: 50
      }
    },
    creator: {
      id: 'aboutgeo',
      name: 'Rainer'
    },
    created: new Date('2023-08-23T10:30:00Z')
  }
};

Properties

id

  • Type: string

A unique identifier for the annotation. Note that Annotorious will automatically insert a UUID if you supply annotations without ID to the loadAnnotations, setAnnotations or addAnnotation methods.

target

Describes the part of the image that is being annotated.

bodies

An array of bodies associated with this annotation. Bodies carry the payload of the annotation, such as comments, tags, or other metadata.

properties

  • Type: { [key: string]: any }
  • Optional

An object that can hold any custom properties you want to associate with the annotation.

AnnotationTarget

The AnnotationTarget interface represents the part of the image being annotated.

interface AnnotationTarget {
  annotation: string;
  selector: AbstractSelector;
  creator?: User;
  created?: Date;
  updatedBy?: User;
  updated?: Date;
}

annotation

  • Type: string

For the purpose of internal state management, Annotorious records the ID of the parent annotation in this field. Note that Annotorious will fill this field automatically if you provide an AnnotationTarget without an annotation field through the loadAnnotations, setAnnotations or addAnnotation methods.

selector

  • Type: Shape

Describes the exact area of the image being annotated. The structure of the selector depends on the shape type (e.g., rectangle, polygon).

creator

  • Type: User
  • Optional

The creator of this annotation target.

created

  • Type: Date
  • Optional

The timestamp of the target’s creation.

updatedBy

  • Type: User
  • Optional

The user who last updated this annotation target.

updated

  • Type: Date
  • Optional

The timestamp the annotation target was last updated.

AnnotationBody

The AnnotationBody interface represents a piece of content associated with an annotation.

interface AnnotationBody {
  id: string;
  annotation: string;
  type?: string;
  purpose?: typeof PurposeValues[number] | string;
  value?: string;
  creator?: User;
  created?: Date;
  updatedBy?: User;
  updated?: Date;
}

id

  • Type: string

A globally unique UUID for the body.

annotation

  • Type: string

For the purpose of internal state management, Annotorious records the ID of the parent annotation in this field. Note that Annotorious will fill this field automatically if you provide an AnnotationBody without an annotation field through the loadAnnotations, setAnnotations or addAnnotation methods.

type

  • Type: string
  • Optional

The type of the body content (e.g., TextualBody).

purpose

The purpose of the body. Can be one of the predefined purposes, or any custom string.

value

  • Type: string
  • Optional

The content of the body (e.g. a comment text or tag).

creator

  • Type: User
  • Optional

The creator of this annotation body.

created

  • Type: Date
  • Optional

The timestamp of the body’s creation.

updatedBy

  • Type: User
  • Optional

The user who last updated this annotation body.

updated

  • Type: Date
  • Optional

The timestamp the annotation body was last updated.

Purpose

You can use any string of your choice for the purpose field of the AnnotationBody. However, it is recommended to use the purpose values predefined in the W3C model for better interoperability with other systems.

For convenience, Annotorious provides IDE auto-complete support for these standard purposes:

const purposes =[
  'assessing',
  'bookmarking',
  'classifying',
  'commenting',
  'describing',
  'editing',
  'highlighting',
  'identifying',
  'linking',
  'moderating',
  'questioning',
  'replying',
  'tagging'
];