model.uml

@startuml
hide stereotype

skinparam class {
    BackgroundColor Linen
    ArrowColor Black
    BorderColor Navy

    BackgroundColor<<functional>> LightSteelBlue
}
skinparam groupInheritance 2

title "STAM: Stand-off Text Annotation Model -- Extended Model"

class TextResource {
    --
    id : str
    text: str
    --
    _id : int
    _index: [TextSelection*]
    --
    <i>Holds the text</i>
    <i>(and the reverse index)</i>
}

class TextSelection <<functional>> {
    offset: (begin: int, end: int)
    --
    _referenced_by: [&Annotation+]
    _part_of: [&TextResource]
    _id : int
    --
    <i>Links text positions to annotations</i>
    <i>Used by the reverse index</i>
    <i>(not serialised)</i>
}

class AnnotationStore {
    id: str?
    annotations: [Annotation*]
    datasets: [AnnotationDataSet*]
    resources: [TextResource*]
    --
    <i>Holds the full annotation graph model</i>
    <i>(entry-point)</i>
}

class AnnotationDataSet {
    id: str?
    keys: [DataKey*]
    data: [AnnotationData*]
    --
    _id: int
    --
    <i>An annotation dataset holds</i>
    <i>the actual data associated with annotations</i>
    <i>and defines the vocabulary (the keys), it does</i>
    <i>not hold the annotations themselves</i>
}

class Annotation {
    id: str?
    data: [&AnnotationData+]
    target: Selector
    --
    _id : int
    _referenced_by: [&Annotation*]
    --
    <i>An instance of an annotation</i>
    <i>Core concept, i.e. nodes in the graph,
    <i>binds everything together</i>
}

abstract class Selector {
    --
    <i>Selects the target</i>
    <i>(or source) of annotation</i>
}

class TextSelector {
    resource: &TextResource,
    offsets: (begin: Cursor, end: Cursor)
    --
    _textselection: &TextSelection?
    --
    <i>Selects a single part of the text,</i>
    <i>Offsets are unicode codepoints relative</i>
    <i>to the text, zero-indexed, </i>
    <i>end is non-inclusive,</i>

}

class ResourceSelector {
    resource: &TextResource
    ---
    <i>Selects a resource as a whole</i>
    <i>(i.e. annotation is metadata)</i>
}

class DataSetSelector {
    annotationset: &AnnotationDataSet
    --
    <i>Selects an annotation data set as</i>
    <i>a whole (i.e. annotation is metadata)</i>
}

class DataKeySelector {
    annotationset: &AnnotationDataSet
    key: &DataKey
    --
    <i>Selects a data key</i>
    <i>(i.e. annotation is metadata)</i>
}

class AnnotationDataSelector {
    annotationset: &AnnotationDataSet
    data: &AnnotationData
    --
    <i>Selects annotation data</i>
    <i>(i.e. annotation is metadata)</i>
}

class AnnotationSelector {
    annotation: &Annotation
    offsets: (begin: Cursor, end: Cursor)?
    --
    _textselection: &TextSelection?
    --
    <i>Selects an annotation. May optionally</i>
    <i>select a only part of the annotation's target</i>
    <i>Offsets are relative</i>
    <i>to the targeted annotation, </i>
    <i>end is non-inclusive.</i>
}

class MultiSelector {
    selectors: [Selector++]
    --
    <i>Combines selectors</i>
    <i>The annotation applies</i>
    <i>to each target individually</i>
    <i>and independently.</i>
}

class CompositeSelector {
    selectors: [Selector++]
    --
    <i>Combines selectors</i>
    <i>The annotation applies</i>
    <i>to all targets combined,</i>
    <i>they are inter-dependant.</i>
}

class DirectionalSelector {
    selectors: [Selector++]
    --
    <i>Expresses a direction between two or more selectors,</i>
    <i>in the exact order specified (from -> to)</i>
    <i>The annotation applies to all targets</i>
    <i>combined, they are inter-dependant.</i>
}

class RangedInternalSelector <<functional>> {
    begin: Selector,
    end: Selector,
    --
    <i>Internal selector to select whole ranges</i>
    <i>by internal ID. Allows for more compact</i> 
    <i>representation in memory. Used under</i>
    <i>DirectonalSelector/CompositeSelector/MultiSelector.</i>
    <i>(not serialised)</i>
}

Selector <|-[#green]- TextSelector
Selector <|-[#green]- ResourceSelector
Selector <|-[#green]- DataSetSelector
Selector <|-[#green]- DataKeySelector
Selector <|-[#green]- AnnotationDataSelector
Selector <|-[#green]- AnnotationSelector
Selector <|-[#green]- MultiSelector
Selector <|-[#green]- CompositeSelector
Selector <|-[#green]- DirectionalSelector
Selector <|.[#green]. RangedInternalSelector


class AnnotationData {
    id: str?
    key: &DataKey
    value: DataValue
    --
    _id : int
    _data_for: [&Annotation*]
    _referenced_by: [&Annotation*]
    _part_of_set: &AnnotationDataSet
    --
    <i>The value of the annotation</i>
}

class DataKey {
    id: str
    indexed: bool
    --
    _id: int
    _key_for: [&AnnotationData*]
    _referenced_by: [&Annotation*]
    _part_of_set: &AnnotationDataSet
    --
    <i>The key of an annotation</i>
}

enum DataValue {
    Null
    String(value: str)
    Bool(value: bool)
    Int(value: int)
    Float(value: float)
    Datetime(value: datetime)
    List(value: [DataValue])
    --
    <i>Encapsulates a data value</i>
    <i>along with its type</i>
}
' There is no Map() in DataValue, a Map should be expressed as an Annotation on an Annotation

enum Cursor {
    BeginAlignedCursor(value: int)
    EndAlignedCursor(value: int)
    --
    <i>Used to select offsets</i>
    <i>Units are unicode codepoints,</i>
    <i>(not bytes!), zero-indexed</i>
}

enum TextSelectionOperator <<functional>> {
    Equals(other: TextSelection)
    Precedes(other: TextSelection, mindistance: int?, maxdistance: int?)
    StartsBefore(other: TextSelection, mindistance: int?, maxdistance: int?)
    Succeeds(other: TextSelection, mindistance: int?, maxdistance: int?)
    EndsBefore(other: TextSelection, mindistance: int?, maxdistance: int?)
    Near(other: TextSelection, mindistance: int?, maxdistance: int?)
    Overlaps(other: TextSelection)
    Embeds(other: TextSelection)
    Before(other: TextSelection,spacing: bool, punct: bool)
    After(other: TextSelection,spacing: bool, punct: bool)
    SameBegin(other: TextSelection)
    SameEnd(other: TextSelection)
    SameRange(other: TextSelection)
    Not(TextSelectionOperator)
    And([TextSelectionOperator++])
    Or([TextSelectionOperator++])
    --
    <i>Operators to compare text selections</i>
}

enum DataOperator <<functional>> {
    Equals(other: DataValue)
    GreaterThan(other: DataValue)
    LessThan(other: DataValue)
    GreaterThanOrEqual(other: DataValue)
    LessThanOrEqual(other: DataValue)
    HasElement(other: DataValue)
    HasElement(key: DataValue)
    And([DataOperator++])
    Or([DataOperator++])
    Not(DataOperator)
    --
    <i>Operators to test the value of</i>
    <i>annotation data (DataValue)</i>
}

AnnotationStore "1" *--> "*" AnnotationDataSet : > datasets
AnnotationStore "1" *--> "*" TextResource : > resources
AnnotationStore "1" *--> "*" Annotation : > annotations

AnnotationDataSet "1" *--> "*" AnnotationData : > data
AnnotationDataSet "1" *--> "*" DataKey : > keys

Annotation "1" *--> "+" Selector : > target
Annotation "1" o-[#red]-> "*" AnnotationData : > data
Annotation "1" o.[#red].> "*" Annotation : > _referenced_by

AnnotationData "1" o.[#red].> "+" Annotation : > _data_for
AnnotationData "1" o.[#red].> "+" Annotation : > _referenced_by
AnnotationData "1" *--> "1" DataValue : > value
AnnotationData "1" *-[#red]-> "1" DataKey : > key
AnnotationData "1" o.[#red].> "1" AnnotationDataSet : > _part_of_set

TextSelector "1" o-[#red]-> "1" TextResource : > resource
TextSelector "1" o.[#red].> "1" TextSelection : > _textselection
AnnotationSelector "1" o.[#red].> "1" TextSelection : > _textselection
ResourceSelector "1" o-[#red]-> "1" TextResource : > resource
AnnotationSelector "1" o-[#red]-> "1" Annotation : > annotation
DataSetSelector "1" o-[#red]-> "1" AnnotationDataSet : > annotationset
DataKeySelector "1" o-[#red]-> "1" AnnotationDataSet : > annotationset
DataKeySelector "1" o-[#red]-> "1" DataKey : > key
AnnotationDataSelector "1" o-[#red]-> "1" AnnotationDataSet : > annotationset
AnnotationDataSelector "1" o-[#red]-> "1" AnnotationData : > data

DataKey "1" o.[#red].> "+" AnnotationData : > _key_for
DataKey "1" o.[#red].> "+" AnnotationData : > _referenced_by
DataKey "1" o.[#red].> "1" AnnotationDataSet : > _part_of_set

MultiSelector "1" --> "*" Selector : > selectors
CompositeSelector "1" --> "*" Selector : > selectors
DirectionalSelector "1" --> "*" Selector : > selectors
RangedInternalSelector "1" --> "1" Selector : > begin/end
TextSelector "1" --> "2" Cursor : > offsets
AnnotationSelector "1" --> "2" Cursor : > offsets

TextResource "1" *..> "*" TextSelection : > _index
TextSelection "1" o.[#red].> "*" Annotation : > _referenced_by
TextSelection "1" o.[#red].> "*" TextResource : > _part_of

TextSelectionOperator *..> TextSelection : > other
TextSelectionOperator .[#blue].> TextSelection : > <<applied to>>
TextSelectionOperator *..> TextSelectionOperator : > Not/And/Or

DataOperator .[#blue].> DataValue : > <<applied to>>
DataOperator *..> DataValue : > other
DataOperator *..> DataOperator : > Not/And/Or

@enduml