

Data Model

The final results for all LibCrowds are stored as Web Annotations. Web Annotations became a W3C standard on the 23rd February, 2017. The Web Annotation Data Model provides the following abstract:

Annotations are typically used to convey information about a resource or associations between resources. Simple examples include a comment or tag on a single web page or image, or a blog post about a news article.

The Web Annotation Data Model specification describes a structured model and format to enable annotations to be shared and reused across different hardware and software platforms. Common use cases can be modeled in a manner that is simple and convenient, while at the same time enabling more complex requirements, including linking arbitrary content to a particular data point or to segments of timed multimedia resources.

The specification provides a specific JSON format for ease of creation and consumption of annotations based on the conceptual model that accommodates these use cases, and the vocabulary of terms that represents it.

By using this structure for our final results we aim to make the crowdsourced data generated via the platform more easily reusable online and provide a way for researchers to answer specific questions via programmatic means (see the API section for details).

As we as the final results data, we use Web Annotations to store additional user-generated data, such as image tags. The various types of annotation are described further below.

Result Annotations¶

These annotations are created once a task is completed and all related contributions analysed (see the Results Analysis section for details).

Each annotation contains a motivation, which provides an indication of why it was created. The types of result Annotations produced by LibCrowds are described below.

Tagging¶

Tagging annotations are used to associate a tag with a specific target, such as a region of an image. For example, this type of annotation would be used in a IIIF Annotation project designed to mark up all of the titles on a page.

Example tagging annotation

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "https://annotations.libcrowds.com/annotations/playbills-results/ce67281d-5b2a-4bdc-ba33-cb46525d0625",
  "type": "Annotation",
  "motivation": "tagging",
  "created": "2017-08-31T04:25:28.178Z",
  "generated": "2017-08-31T04:25:28.178Z",
  "generator": [
    {
      "id": "https://github.com/LibCrowds/libcrowds",
      "type": "Software",
      "name": "LibCrowds",
      "homepage": "https://www.libcrowds.com"
    },
    {
      "id": "https://backend.libcrowds.com/api/task/42",
      "type": "Software"
    }
  ],
  "body": {
    "type": "TextualBody",
    "purpose": "tagging",
    "value": "title"
  },
  "target": {
    "source": "https://api.bl.uk/metadata/iiif/ark:/81055/vdc_100022589158.0x00007f",
    "selector": {
      "conformsTo": "http://www.w3.org/TR/media-frags/",
      "type": "FragmentSelector",
      "value": "?xywh=245,1172,1789,270"
    }
  }
}

Describing¶

Describing annotations are used for any user input that can be stored as text, such as transcriptions. For example, this type of annotation would be used in a IIIF Annotation project designed to transcribe all of the titles on a page.

Example describing annotation

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "https://annotations.libcrowds.com/annotations/playbills-results/7640ddcd-6e48-4a9c-a360-3383032593b6",
  "type": "Annotation",
  "motivation": "describing",
  "created": "018-02-08T22:15:07.152Z",
  "generated": "018-02-08T22:15:07.152Z",
  "generator": [
    {
      "id": "https://github.com/LibCrowds/libcrowds",
      "type": "Software",
      "name": "LibCrowds",
      "homepage": "https://www.libcrowds.com"
    },
    {
      "id": "https://backend.libcrowds.com/api/task/42",
      "type": "Software"
    }
  ],
  "body": [
    {
      "type": "TextualBody",
      "purpose": "tagging",
      "value": "title"
    }
    {
      "type": "TextualBody",
      "purpose": "describing",
      "value": "King Lear",
      "format": "text/plain"
    }
  ],
  "target": {
    "source": "https://api.bl.uk/metadata/iiif/ark:/81055/vdc_100022589096.0x0002b7",
    "selector": {
      "conformsTo": "http://www.w3.org/TR/media-frags/",
      "type": "FragmentSelector",
      "value": "?xywh=7,1191,1962,359"
    }
  }
}

Commenting¶

Commenting annotations are used to store comments about a target. For example, this type of annotation would be used to store any user-input provided via the notes field of a IIIF Annotation project.

Example commenting annotation

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "https://annotations.libcrowds.com/annotations/playbills-results/97b63351-c1a4-456e-8871-b299aa684639",
  "type": "Annotation",
  "motivation": "commenting",
  "created": "2017-09-05T11:07:32.273Z",
  "creator": {
    "id": "https://www.libcrowds.com/api/user/1",
    "type": "Person",
    "name": "Joe Bloggs",
    "nickname": "joebloggs"
  },
  "generated": "2017-09-05T11:07:32.273Z",
  "generator": [
    {
      "id": "https://github.com/LibCrowds/libcrowds",
      "type": "Software",
      "name": "LibCrowds",
      "homepage": "https://www.libcrowds.com"
    },
    {
      "id": "https://backend.libcrowds.com/api/task/42",
      "type": "Software"
    }
  ],
  "body": {
    "type": "TextualBody",
    "purpose": "commenting",
    "value": "Not a playbill",
    "format": "text/plain"
  },
  "target": "https://api.bl.uk/metadata/iiif/ark:/81055/vdc_100022589158.0x000094"
}

Image Tag Annotations¶

As the title suggests, image tag annotations are used to associated a tag with an image. All image tag annotations are generated with the tagging motivation.

Tagging¶

Tagging annotations are used to associate a tag with an image. They contain enough data for them to later be used to build an image album, or potentially a IIIF manifest.

The target's source contains a the image URI and the target's scope contains the IIIF manifest URI, if available. If a IIIF manifest URI was not available at the time of tagging (e.g. if the image being tagged was from another source, such as Flickr) then the target will contain only the URI of the image.

Example tagging annotation

{
  "@context": "http://www.w3.org/ns/anno.jsonld",
  "id": "https://annotations.libcrowds.com/annotations/playbills-image-tags/ce67281d-5b2a-4bdc-ba33-cb46525d0625",
  "type": "Annotation",
  "motivation": "tagging",
  "created": "2017-08-31T04:25:28.178Z",
  "creator": {
    "id": "https://www.libcrowds.com/api/user/1",
    "type": "Person",
    "name": "Joe Bloggs",
    "nickname": "joebloggs"
  },
  "generated": "2017-08-31T04:25:28.178Z",
  "generator": {
    "id": "https://www.libcrowds.com",
    "type": "Software",
    "name": "LibCrowds",
    "homepage": "https://www.libcrowds.com"
  },
  "body": {
    "type": "TextualBody",
    "purpose": "tagging",
    "value": "foo"
  },
  "target": {
    "scope": "https://api.bl.uk/metadata/iiif/ark:/81055/vdc_100022589060.0x000002/manifest.json",
    "source": {
      "id": "https://api.bl.uk/image/iiif/ark:/81055/vdc_100022589059.0x00004b/full/max/0/default.jpg"
    }
  },
}

Full model¶

The following tables detail how the LibCrowds platform implements Web Annotations.

Property	Type	Description
@context	String	The JSON-LD context (always http://www.w3.org/ns/anno.jsonld)
id	String	An IRI where the Web Annotation can be retrieved
type	String	The class for Web Annotations (always 'Annotation')
motivation	String	The relationship between the Annotation and a Motivation
created	String	The time at which the Annotation was created
creator	Object	The creator of the Annotation
generated	String	The time at which the Annotation serialization was generated
generator	String or Object	The agent responsible for generating the serialization of the Annotation (typically software)
modified	String	The time at which the Annotation was modified, after its creation
target	String or Object	The target of the Annotation
body	List or Object	The relationship between the Annotation and its Body

creator¶

The creator contains information about the person that created the annotation. This is currently only used for commenting annotations, which are created by a single authenticated user.

Property	Type	Description
id	String	An IRI that identifies the person
type	String	The type of the creator (always 'Person')
name	String	The full name of the person
nickname	String	The nickname of the person

Example of a creator

{
  "id": "https://www.libcrowds.com/api/user/1",
  "type": "Person",
  "name": "Joe Bloggs",
  "nickname": "joebloggs"
}

generator¶

The generator contains information about the software used to generated the annotation, which in this case is LibCrowds. For results Annotations, a second generator is added to identify the result to which the Annotation is linked.

Property	Type	Description
id	String	An IRI that identifies the software (always main LibCrowds GitHub repository )
type	String	The type of the generator (always 'Software')
name	String	The name of the generator (always 'LibCrowds')
homepage	String	The base URL that the software was running from when the annotation was generated

Example of a generator

[
  {
    "id": "https://github.com/LibCrowds/libcrowds",
    "type": "Software",
    "name": "LibCrowds",
    "homepage": "https://www.libcrowds.com"
  },
  {
    "id": "https://backend.libcrowds.com/api/task/42",
    "type": "Software"
  }
]

target¶

The target identifies the resource being annotated. For instance, this may be an image, in which case the target will be a URL. Or, the target may be a specific region of an image, in which case the target will be an object with the properties below.

Property	Type	Description
source	String or Object	The URL of the resource being annotated
selector	Object	The relationship between the resource and a selector
selector.type	String	The class of the selector (always 'FragmentSelector')
selector.conformsTo	String	The fragment selector syntax IRI (always http://www.w3.org/TR/media-frags/)
selector.value	String	The contents of the fragment component
scope	String	A resource that provides the scope for the context of an Annotation

Example of a media fragment target

{
  "target": {
    "source": "http://example.org/iiif/book1/canvas/p1",
    "selector": {
      "type": "FragmentSelector",
      "conformsTo": "http://www.w3.org/TR/media-frags/",
      "value": "xywh=100,100,100,100"
    }
  },
  ...
}

body¶

The body contains information that describes the target, for example, a tag or a transcription.

Tags¶

Tags are used to associate some label, generally as plain text, with the target.

Property	Type	Description
type	String	The type of the resource (always 'TextualBody')
purpose	String	The reason for the inclusion (always 'tagging')
value	String	The tag text

Example of a tag

{
  "type": "TextualBody",
  "purpose": "tagging",
  "value": "title"
}

Semantic Tags¶

Semantic Tags are used to link the annotation to a URI that identifies a specific resource.

Property	Type	Description
type	String	The type of the resource (always 'SpecificResource')
purpose	String	The reason for the inclusion (always 'classifying')
source	String	A URI identifying the specific resource

Example of a semantic tag

{
  "type": "SpecificResource",
  "purpose": "classifying",
  "source": "http://purl.org/dc/terms/title"
}

Descriptions¶

Descriptions are used to describe the target in plain text.

Property	Type	Description
type	String	The type of the resource (always 'TextualBody')
purpose	String	The reason for the inclusion (always 'describing')
format	String	The format of the description (always 'text/plain')
value	String	The description text

Example of a description

{
  "type": "TextualBody",
  "purpose": "describing",
  "format": "text/plain",
  "value": "The Merchant of Venice"
}

For details on how to query the Annotations see the API documentation.