View Source

All annotations should have titles.
We need to generate meaningful annotation titles in the following cases:
* Precreated empty annotations. These are links to annotation points based on migrated Rembrandt data. They are used to refer to AP and don't have content. See [Annotation Design#AP Names]
* Migrated remarks from Rembrandt database. These are mapped to annotations in RDF and Nuxeo forum topics.
* Manually created annotations by users in Nuxeo. Users create forum topics/posts and these are mapped to annotations in RDF


h4. Annotations creation

Precreated annotations are created just after migration. They have no description and their status is "invisible". They have new_value that corresponds to the value they have been created for. Each subject-predicate-object triple in data layer has a corresponding precreated annotation.
Title for precreated annotations is generated by Entity API based on existing MO, subject, predicate and object.

After we have all precreated (empty) annotations created, we migrate remarks. These are also annotations but they do have description (that is, the remark) and are also presented as forum topics in Nuxeo. Titles are copied from precreated annotations. Migrated remarks are mapped to annotations and are sent to Entity API via the synchronization API (notifyNewAnnotation() etc.). They have the same new_value, main, subject, predicate and title as the corresponding precreated annotation but have additionally a description and status of "original". We don't want a new annotation created but rather we want the "invisible" one updated.

This requires the following logic to be added to notifyNewAnnotation(newAnnotation): If newAnnotation.status equals "orginal" then find the "invisible" annotation and update it.

And finally, annotations may be created by users in Nuxeo. They do this by creating discussions (topics) or posts on specific data in a painting (like, date of creation etc.). The use case goes like that:
# User browses the paintings data and clicks the "D" button next to specific value. This selects the value (and subject, predicate).
# Then user selects "Create new discussion" button in the annotation pane. A title is suggested based on the title of the "invisible"/"original" annotation. User may change it.
# User may enter a new value (literal or from thesaurus). Old value is the selected value. The user may choose whether they criticise or justify it (from a dropdown).
# User clicks "Save". Topic/post is saved and is sent to Entity API via notifyNewAnnotations(). New annotation is created with status of "proposed".
# If this is reply and not a new discussion, the replyTo field is set.


h4. Annotation URIs
Annotation URIs are generated by the Entity API.
There was an idea to use Nuxeo UIDs but there are not Nuxeo UIDs for precreated annotations.
Entity API should be able to generate URIs - either using some kind of sequence, hash or UID generation.

h4. Annotation Titles
Titles are only generated when precreating annotations. In all other cases they are copied.
Titles are generated by the Entity API using MO, AP and object (new value). See [Annotation Design#AP Names].

h4. Open Issues
- Topics don't have old/new value now. We would probably need to add these fields.
- We need the "criticise"/"justify" old object disposition in Annotation.
- There are some problems with the "object" part of AP Names, which leads to "null"
-- The spec treats only the case of terminal nodes (literal or thesaurus value):
{noformat}literal or rdf:label or P1_is_identified_by.P3_has_note {noformat}
-- Two thesauri have a different property instead of P1: Places (eg rkd-plaats:antwerpen) have P87, Artists (eg rkd-artist:Rembrandt) have P131.
P1 is implied from P87 and P131, but EntityAPI currently doesn't return inferred triples
-- Jana requested all APs to have "object", so now some "object" are internal nodes (eg part/1 and eg collection/1/entry) which have no label or P1
-- Decision: change to
{noformat}literal or rdf:label or P1.P3 or P87.P3 or P131.P3 or "type.label - P2.label" or ""{noformat}
-- Please note that some nodes have multiple rdf:type and P2: use only the first one
-- the next-to-last disjunct will result in the following:
|part/1 | Man-Made Object - Painting| also has "Information Carrier - vertical rectangle" but we skip this|
|exhibition/1 | Activity - Exhibition | |
|collection/1/entry | | has inferred types Part Addition, Transfer of Custody and Acquisition but we don't return them for now|
-- the last disjunct returns empty string instead of the unsightly "null"
-- if a title part is empty, also skip the separator ": "