Revision History

Name	Date	Reason for Change	Version
Practical use	November 12th, 2023	Initial ideas for how to use annotations	0.0
Using Annotation Services	November 15th, 2023	Document revised after some feedback by the instructor	0.1 - draft

The parent document being updated, this document will also be updated. So 0.1 is being drafted now.

Please be warned that this document is subject to change.

By example

A sample annotation will be used as an example to illustrate the data entry steps. Check the final annotation about a need entry:

sample_annotation_data = {
    "context": "http://www.w3.org/ns/anno.jsonld",
    "type": "Annotation",
    "id": "http://dapp.org/annotated",
    "motivation": ["commenting", "highlighting"],
    "body": [
        {"type": "TextualBody", "value": "Elbiseler soğuk hava koşulları düşünülerek edinilmelidir. Çocuk giysilerine öncelik verilebilir"},
        {"type": "ImageBody", "format": "image/jpeg", "url": "http://dapp.org/9102211123.jpg"},
        {"type": "URL", "url": "https://www.defacto.com.tr/takim-2812969"},
    ],
    "target": [
        {"source": "http://dapp.org/annotated/needs/", "data_selector": {"start": 0x653ff479d6b8de0728e51b15, "end": 0x653ff479d6b8de0728e51b15}},
    ],
}

What is what?

In this example the need with id 0x653ff479d6b8de0728e51b15 is annotated.

It shows that, the user annotated the need with

• The textual information that "Elbiseler soğuk hava koşulları düşünülerek edinilmelidir. Çocuk giysilerine öncelik verilebilir"
• An image (maybe a photo) possibly about the need and needy people
• A URL, to give a more detailed impression about the clothings in question.

System level

How to annotate

The annotation is manually added via the UI function residing in "needs" entry pages. The user selected to annotate the need 0x653ff479d6b8de0728e51b15 and

• entered a text
• uplaodad an image
• entered a URL

The frontend makes an API call with these parameters:

• endpoint: annotations/needs/
• id
• annotation text
• image
• URL

The backend creates the annotation data with these values:

target_entity_type: Needs
target_id: 0x653ff479d6b8de0728e51b15
annotation_body: 
{
    "context": "http://www.w3.org/ns/anno.jsonld",
    "type": "Annotation",
    "id": "http://dapp.org/annotated",
    "motivation": ["commenting", "highlighting"],
    "body": [
        {"type": "TextualBody", "value": "Elbiseler soğuk hava koşulları düşünülerek edinilmelidir. Çocuk giysilerine öncelik verilebilir"},
        {"type": "ImageBody", "format": "image/jpeg", "url": "http://dapp.org/9102211123.jpg"},
        {"type": "URL", "url": "https://www.defacto.com.tr/takim-2812969"},
    ],
    "target": [
        {"source": "http://dapp.org/annotated/needs/", "data_selector": {"start": 0x653ff479d6b8de0728e51b15, "end": 0x653ff479d6b8de0728e51b15}},
    ],
}

How to view

The UI makes an API call with these:

• endpoint: annotations/needs/
• id

and retrieves the annotation as the given json:

annotation_body: 
{
    "context": "http://www.w3.org/ns/anno.jsonld",
    "type": "Annotation",
    "id": "http://dapp.org/annotated",
    "motivation": ["commenting", "highlighting"],
    "body": [
        {"type": "TextualBody", "value": "Elbiseler soğuk hava koşulları düşünülerek edinilmelidir. Çocuk giysilerine öncelik verilebilir"},
        {"type": "ImageBody", "format": "image/jpeg", "url": "http://dapp.org/9102211123.jpg"},
        {"type": "URL", "url": "https://www.defacto.com.tr/takim-2812969"},
    ],
    "target": [
        {"source": "http://dapp.org/annotated/needs/", "data_selector": {"start": 0x653ff479d6b8de0728e51b15, "end": 0x653ff479d6b8de0728e51b15}},
    ],
}