Annotation Types#

Annotation types are part of annotation template system which defines the structure the annotation template.

Annotation type object#

Each annotation type returned from the API is a JSON object with the following properties:

  • id: (read only) The ID of the annotation type.

  • name: The name of the annotation type.

  • description: The description of the annotation type.

  • owner_id: (read only) The owner ID of the annotation type. System annotation types have null owner ID.

  • extended_data: additional data of the annotation type, which is an object can contain the following properties:

    • structure: The structure of the annotation type. See Structure for details.

    • titleMask: The title mask of the annotation type. See Title mask for details.

  • publication_id: (read only) The publication ID of the annotation type.

  • persistent_url: (read only) The persistent URL of the annotation type publication.

  • created_at: (read only) The datetime when the annotation type is created.

  • updated_at: (read only) The datetime when the annotation type is updated.

  • policies: (read only) The policies applied to the annotation type for the current user. The value is an array of permission names which the current user has on the annotation type. The permission names are:

    • access: The user can view the annotation type.

    • write: The user can update the annotation type properties.

    • manage: The user can create/remove fields in the annotation type.

    • delete: The user can delete the annotation type.

Structure#

The structure defines the order and grouping of the fields in the annotation type. It is an array of objects where each object can either be a group or a field.

A group object has the value of the group name and type of group. It also has a items property which is an array of field objects.

Note

A group cannot contain another group. If the structure contains groups, the first level of the structure must be groups.

A field object has the type of field and the value which is the ID of a field in the annotation type.

Example structure with groups:

[
  {
    "type": "group",
    "value": "Group 1",
    "items": [
      {
        "type": "field",
        "value": "1"
      },
      {
        "type": "field",
        "value": "2"
      }
    ]
  },
  {
    "type": "group",
    "value": "Group 2",
    "items": [
      {
        "type": "field",
        "value": "3"
      }
    ]
  }
]

Example structure without groups:

[
  {
    "type": "field",
    "value": "1"
  },
  {
    "type": "field",
    "value": "2"
  },
  {
    "type": "field",
    "value": "3"
  }
]

Title mask#

The title mask defines how the title of an annotation using this annotation type is generated. It can be a plain text or a string with dynamic field values. To insert a field placeholder in the title mask, use the syntax {field:<field_id>}.

Example title mask:

Annotation for {field:1} - {field:2}

Get all annotation types#

GET /annotation-template/types

Get all annotation types which contain both system and user defined annotation types.

Response#

An array of annotation type objects.

Create an annotation type#

POST /annotation-template/types

Create a new annotation type.

Request#

The request body should be an annotation type object used to create a new annotation type. Read only properties will be ignored.

Response#

The annotation type object of the newly created annotation type.

Get an annotation type#

GET /annotation-template/types/{id}

Get an annotation type by its ID.

URL parameters#

  • id: The ID of the annotation type.

Response#

The annotation type object of the queried annotation type.

Update an annotation type#

PUT /annotation-template/types/{id}

Update an annotation type by its ID.

URL parameters#

  • id: The ID of the annotation type.

Request#

The request body should be an annotation type object used to update the annotation type. Read only properties will be ignored.

Response#

The annotation type object after the update.

Delete an annotation type#

DELETE /annotation-template/types/{id}

Delete an annotation type by its ID.

Warning

Deleting an annotation type will also delete all fields attached to the annotation type and all annotations using this annotation type.

URL parameters#

  • id: The ID of the annotation type.

Response#

The deleted annotation type object.

Get fields of an annotation type#

GET /annotation-template/types/{id}/fields

Get all fields of an annotation type.

URL parameters#

  • id: The ID of the annotation type.

Response#

An array of field objects of the queried annotation type.

Attach fields to an annotation type#

POST /annotation-template/types/{id}/fields/attach

Attach fields to an annotation type.

URL parameters#

  • id: The ID of the annotation type.

Request#

The request body should be an object with a property field_ids which is an array of field IDs to be attached to the annotation type.

Response#

An object with a property attached_field_ids which is an array of field IDs that have been attached to the annotation type.

Detach fields from an annotation type#

POST /annotation-template/types/{id}/fields/detach

Detach fields from an annotation type.

Warning

Detaching a field from an annotation type will also remove the field values of this field in all annotations using this annotation type.

URL parameters#

  • id: The ID of the annotation type.

Request#

The request body should be an object with a property field_ids which is an array of field IDs to be detached from the annotation type.

Response#

An object with a property detached_field_ids which is an array of field IDs that have been detached from the annotation type. It also has the property removed_field_ids which is an array of field IDs that have been removed because these fields are not attached to any annotation type.