4A protocol 2.0

Last modification: June 23, 2015

Table of contents:

Description of protocol follows. In the definitions of the messages there are macros used. These macros are surrounded by curly brackets: {macro}

There are some attributes in which client can use wildcard *. This wildcard is interpreted as expression .* in regular expressions -- any count of any characters (including empty string).

In the protocol description there is only positive response considered in the response description (no errors). If some error occurs, server will send it to the client in the error message (there is separate section in this document with error messages).

There will be introduced types of objects consecutively in the protocol which are used by both communicating sides. Some of them has URI which are uniquely identifying given object in the Internet:

Type of object URI scheme URI example
Annotation {server URI}/Annotations/{serv|temp}/{identification number of annotation} http://example.com/Annotations/serv/81174
Suggestion {server URI}/Annotations/sugg/{identification number of suggestion} http://example.com/Annotations/sugg/348
Subscriptions {server URI}/Annotations/subscriptions/{id of subscription} http://example.com/Annotations/subscriptions/234
Type of annotation {server URI}/Annotations/types/g{id of user group}/{type path} http://example.com/Annotations/types/g17/Animal/Human/Artist
Type of attribute --- no unified scheme (more patterns) --- http://www.w3.org/2001/XMLSchema#string
User {server URI}/Annotations/users/{id of user} http://example.com/Annotations/users/6881
User group {server URI}/Annotations/groups/{id of user group} http://example.com/Annotations/groups/1114
Document (server copy) {server URI}/Annotations/documents/getDoc?id={id of document} http://example.com/Annotations/documents/getDoc?id=1234
Entity from controlled vocabulary --- no unified scheme --- http://www.artnet.com/artwork/426018191/3952/sergei-chepik-sunflowers-from-arles.html
Attribute from ontology --- no unified scheme --- http://decipher.open.ac.uk/rdfs/decipher/decipher_v1.rdfs#uses

Communication

All communication is in XML language. There are two different channel used:

Synchronous channel

It is crucial for synchronous channel that there is only one open connection with the server in any moment. If client creates request in the moment when it is waiting for response to previous request new request is inserted into queue. It is get from the queue and send to the server after receiving response to the previous request from the server.

Request

<?xml version="1.0"?>
<messages sessionID="{ID sezení}">
  {list of messages}
</messages>

Attribute sessionID is used for identification of session (see Session and user log on). This attribute is required except case that client is not connected so session is not established yet.

Response

<?xml version="1.0"?>
<messages>
  {list of messages}
</messages>

If server receives request where no usable response is expected and no error occurs server still needs to respond. In this case simple response ok is used:

<?xml version="1.0"?>
<messages>
  <ok/>
</messages>

Asynchronous channel

Request

Responses to comet requests arrives after a long period of time typically. Number of active connections with the server is limited by browsers for one web page (typically according to RFC 2616). For this reason it is not possible for more clients to have own comet channel. So there must be some mechanism on the client side to manage one comet channel for all connected annotation editors. Client must state session ID of of all connected editors in the comet request.

<?xml version="1.0"?>
<messages>
  {list of session IDs in following format:
    <session id="{session ID}"/>
  }
  <comet/>
</messages>

Response

Server sends response which is addressed only to one connected editor. If there is more messages for different editors on same channel in the same moment then server is sending these messages as a responses for new individual requests.

<?xml version="1.0"?>
<messages sessionID="{ID sezení}">
  {list of messages}
</messages>

According to attribute sessionID client determines to which editor it should pass the message.

If time limit for response is reached and server have no data for client, it responses with simple message ok, where it will states ID of session of any connected editor in the attribute sessionID:

<?xml version="1.0"?>
<messages sessionID="{session ID}">
  <ok/>
</messages>

If client received response from server it must send another comet request immediately. It states session IDs of all connected editors again.

Session and user log in

Connection establishment

Request

Client establishes connection with server by message connect. In element messages where doesn't states sessionID, because it was not assigned yet. Message connect have required attribute protocolVersion -- client states number of highest supported version.

Optional attribute attachCometTo can be used to tell server that new session should be added to the existing comet channel. It is suitable if there is more editors on one page. In this case in this attribute client states session ID of any editor which is already assigned to this comet channel.

<connect protocolVersion="{protocol version}"
         {optional: attachCometTo="{session ID}"}/>

Example:

<connect protocolVersion="2.0"
         attachCometTo="34"/>

Response

If there are no errors server responses with message connected:

<connected protocolVersion="{protocol version}"
           sessionID="{session ID}"/>

Attributes:

If server doesn't support protocol version sent by client, it sends highest supported protocol version which is backward compatible with version proposed by client. Client should communicate by this version without problems. If server doesn't support such version, it will return error message. If client supports another versions of the protocol, it can try to connect to the server with particular versions.
If client offer newest version than server, server uses newest version supported. If client detects that its version is not backward compatible with server version, it must switch to server version or any backward compatible version. If no compatible version available, client must disconnect itself.

Example:

<connected protocolVersion="2.0"
           sessionID="17"/>

Creating of comet channel

After receiving of response to the connect message, client creates comet channel which will be used for asynchronous communication. Message for channel opening is following:

<comet/>

Any time when server returns the response, client must reopen the channel using comet message. Channel can be opened only for limited time because browser sets timeout for receiving of the response. If server have channel opened for the long time and haven't data to send, it will respond by message ok. It will cause closing of the channel which will be reopened by client immediately.

Closing of connection

Client finishes connection by message disconnect:

<disconnect/>

In case of unsuccessful connection to the server, client will not send this as it is not connected.

Server doesn't respond to this message.

User log in

Request

User is logged in using message login. There are two alternatives of this message:

Response

If there are no problems, server will respond by messages logged and settings:

<logged uri="{URI of user}"
        login="{user name}"
        name="{full name of the user}"
        email="{user's email}"
        image="{URI of user's image}"/>
{settings message}

Attributes of element logged correspond to user's required attributes.

Note: In case of using OpenID, attribute login is not used so it is not required in this case.

Message settings will be described below.

Example:

<logged uri="http://example.com/Annotations/users/89"
        login="admin"
        name="John Doe"
        email="john.doe@example.com"
        image="http://example.com/images/photo.png"/>

User log off

Client logs off user using message logout:

<logout/>

Server doesn't respond to this message.

Users and user groups

User is person to which is allowed to log in to his account on given server. User group allows to group more users to one collective.

User is represented by entity with set of required attributes:

Note: In case of using OpenID, attribute login is not used so it is not required in this case.

List of users

Request

Client can request for list of users using message getUsers:

<getUsers {filtering attributes}/>

It is possible to specify up to 4 attributes for filtering of the list of users for the client:

First two attributes should lead to list with only one user.

Following example demonstrates request for list of users which have name or surname beginning with Adam:

<getUsers name="Adam"/>

It is also possible to use element includeOnly and put attributes filtering elements inside. Every element corresponds to one attribute of the user which should be presented in the response:

<getUsers {filtering attributes}>
  <includeOnly>
    {filtering elements}
  </includeOnly>
</getUsers>

Macro {filtering elements} is composed from following elements where each can be used only once:

If element includeOnlyis not presented, server returns all information about user, which it have. If it is presented, server returns only explicitly specified information. It is usable eg. for autocomplete functionality, where we need only small specific set of attributes. Attribute uri is always returned.

Following example is request for list of all users. Only URI , name and email will be returned:

<getUsers>
  <includeOnly>
    <name/>
    <email/>
  </includeOnly>
</getUsers>

Response

Response from server is following:

<users>
  {list of users}
</users>

Macro {list of users} is composed from elements user:

<user {information about user}/>

Eventually:

<user {information about user}>
  <groups>
    {list of user groups in following format:
      <group uri="{group URI}"/>
    }
  </groups>
</user>

Example of response to request above:

<users>
  <user uri="http://example.com/Annotations/users/89"
        name="John Doe"
        email="john.doe@example.com"/>
  <user uri="http://example.com/Annotations/users/17"
        name="Frank Doe"
        email="frank.doe@example.com"/>
</users>

List of user groups

Request

List of user groups can be requested using message getUserGroups:

<getUserGroups {selection attributes}
               {optional: withUsers="{true|false}"}/>

Macro {selection attributes} is composed by following attributes:

Attribute withUsers indicates that list of users should be included in information about every user group. Default value is false.

Example:

<getUserGroups uri="http://example.com/Annotations/groups/27"
               withUsers="true"/>

If withUsers is set to true it is possible to use element includeOnly as in list of users above (with same syntax and semantics).

<getUserGroups {atributy}>
  <includeOnly>
    {list of selection elements}
  </includeOnly>
</getUserGroups>

Response

Server responses with following message:

<userGroups>
  {list of groups}
</userGroups>

where each user group have following format:

<group name="{name of the group}"
       uri="{group URI}"/>

or

<group name="{name of the group}"
       uri="{group URI}">
  {list of users}
</group>

Example of whole message:

<userGroups>
  <group name="Administrators"
         uri="http://example.com/Annotations/groups/27">
    <user uri="http://example.com/Annotations/users/17"/>
    <user uri="http://example.com/Annotations/users/89"/>
  </group>
</userGroups>

Join user to group

Logged in user can join to the group using message joinUserGroup:

<joinUserGroup uri="{group URI}"/>

Example:

<joinUserGroup uri="http://example.com/Annotations/groups/27"/>

Server doesn't respond to this message.

Leaving user group

Logged in user can leave the group using message leaveUserGroup:

<leaveUserGroup uri="{group URI}"/>

Example:

<leaveUserGroup uri="http://example.com/Annotations/groups/27"/>

Server doesn't respond to this message.

Subscriptions to annotations

Subscription to annotations is object which contain list of sources of annotations. Sources are selecting the annotations according to its types, author and user group of author. So every subscription is description of some specific set of rules for annotations selection. Every user can subscribe to subscription and thus receive annotations from other users which are interesting for him. Client is subscribed to the subscription only until his session is finished. If client needs to have some subscriptions subscribed in every session, it have to request them again in every session.

Creating of subscription

Request

Client creates temporary identifier of subscription tmpId. Server sends mapping of temporary identifier to assigned persistent identifier (URI). So server is not sending whole description of the subscription back to the client. Client deletes tmpId and assign received uri. Message for subscription creation is following:

<createSubscription tmpId="{temporary identifier of subscription}"
                    name="{name of subscription}">
  {list of sources in following format:
    <source subscribe="{true|false}"
            {selection attributes of source}/>
  }
</createSubscription>

Source source have attribute subscribe which indicates whether annotations from given source should be received or not. So it is possible to select receiving of some set of annotations by positive source (subscribe="true") and then restrict this set by some negative source(s) (subscribe="false").

Macro {selection attributes of source} is composed from following attributes:

Example:

<createSubscription tmpId="138"
                    name="My Favorite Art Movements">
  <source subscribe="true"
          typeUri="http://example.com/Annotations/types/g17/Movement"
          authorUri="http://example.com/Annotations/users/123456"
          groupUri="http://example.com/Annotations/groups/27"/>
  <source subscribe="false"
          typeUri="http://example.com/Annotations/types/g17/Movement/Expressionism"/>
</createSubscription>

Response

<subscriptionCreated tmpId="{temporary identifier of subscription}"
                     uri="{URI of subscription}"/>

Example:

<subscriptionCreated tmpId="138"
                     uri="http://example.com/Annotations/subscriptions/65"/>

Removing of subscription

Client can remove subscription using following message:

<removeSubscription uri="{URI of subscription}"/>

Example:

<removeSubscription uri="http://example.com/Annotations/subscriptions/438"/>

Server doesn't respond to this message.

Changing of subscription

Client can remove subscription using following message:

<modifySubscription uri="{URI of subscription}"
                    name="{name of subscription}">
  {list of sources in following format:
    <source subscribe="{true|false}"
            {selection attributes of source}/>
  }
</modifySubscription>

Example:

<modifySubscription uri="http://example.com/Annotations/subscriptions/71"
                    name="My Favorite Art Movements (Modified)">
  <source subscribe="true"
          typeUri="http://example.com/Annotations/types/g17/Movement"
          authorUri="http://example.com/Annotations/users/123456"
          groupUri="http://example.com/Annotations/groups/27"/>
  <source subscribe="false"
          typeUri="http://example.com/Annotations/types/g17/Movement/Expressionism"/>
  <source subscribe="false"
          typeUri="http://example.com/Annotations/types/g17/Movement/Impressionism"/>
</modifySubscription>

Server doesn't respond to this message.

List of subscriptions

Request

Client can request list of subscriptions filtered by some attributes. If no attributes are presented, server sends list of all subscriptions of all users.

<getSubscriptions {filtering attributes}/>

Macro {filtering attributes} is composed from following attributes:

Example:

<getSubscriptions authorUri="http://example.com/Annotations/users/84"/>

Response

<subscriptions>
  {list of subscriptions in following format:
    <subscription uri="{URI of subscription}"
                  name="{name of subscription}"
                  authorUri="{URI of author of subscription}">
      {list of sources in following format:
        <source subscribe="{true|false}"
                {filtering attributes}/>
      }
    </subscription>
  }
</subscriptions>

Example:

<subscriptions>
  <subscription uri="http://example.com/Annotations/subscriptions/71"
                name="My Favorite Art Movements"
                authorUri="http://example.com/Annotations/users/8394">
    <source subscribe="true"
            typeUri="http://example.com/Annotations/types/g17/Movement"
            authorUri="http://example.com/Annotations/users/67"
            groupUri="http://example.com/Annotations/groups/27"/>
    <source subscribe="false"
            typeUri="http://example.com/Annotations/types/g17/Movement/Expressionism"/>
  </subscription>
</subscriptions>

Subscribe to subscription

User can subscribe to existing subscription using following message:

<subscribe subscriptionUri="{URI of subscription}"/>

Example:

<subscribe subscriptionUri="http://example.com/Annotations/subscriptions/4"/>

Server doesn't respond to this message.

Unsubscribe from subscription

User can unsubscribe from subscription to which is subscribed using following message:

<unsubscribe subscriptionUri="{URI of subscription}"/>

Example:

<unsubscribe subscriptionUri="http://example.com/Annotations/subscriptions/4"/>

Server doesn't respond to this message.

Document synchronization

For each document which is opened on the client, server creates own copy and returns URI of this copy to the client. All annotations created for this document contains this URI as a target (or as a part of target description).

Process of synchronization

Client in the beginning of process of synchronizace sends URI and the content of the document to the server. Server checks whether it have this document already in the database. If haven't, server stores the document. If have, it compares the content of the document with stored one. If contents are different, impact of update to annotations is evaluated. If impact is small, fragments of affected annotations are updated and document is updated in the database. If impact is high, it is possible that targets of some annotations will not be found and they will be moved to the level of whole document. In this case it is necessary to confirm update by user. In case of confirmation user can additionally set targets to another place (by common editation of annotation).

Request

Synchronization message have following format:

<synchronize uri="{URI of opened document}"
            {optional attributes}>
  <![CDATA[{content of the document}]]>
</synchronize>

Note: Comparing to protocol version 1.1 there is no surrounding element content.

Note: Attribute uri is called resource in protocol version 1.1. It allows easily distinguish:

Macro {optional attributes} is composed from following attributes:

Example of synchronization message:

<synchronize uri="http://example.com/Annotations/documents/getDoc?id=1234"
             linearized="false"
             overwrite="false">
  <![CDATA[<html><head></head><body><p>Hello World!</p></body></html>]]>
</synchronize>

Response

Server compares own version of the document with one that was sended by client.

Message synchronized

This message is sent by server in case of successful synchronization.

<synchronized resource="{URI of copy of the document on the server}"
              lastModification="{ID of last modification}"/>

Attribute resource contains URI of copy of the document on the server (copy of the document which client sent in the message synchronize. This URI is used by the client in the annotations.

Attribute lastModification contains identifier of the last modification performed on the document.

Example:

<synchronized resource="http://example.com/Annotations/documents/getDoc?id=1234"
              lastModification="72"/>
Warning message

If some fragments of the annotations will be changed in synchronization process, server will send warning message along with synchronized message. This warning message will contain URIs of changed annotations:

<warning code="annotations changed">
  <message>
    <![CDATA[Targets of some annotations have been changed due to a document modification.]]>
  </message>
  <annotations>
    {list of annotations in following format:
      <annotation uri="{URI of annotation}"/>
    }
  </annotations>
</warning>

Example:

<warning code="annotations changed">
  <message>
    <![CDATA[Targets of some annotations have been changed due to document modification.]]>
  </message>
  <annotations>
    <annotation uri="http://example.com/Annotations/serv/3985"/>
    <annotation uri="http://example.com/Annotations/serv/1545"/>
    <annotation uri="http://example.com/Annotations/serv/148868"/>
    <annotation uri="http://example.com/Annotations/serv/88916"/>
    <annotation uri="http://example.com/Annotations/serv/35486"/>
    <annotation uri="http://example.com/Annotations/serv/99"/>
  </annotations>
</warning>
Error message

In case of unsuccessful synchronization server will send following error message to the client:

<error code="sync error">
  <message>
    <![CDATA[Targets of some annotations would be significantly changed if the server's version of the document was updated.]]>
  </message>
  <serverVersion>
    <![CDATA[{content of server's copy of the document}]]>
  </serverVersion>
</error>

Example:

<error code="sync error">
  <message>
    <![CDATA[Targets of some annotations would be significantly changed if the server's version of the document was updated.]]>
  </message>
  <serverVersion>
    <![CDATA[<html><body><p>Konnichiwa sekai!</p></body></html>]]>
  </serverVersion>
</error>

With synchronized message server sends all annotations (according to client's subscriptions) and all types of annotations which are contained in them (client can need it for interpretation of them)..

Resending of document content

Message from the server

If server detects that it is possible that client have another version of the document even if documents should be synchronized (eg. fragment of just created annotation doesn't match), it will send command to perform resynchronization to the client. If detected problem is related to client's request (eg. new annotation), it will send it through AJAX channel. If it is not related to client's request (eg. server's internal problem) it will send it through comet channel.

<resynchronize resource="{URI of resource}"
               method="{soft|hard}"/>

Attributes:

Example:

<resynchronize resource="http://example.com/Annotations/documents/getDoc?id=12341234567"
               method="soft"/>

Client's reaction

Document modifications

Client can be extension of the WYSIWYG editor so the user can freely change content of the annotated document. Client should send modification of the text performed by user (or other plugin) as often as possible (preferably with each change, eg. with every written, changed or removed character in the document).

Request

<modification lastApplied="{ID of last modification performed}">
  {list of modification messages}
</modification>

Macro {ID of last modification performed} represents identifier of last modification applied which client performed on its own version of the document before performed new change (see below).

Macro {list of modification messages} consists from the list of modifications. There are 3 types of modifications:

Response

Current version of the annotated document is stored on the server. Modification of the document is restricted by exclusive access. When server receives new request for modifications and previous requests are not processed, it is putted into fronty. After processing of previous requests, given request is picked up from the queue and processed. Server keeps counter of modifications along with document. It also keeps some number of descriptions of last modifications performed. If client's request is processed, server evaluates if it is possible to perform modification of the document such way that result will be correct and consistent on all clients.

If client have same version as a server (same modification ID), modifications can be performed immediately. Counter of modifications is increased and given modification is along with it's ID sent to other clients with same document opened.

If client have older version than server, number of unexecuted modifications (from other clients) on the given client is evaluated. Client have not these modifications so they are not taken into account in creation of current modification. If there is a lot of such modifications (according to server's setting; at least 3), server will send error message to the client. In this error message it states that client's version is too old for performing of the modification.

If they are conflicting, server will send error message to the client. In this message it states that modifications can not be applied due to conflict with other modifications. If they are not conflicting, modifications are performed and counter of modifications is increased. Then given modification is along with it's ID sent to other clients with same document opened.

Client which requested the modification receives following message in case of success:

<modificationApplied id="{ID of modification}"/>

ID of modification is necessary to tell the client that it should not wait for this number if it is receiving modifications from other clients (see below).

Other clients receives modification in following format:

<modification id="{ID of modification}">
  {list of modification messages}
</modification>

Client holds ID of last modification performed on its document. Incoming modifications are held in a queue from which are picked up if their number matches number of last modification performed plus 1. Then modification is performed and ID of last modification incremented.

If client is waiting for response to own modification request, it is not performing incoming modifications and creates also queue of next modifications performed by the user. If server responses wit error, client have following possibilities:

Types

Annotation can be only of type of annotation (structured type). Structured type can have attributes which can have simple or structured types.

Note: Unless otherwise stated, in whole protocol is valid that if some type of annotations is expected, server involves also all subtypes of a given type. Eg. if client requests for suggestions of type Person, server returns also suggestions of subtypes as a Person->Employee or Person->Artist.

Simple types

Name URI Description Example of value
String http://www.w3.org/2001/XMLSchema#string UTF8 string John Doe
URI http://www.w3.org/2001/XMLSchema#anyUri URI http://example.com
DateTime http://www.w3.org/2001/XMLSchema#dateTime date and time in conformance to RFC 3339 (iso-date-time with datespec-full) 2002-10-10T12:00:00-05:00
Date http://www.w3.org/2001/XMLSchema#date date in conformance to RFC 3339 (datespec-full) 2002-10-10+05:00
Time http://www.w3.org/2001/XMLSchema#time time in conformance to RFC 3339 (time) 13:20:00-05:00
Integer http://www.w3.org/2001/XMLSchema#integer integer -518
Decimal http://www.w3.org/2001/XMLSchema#decimal decimal 1.23
Boolean http://www.w3.org/2001/XMLSchema#boolean boolean value true
GeoPoint http://www.w3.org/2003/01/geo/wgs84_pos#Point geographical point according to Basic Geo (WGS84 lat/long) Vocabulary (basic)
<geo:Point>
  <geo:lat>55.701</geo:lat>
  <geo:long>12.552</geo:long>
</geo:Point>
AnyAnnotation http://knot.fit.vutbr.cz/annotations/knotOAExtension#anyAnnotation nested annotation or link to annotation can not have value
AnyEntity http://knot.fit.vutbr.cz/annotations/knotOAExtension#anyEntity some entity can not have value
Duration http://www.w3.org/2001/XMLSchema#duration duration according to RFC 3339 (duration) - extended over XMLSchema duration P1Y2MT2H
Binary http://www.w3.org/2001/XMLSchema#base64binary binary data (files as an OpenDocument; encoded in base64; file size can be limited by the server) 0FB8
Text http://knot.fit.vutbr.cz/annotations/knotOAExtension#text long string Some text
Image http://knot.fit.vutbr.cz/annotations/knotOAExtension#imageUri URI of image http://upload.wikimedia.org/wikipedia
/commons/a/a0/Bruegge_View_from
_Rozenhoedkaai.jpg
Entity http://knot.fit.vutbr.cz/annotations/knotOAExtension#entity entity from controlled vocabulary Serialization of attribute of this type is significantly different from other types - see Format of annotation.

Format of type of annotation

<type name="{name of type}"
      uri="{URI of type}"
      groupUri="{URI of user group}"
      restrictedAttributes="{restriction of attributes}"
      {volitelně: ontologyUri="{URI from ontology}"}>
  <directAncestors primary="{URI of primary ancestor}">
    {list of direct ancestors in following format:
      <ancestor uri="{URI of type}"/>
    }
  </directAncestors>
  <attributes>
    {list of attributes}
  </attributes>
  {optional comment in following format:
    <comment>
      <![CDATA[{commentary}]]>
    </comment>
  }
</type>

Required attributes of element type:

Attribute ontologyUri is included in case that this type is in ontology. Value is URI of type in given ontology.

Element directAncestors have attribute primary which contains primary direct ancestor. If it is empty, it represents root of type tree. Sub elements of ancestor contains other direct ancestors of type.

Macro {list of attributes} is composed from elements attribute:

<attribute valueType="{simple|linked|nested}"
           name="{name of attribute}"
           typeUri="{URI of type}"
           required="{is attribute required?}"
           {optionally: ontologyUri="{URI of attribute from ontology}"}
           {optionally: priority="{priority of attribute}"}/>
  {optionally: <comment><![CDATA[{comment for attribute}]]></comment>}
</attribute>

Attribute valueType determines type of value:

Attribute ontologyUri is included only in case that attribute is in some (imported) ontology. In this case it contains URI of attribute in ontology.

Attributes can be of simple or structured types.

Example of serialized type of annotation:

<type name="Picture"
      uri="http://example.com/Annotations/types/g17/Art/Artwork/Picture"
      groupUri="http://example.com/Annotations/groups/27"
      restrictedAttributes="true">
  <directAncestors primary="http://example.com/Annotations/types/g17/Art/Artwork">
    <ancestor uri="http://example.com/Annotations/types/g17/Art"/>
    <ancestor uri="http://example.com/Annotations/types/g17/Art/Artist/Work"/>
  </directAncestors>
  <attributes>
    <attribute name="Created"
               typeUri="http://www.w3.org/2001/XMLSchema#date"
               required="true">
      <comment>
        <![CDATA[Date of creation]]>
      </comment>
    </attribute>
    <attribute name="Price"
               typeUri="http://www.w3.org/2001/XMLSchema#integer"
               required="true">
      <comment>
        <![CDATA[Current price of the picture]]>
      </comment>
    </attribute>
  </attributes>
  <comment>
    <![CDATA[Picture is a kind of an artwork.]]>
  </comment>
</type>

Manipulation with types

Server can control set of types of annotations on the client. If client needs some types, server responds with command for adding of types which are specified in this command. If client creates new type of annotation, server will send command to create this type to other interested clients through the comet channel. Client also can add, change or remove type on the server. Communication is performed by three types of messages:

Getting of types of annotations from the server

Request

Client do not need to have all types in all cases. There can be so much types that it can exhaust the client. So client is requesting the types and server is returning them on demand. Server knows what requests was sent by particular client and if there is some change in set of types requested, server will send update to the client immediately.

Client can request types using following message:

<getTypes {optionally: uri="{URI of type}"}/>

Example:

<getTypes uri="http://example.com/Annotations/types/g17/Person/Artist"/>

Attribute uri allows to select type and his whole subtree. It is possible to use wildcard *. If attribute is not presented, server returns all types in all groups to which the user belongs.

Server responds with message addTypes.

Getting of attributes from ontology

Client can request attributes from ontology. These attributes have defined name and type. If user is adding a new attribute to the type of annotation, he can decide if he creates a new one (fill in name and type) or selects already defined attribute from ontology.

Request

<getOntologyAttributes {optionally: groupUri="{URI of user group}"}/>

Note: this element was renamed from queryAttrFromOnto in protocol 1.1.

Attribute groupUri contains URI of user group to which list of attributes should be restricted. If it is not present, server returns all attributes in all groups to which the user belongs.

Example:

<getOntologyAttributes groupUri="http://example.com/Annotations/groups/27"/>

Response

<ontologyAttributes>
  {list of attributes}
</ontologyAttributes>

Note: this element was renamed from attrsFromOntology in protocol 1.1.

List of attributes is composed from elements attribute:

<attribute name="{name of atribute}"
           uri="{URI of attribute}"
           typeUri="{URI of type}"
           groupUri="{URI of user group}">
  {optionally: <comment><![CDATA[{comment for attribute}]]></comment>}
</attribute>

Annotations

Annotation in 4A is structured additional information which belongs to the fragment of document or to the whole document. It have type and attributes. Attributes can contain nested annotations and links to other annotations. It allows to create complex hierarchies.

Format of annotation

Annotations are serialized according to standard Open Annotation Data Model. More information can be found in: http://www.openannotation.org/spec/core/

<oa:Annotation rdf:about="{URI of annotation}">
  <oa:hasBody>
    <oa:SemanticTag rdf:about="{URI of type of annotation}"/>
  </oa:hasBody>
  <oa:hasBody>
    <cnt:ContentAsText rdf:about="{URI of annotation}#body">
      <rdf:type rdf:resource="http://purl.org/dc/dcmitype/Text"/>
      <cnt:chars>
        <![CDATA[{textual comment in annotation}]]>
      </cnt:chars>
      <dc:format>text/plain</dc:format>
    </cnt:ContentAsText>
  </oa:hasBody>
    {TARGET}
  <oa:hasBody>
    <cnt:ContentAsText rdf:about="{URI of annotated document}">
      <rdf:type rdf:resource="http://www.w3.org/2004/03/trix/rdfg-1/Graph"/>
      <trix:TriX>
        <trix:graph>
        {LIST OF ATTRIBUTES OF ANNOTATION}
        </trix:graph>
      </trix:TriX>
      <dc:format>text/xml</dc:format>
    </cnt:ContentAsText>
  </oa:hasBody>
  <oa:annotatedBy>
    <foaf:Person rdf:about="{URI of author}">
      <foaf:name>{name of author}</foaf:name>
      <foaf:mbox>mailto:{email of author}</foaf:mbox>
    </foaf:Person>
  </oa:annotatedBy>
  <oa:annotatedAt>{time of annotation creation}</oa:annotatedAt>
  <oa:serializedAt>{time of annotation creation}</oa:serializedAt>
</oa:Annotation>

Note: elements oa:annotatedAt and oa:serializedAt contains same timestamp.

Description of macros

Manipulation with annotations on the client

Server can control set of annotations on the client. For this purpose there are following messages:

Creation of the annotation by the client

Request

Client can send newly created annotations to the server using following message:

<createAnnotations>
  {list of annotations}
</createAnnotations>

Macro {list of annotations} is composed from elements oa:Annotation. Persistent URI (prefix serv) have to be created by server. Client generates temporary URI with prefix temp.

Response

<annotationsCreated>
  {list of annotations in following format:
    <annotation tempUri="{temporaty URI of annotation}"
                servUri="{persistent URI of annotation}"/>
  }
</annotationsCreated>

Example:

<annotationsCreated>
  <annotation tempUri="http://example.com/Annotations/temp/268"
              servUri="http://example.com/Annotations/serv/13"/>
  <annotation tempUri="http://example.com/Annotations/temp/42"
              servUri="http://example.com/Annotations/serv/711"/>
</annotationsCreated>

It is a mapping of URI with prefix temp to URI with prefix serv. Client must replace all occurrences of temporary URI with persistent URI.

Modification and removing of the annotation by the client

Client can change and remove annotations using messages modifyAnnotations and removeAnnotations. These messages are same as messages which are sent by the server to the client. Server doesn't respond to them.

Reload of the annotation

Client can request reload of one or all annotations for documents opened.

<reloadAnnotation {optionally: uri="{URI of annotation}}"/>

Example:

<reloadAnnotation uri="http://example.com/Annotations/serv/5556"/>

Attribute uri is URI of annotation which should be sended. If it is not presented, server will send all annotations for all documents opened by client. Server will respond by message addAnnotations.

Suggestions of annotations

Suggestion of annotation is annotation, which was created by machine (named entity recognition and so on). These annotations needs to be reviewed and confirmed by the user. Suggestion can be differentiated from the annotation by prefix sugg.

Manipulation with suggestions

Server can control set of suggestions of annotations on the client. For this purpose it will use following two messages:

Requesting of suggestions

Client can request for suggestions using following message:

<suggestAnnotations minConfidence="{minimal confidence}"
                    {optionally: autoConfirm="{automatic confirmation}"}>
  {optionally:
    <types>
      {list of types of annotations in following format:
        <type uri="{URI of type of annotation}"/>
      }
    </types>
  }
  {optionally:
    <fragments>
      {list of fragments in following format:
        <fragment path="{XPath of fragment}"
                  {optionally:
                    offset="{offset}"
                    length="{length}"
                  }/>
      }
    </fragments>
  }
</suggestAnnotations>

Attributes of element suggestAnnotations:

If element types is not presented, annotations of all available types will be suggested. If it is presented, only annotations of types given by elements type will be included.

If element fragments is not presented, annotations will be suggested for whole document (and all parts of the document). If it will be presented, only annotations which are for specified parts of the document will be suggested. Parts of the document are specified by elements fragment.

Attributes of element fragment:

If attributes offset and length are not presented, annotations will be suggested for whole node.

Example:

<suggestAnnotations>
  <types>
    <type uri="http://example.com/Annotations/types/g17/City"/>
    <type uri="http://example.com/Annotations/types/g17/Person"/>
  </types>
  <fragments>
    <fragment path="html[1]/body[1]/p[3]"
              offset="268"
              length="354"/>
    <fragment path="html[1]/body[1]/p[4]"/>
  </fragments>
</suggestAnnotations>

Server responds with message addSuggestions.

Requesting of alternative suggestions

Requests alternatives for some suggestions

<getAlternativesFor>
  {list of suggested annotations in following format:
    <suggestion uri="{URI of suggested annotation}"/>
  }
</getAlternativesFor>

Example:

<getAlternativesFor>
  <suggestion uri="http://example.com/Annotations/sugg/458784"/>
  <suggestion uri="http://example.com/Annotations/sugg/547"/>
  <suggestion uri="http://example.com/Annotations/sugg/35"/>
</getAlternativesFor>

Suggestion confirmation

Confirmation of the suggestion of annotation is a process which is initiated by the user. The goal is to create common annotation from the suggested one.

Note: If the user is confirming suggestion with nested or linked suggestions, it is necessary to confirm also all these suggestions to satisfy all dependencies. All rules apply also for these suggestions which can lead to confirm complex hierarchy of suggestions by one user's mouse click.

Request

Client can confirm the suggestion by sending of the following message:

<confirmSuggestions>
  {list of suggestions in following format:
    <suggestion modified="false"
                uri="{URI of suggestion of annotation}"/>
  }
</confirmSuggestions>

Eventually:

<confirmSuggestions>
  {list of suggestions in following format:
    <suggestion modified="true">
      {annotation in element oa:Annotation}
    </suggestion>
  }
</confirmSuggestions>

Attribute modified indicates whether suggested annotation was modified before confirmation. Possible values:

Example of whole message:

<confirmSuggestions>
  <suggestion uri="http://example.com/Annotations/sugg/111684"
              modified="false"/>
  <suggestion uri="http://example.com/Annotations/sugg/58568"
              modified="false"/>
</confirmSuggestions>

Response

Server will send mapping of suggUri to servUri:

<suggestionsConfirmed>
  {list of suggestions in following format:
    <suggestion suggUri="{URI of suggestion of annotation}"
                servUri="{URI of annotation}"/>
  }
<suggestionsConfirmed>

Example:

<suggestionsConfirmed>
  <suggestion suggUri="http://example.com/Annotations/sugg/111684"
              servUri="http://example.com/Annotations/serv/5557"/>
  <suggestion suggUri="http://example.com/Annotations/sugg/481"
              servUri="http://example.com/Annotations/serv/1"/>
</suggestionsConfirmed>

Client then must replace all occurrences of suggUri by servUri and transform the suggestions to the annotations.

Refusing of suggestion

Client can refuse the suggestion using following message:

<refuseSuggestions>
  {list of suggestions in following format:
    <suggestion uri="{URI of suggestion of annotation}"/>
  }
</refuseSuggestions>

Example:

<refuseSuggestions>
  <suggestion uri="http://example.com/Annotations/sugg/111684"/>
  <suggestion uri="http://example.com/Annotations/sugg/1878"/>
</refuseSuggestions>

Server does not respond to this message.

Controlled vocabulary

Controlled vocabulary is a database of entities which are representing various real world objects (even physical or abstract). These entities can be used as a values of attributes. Entities have own types, eg.:

Retrieving of entity types

Client can retrieve list of entity types using following message:

Request

<getEntityTypes/>

Response

<entityTypes>
  {list of entity types in following format:
    <type name="{name of type}"
          description="{description of type}"/>
  }
</entityTypes>

Example of response:

<entityTypes>
  <type name="artwork"
        description="A work of an artist, considered to has both spiritual and monetary value."/>
</entityTypes>

Retrieving of entities

Request

Client can request for entities from controlled vocabulary. Communication is asynchronous for this request as it can take some time to traverse a big dictionary. Request is following:

<getEntities name="{name of entity}"
             {optionally: type="{type of entity}"}
             {optionally: maxResults="{max. number of results}"}/>

Attributes:

Note: High value of returned entities or omission of the limit can lead to serious performance problems.

Example of request:

<getEntities type="artwork"
             name="Sunflowers"/>

Response

<entities name="{name of entity from the request}"
          {volitelně: type="{type of entity from the request}"}>
  {list of entities in following format:
    <entity name="{name of entity}"
            uri="{URI of entity}"
            type="{type of entity}"
            image="{URI of image of entity}">
      {optionally:
        <description>
          <![CDATA[{description of entity}]]>
        </description>
      }
      {more optional attributes of entity}
    </entity>
  }
</entities>

Attribute type of element entities is presented only if it was presented in the request.

Example of response:

<entities type="artwork"
          name="Sunflowers">
  <entity name="Four Cut Sunflowers"
          uri="http://www.freebase.com/m/04d7gfr"
          type="artwork"
          image="http://athena3.fit.vutbr.cz/kb/images/freebase/04d8b77.jpg">
    <description>
      <![CDATA[Four Cut Sunflowers (Aug.-Sept. 1887) is one of a series of sunflower-themed paintings by Dutch painter Vincent van Gogh. The painting is currently owned by the Krller-Mller Museum in Otterlo.]]>
    </description>
    <artist>Vincent van Gogh</artist>
    <subject>Sunflower</subject>
    <location>Kröller-Müller Museum</location>
    <owner>Kröller-Müller Museum</owner>
    <more_information type="http://www.w3.org/2001/XMLSchema#anyUri">http://artmight.com/Artists/Vincent-van-Gogh-1853-1890/four-cut-sunflowers-paris-51204p.html</more_information>
  </entity>
  <entity name="Vase with Five Sunflowers"
          uri="http://www.freebase.com/m/044dnb2"
          type="artwork"
          image="http://athena3.fit.vutbr.cz/kb/images/freebase/044dnjv.jpg"/>
</entities>

Optional attribute type of additional attribute of entity can contain URI of type String or URI from table above. Default value is http://www.w3.org/2001/XMLSchema#string.

Settings

Settings is a set of parameters related to client or server (or both). Each user have own set of parameters stored on the server. These parameters can be read and written by the client as it is needed.

Retrieving of settings from the server

For retrieving of settings from the server client uses message settings:

<settings>
  {list od parameters in following format:
    <param name="{name of parameter}"
           value="{value of parameter}"
           {optionally: description="{description of parameter}"}/>
  }
</settings>

Name of parameter should have format

Description of parameter is usable especially for non standard parameters (eg. settings for some specific server module).

Example:

<settings>
  <param name="ClientAnnotationTypeColor:Animal->Human"
         value="green"/>
  <param name="ClientAnnotationTypeColor:City"
         value="blue"/>
</settings>

Server will send this message after user log in (along with message logged) and in case of any change in parameter list. Client reacts to this message by dropping its current list of parameters and replaces it with received one (including all actions required to apply new settings).

Changing of parameters

Client can change parameters in the list of settings. To the following message only parameters which should be changed will be included:

<updateParameters>
  {list od parameters in following format:
    <param name="{name of parameter}"
           {optionally: value="{value of parameter}"}
           {optionally: description="{description of parameter}"}/>
  }
</updateParameters>

Note: If client needs to remove value of parameter, it will set attribute value to the empty string. If client needs to remove whole parameter, it will not include attribute value.

Example:

<updateParameters>
  <param name="ClientAnnotationTypeColor:Animal->Human"
         value="red"/>
  <param name="ClientAnnotationTypeColor:City"
         value="silver"/>
</updateParameters>

Server does not respond to this message. Nor with message settings.

Errors and warningsí

Error message

<error code="{error code}">
  <message>
    <![CDATA[{error description}]]>
  </message>
  {optional context of error}
</error>

Attribute code contains error code.

In some special cases attribute code can be replaced by attribute number. It is due to backward compatibility with protocol 1.0 in cases where it is not possible to determine protocol version on server's side (eg. unknown session number or bad request).

Macro {error description} form detailed description of the error which can be displayed to the user. Language of error message depends on parameter ServerLanguage in settings. Values of this parameter are according to ISO 639-2 (for bibliographic purposes). Default value is eng (english).

Macro {optional context of error} is composed from optional elements which are closer specifying error occurred.

Example:

<error code="access denied">
  <message>
    <![CDATA[Access to selected annotation denied.]]>
  </message>
  <annotation uri="http://example.com/Annotations/serv/482"/>
</error>

Warning message

Warning message has same format as an error message but element with message is warning:

<warning code="{warning code}">
  <message>
    <![CDATA[{description of warning}]]>
  </message>
  {optional context of warning}
</warning>

Example:

<warning code="fragments changed">
  <message>
    <![CDATA[Fragments of your annotations has been changed.]]>
  </message>
  <annotations>
    <annotation uri="http://example.com/Annotations/serv/17"/>
    <annotation uri="http://example.com/Annotations/serv/232"/>
    <annotation uri="http://example.com/Annotations/serv/88"/>
  </annotations>
</warning>

List of error codes

"0" - Unsupported protocol version.
"bad credentials" - Bad login or password.
"permission denied" - Permission to selected annotation denied.
"read only" - Read only access - annotation not saved.
"change not permitted" - Change not permitted.
"removing not permitted" - Removing not permitted.
"attribute required" - Missing mandatory attributes.
"attribute value" - Bad attribute value.
"sug fragment" - Bad selection of fragment - suggestions is not possible.
"sync error different" - Synchronization failed - there is registered different content with this URI.
"sync error not possible" - Synchronization is not possible.
"sync error need resync" - Synchronization error.
"type add not permitted" - Addition of annotation types is not permitted.
"attribute type unavailable" - Type of attribute not exists.
"type malformed" - Annotation type is malformed.
"type attributes malformed" - Annotation type attributes are malformed.
"type unknown" - Type of annotation does not exists.
"type name modify" - Modification of annotation type name, ancestor or group is not possible.
"settings malformed" - Error in settings.
"missing document uri" - Synchronization message without document address.
"missing document content" - Synchronization message without document content.
"bad fragment" - Bad annotated fragment.
"attribute malformed" - Attribute of annotation is malformed.
"bad confirm" - Bad suggestion URI or unrecognized modify.
"changed annot not found" - Changed annotation was not found. Changes was not saved.
"rem annot not found" - Annotation to remove was not found. Annotation was not removed.
"session expired" or "31" - Session expired or bad session number.
"bad request" or "32" - Bad request. Possible client error or incompatible protocol.
"module error" - Error in server module.
"reload annot not found" - Requested annotation was not found.
"bad document" - Error in annotated document.
"annot malformed" - Errors in annotation.
"modification not applicable" - Modification of document is not applicable.
"bad sugg type" - Unknown annotation type - it is not possible to suggest such annotations.
"not synchronized" - Document is not synchronized. Manipulation with annotations is not possible.
"unknown group" - Unknown user group.
"used type del" - Removing of used types is not allowed. You must remove annotations of this type first.
"persistence error" - Server internal error caused that data has not been saved.
"duplicit type" - Duplicit annotation type URI.
"bad modification" - Description of document modification is bad.
"type w subtype del" - Deletion of used types is not allowed. You must delete subtypes first.
"ambiguous fragment" - Ambiguous fragment (found in more than one place in document).
"bad document uri" - Bad URI of annotated document.
"type ancestors malformed" - Annotation type ancestors are malformed.
"join administrators" - You can't join to group with administrators. Only administrator can do that.
"last admin" - You can't leave group with administrators, because You are the last administrator.
"auto update failed" - Some annotations should be updated, but these changes cannot be saved.
"SEC not available" - SEC (Semantic Enrichment Component) server is not available (suggestions will not be available).
"sync error other different" - Another client is holding a different version of this document.
"empty entity filter" - Empty filter for name in query for entities.
"unknown sub uri" - URI of subscription was not found.
"subscription malformed" - Subscription is malformed.
"empty composite" - Composite of fragments is empty.
"duplicit attribute of type" - Duplicit attribute of type of annotation.
"missing confidence" - Missing minimal confidence in request for suggestions.
"bad max entities" - Bad format of maximum of results in request for entities.
"not in group" - User is not in any group - it is not possible to manipulate with annotation types, annotations etc.
"unsupported operation" - Unsupported operation.
"unknown error" - Unknown error.
"suggestions not ready" - Suggestions are not ready, please try it later.
"missing modified sug" - Modified suggestion is missing.
"modification specification" - Wrong specification of modification.
"duplicit subscription" - Duplicit subscription was found.
"bad autoconfirm" - Bad confidence value for automatic confirmation of suggestions.

List of warning codes

"server error" - Noncritical server internal error.
"annot superseded" - Annotation was superseded.
"annot orphaned" - Annotation was orphaned.
"annot updated" - Annotation was automatically updated.
"annot partially orphaned" - Annotation was partially orphaned.
"not logged" - You are not logged in. You can only log in or disconnect (other messages will be discarded).
"fragments updated" - Annotated fragments were updated.

Authors: Ing. Jaroslav Dytrych (idytrych@fit.vutbr.cz), Bc. Jakub Macháček