Manage AnnotationLists

Reference: https://iiif.library.utoronto.ca/presentation/v2/#!/AnnotationList/ListByItemGet

Table of Contents

• Create an AnnotationList
• Update an AnnotationList
• Delete an AnnotationList
• View an AnnotationList
• FAQ

IIIF Reference: http://iiif.io/api/presentation/2.1/#annotation-list

Create an AnnotationList

• An annotationList can be created by sending a POST request to {identifier}/list with the required parameters.
• For example:

{
  "annotationList": {
    "@context": "http://iiif.io/api/presentation/2/context.json",
    "@id": "http://example.org/iiif/book1/list/p100",
    "@type": "sc:AnnotationList",
    "resources": [
      {
        "@type": "oa:Annotation",
        "motivation": "sc:painting",
        "resource": {
          "@id": "http://example.org/iiif/book1/res/music.mp3",
          "@type": "dctypes:Sound",
          "format": "audio/mpeg"
        },
        "on": "http://example.org/iiif/book1/canvas/p1"
      },
      {
        "@type": "oa:Annotation",
        "motivation": "sc:painting",
        "resource": {
          "@id": "http://example.org/iiif/book1/res/tei-text-p1.xml",
          "@type": "dctypes:Text",
          "format": "application/tei+xml"
        },
        "on": "http://example.org/iiif/book1/canvas/p1"
      }
    ]
  }
}

• This would create the annotationList for the identifier book1 with name p100 and also create all of its provided sub-annotations recursively.
• Each sub-annotation will have an upward link to this annotationList defined in their belongsTo field with this annotationList @id.
• The new annotationList will also have a list of @ids in its children field. This value along with the belongsTo are later used to re-construct the annotationList when viewing.
• Suppose any of the sub-annotation already exists, those objects will be updated with any new values from this request. Those objects will also be updated to have their belongsTo field to contain this new annotationList @id.

Update an AnnotationList

• An annotationList can be updated by sending a PUT request to /{identifier}/list/{name} with fields that need to be updated.
• Updating an annotationList without any of its sub-annotations in the request body would not affect its children unless the @id is being changed. In this case, an internal update will be performed on all of its children to update their belongsTo values.
• Suppose any of the sub-annotation does not exist, those objects will be created with new values from this request. Those objects will also be updated to have their belongsTo field to contain this new annotationList @id.

Delete an AnnotationList

• An annotationList can be deleted by sending a DELETE request to /{identifier}/list/{name}. Beware that this will also delete all sub-annotations under this annotationList recursively.

View an AnnotationList

• A single annotationList can be viewed at /{identifier}/list/{name}. This lists all sub-annotations that have the requested annotationList @id in their belongsTo field.

FAQ

• How to create an annotationList without an @id?

• A POST with no @id in the request body will auto-generate a unique UUID name for that object with the provided identifier.

• How to hide a specific sub-annotation when viewing an annotationList ?

• This can be achieved by sending a PUT request to the object that needs to be hidden by updating the hidden property to true.

{"annotation: {"hidden": true}}

• How to change the order of sub-annotations of a parent annotationList?
• This can be achieved by sending a PUT request to the parent annotationList with the correct order of @ids for sub-annotations.
• This would auto-update the order field of all the sub-annotations.

{"annotationList": {
 "resources": [{"@id": "id-of-annotation-1"}, {"@id": "id-of-annotation-2"}]
}}