{{{
#!html
<h3>Contents</h3>
}}}

[[PageOutline(1-3, , inline)]]

{{{
#!comment
Obviously, your page starts below this block 
}}}


= XSD Schema =

== Preamble ==

The xsd schema is designed according to the following paradigm:

-- There are 7 sorts of resources in DASISH: {{{CachedRepresentation}}}, {{{Source}}}, {{{User}}}, {{{Annotation}}}, {{{Notebook}}}, {{{Lists of Permissions}}}, {{{Lists of Versions}}}.

-- There are 6 xsd-types corresponding to the serialisations of all the types of resources above,  except {{{CachedRepresentation}}}. There is no an xsd-schema type corresponding  to {{{Cached representation}}} because a cached representation is  a "pure" resource like an image or a text file that does not contain any meta-information about itself. The metadata of a cached presentation are defined via an instance of {{{CachedRepresentationInfo}}}.

--  Each of these 6 types has an obligatory attribute "URI" which contains DASISH identifier pointing to the location of the resource on the DASISH server.

-- There are corresponding lists-of-reference types: {{{CachedRepresentations}}}, {{{Sources}}}, {{{Users}}}, {{{Annotations}}}, {{{Notebooks}}}. Their names are just plural English forms of the corresponding types.  

-- There are corresponding resource-info types: {{{CachedRepresentationInfo}}},  {{{SourceInfo}}}, {{{UserInfo}}}, {{{AnnotationInfo}}}, {{{NotebookInfo}}}. They contain reference to the corresponding resource plus the most important information about the resource. 

-- There are  corresponding list-of-resource-info types:  {{{SourceInfos}}}, {{{UserInfos}}}, {{{AnnotationInfos}}}, {{{NotebookInfos}}}. 

There is a number of auxiliary types as well. A commonly-used one is ResourceREF which contains the attribute "ref" of type {{{xs:anyURI}}}. It allows to declare elements-references and avoid mixing them with elements-resources. 

=== Handling new (not yet in the DB) sources ===

Adding annotation with the target sources which are not yet in the DB needs special treatment. It becomes clear when the POST body for a new annotation must be serialized. Two approaches seem to be plausible. We will follow the FIRST option. 

1) A "strongly-typed" schema. An annotation contains a list of elements-"targets". Each of them can be  either a source element or a new-source element. It is implemented using xs:choice construct for elements. A source and a new-source element differs by one attribute: a source has obligatory "ref" attribute, and a new source has an obligatory "xml:id" attribute. 

See [source:DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd DASISH-schema]

2) A "weakly-typed" schema. An annotation contain a list of elements-"targets" of the same type that contains two non-obligatory attributes: "ref" and "xml:id". The type-checking "''at least one of the attributes is present and they are mutually exclusive''" may be left for later to schematron or so.

See [source:DASISH/t5.6/docs/XMLandXSD/DASISH-schema-alternative.xsd DASISH-alternative-xsd].

The link to the second, "weakly-typed",  version of the XSD-schema is left for the reference, however this version is not maintained any more.


= Scenario XML's validated vs the given schema =

See [[DASISH/Scenario]]

=== GET api/user/00000000-0000-0000-0000-000000000112 ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns="http://www.dasish.eu/ns/addit"
 eMail="Peter.Withers@mpi.nl" 
displayName="Peter" 
URI="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000112" 
xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd"/>
}}}

=== GET api/users/00000000-0000-0000-0000-0000000000112/current ===

{{{#!xml
<currentUserInfo currentUser="false" 
ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000112" 
xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd"/>
}}}

=== GET api/users/info?email=twagoo@mpi.nl  ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<user xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xmlns="http://www.dasish.eu/ns/addit" 
eMail="twagoo@mpi.nl" displayName="Twan"
URI="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000111"
xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd"/>
}}}

== Retrieving annotations ==

=== Responding GET api/annotations?link=Sagrada ===
all annotations which annotating links containing "Sagrada"


{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<annotationInfoList xmlns="http://www.dasish.eu/ns/addit" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
    <annotationInfo headline="Sagrada Famiglia Dutch" 
      ownerRef="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113" 
      lastModified="2013-12-13T14:54:23.372132Z" 
      ref="http://localhost:8080/annotator-backend/api/annotations/09e1ebaf-fca6-4509-ac26-362b2301f37f">
        <targets>
            <ref>http://localhost:8080/annotator-backend/api/targets/15a7ff2c-ee9e-4eb1-b51a-6b20c6df0218</ref>
        </targets>
    </annotationInfo>   
    <annotationInfo headline="Sagrada Famiglia" 
      ownerRef="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000111" 
      lastModified="2013-08-12T11:25:00.383Z"
       ref="http://localhost:8080/annotator-backend/api/annotations/00000000-0000-0000-0000-000000000021">
        <targets>
            <ref>http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-000000000031</ref>
            <ref>http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-000000000032</ref>
        </targets>
    </annotationInfo>
</annotationInfoList>
}}}



=== Responding GET api/annotations/00000000-0000-0000-0000-000000000021 ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<annotation xmlns="http://www.dasish.eu/ns/addit" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" headline="Sagrada Famiglia" 
ownerRef="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000111" 
lastModified="2013-08-12T11:25:00.383Z" 
URI="http://localhost:8080/annotator-backend/api/annotations/00000000-0000-0000-0000-000000000021"
xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
    <body>
        <textBody mimeType="text/html">&lt;html&gt;&lt;body&gt;some html 1&lt;/body&gt;&lt;/html&gt;</textBody>
    </body>
    <targets>
        <targetInfo version="version 1.0" link="http://nl.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#De_opdracht" ref="http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-000000000031"/>
        <targetInfo version="version 1.0" link="http://nl.wikipedia.org/wiki/Antoni_Gaud%C3%AD#Vroege_werk" ref="http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-000000000032"/>
    </targets>
    <permissions>
        <userWithPermission permission="owner" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000111"/>
        <userWithPermission permission="writer" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000112"/>
        <userWithPermission permission="reader" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113"/>
    </permissions>
</annotation>
}}}

=== GET api/annotations/00000000-0000-0000-0000-000000000021/targets ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<targetList xmlns="http://www.dasish.eu/ns/addit" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
    <ref>http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-000000000031</ref>
    <ref>http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-000000000032</ref>
</targetList>
}}}

=== GET api/annotations/00000000-0000-0000-0000-000000000021/permissions ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<permissionList xmlns="http://www.dasish.eu/ns/addit" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
    <userWithPermission permission="owner" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000111"/>
    <userWithPermission permission="writer" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000112"/>
    <userWithPermission permission="reader" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113"/>
</permissionList>
}}}


=== GET api/targets/00000000-0000-0000-0000-000000000032 ===

An unresolvable target obeys the same schema. A target becomes unresolvable if e.g. its link becomes obsolete or broken.

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<target xmlns="http://www.dasish.eu/ns/addit" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
version="version 1.0" 
link="http://nl.wikipedia.org/wiki/Antoni_Gaud%C3%AD#Vroege_werk" 
lastModified="2013-10-17T16:31:31.838Z" 
URI="http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-000000000032" 
xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
    <siblingTargets>
        <ref>http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-000000000032</ref>
    </siblingTargets>
    <cachedRepresentatinons>
        <cached fragmentString="(1,0)" ref="http://localhost:8080/annotator-backend/api/cached/00000000-0000-0000-0000-000000000052"/>
    </cachedRepresentatinons>
</target>
}}}

=== GET api/targets/00000000-0000-0000-0000-000000000032/versions ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<referenceList xmlns="http://www.dasish.eu/ns/addit" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
    <ref>http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-000000000032</ref>
</referenceList>
}}}

=== GET api/cached/00000000-0000-0000-0000-000000000051/metadata ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cashedRepresentationInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns="http://www.dasish.eu/ns/addit" 
   type="image" 
   tool="apple-screen-shot" 
   mimeType="image/png"
    URI="http://localhost:8080/annotator-backend/api/cached/00000000-0000-0000-0000-000000000051" 
    xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd"/>
}}}




=== Responding GET api/annotations/00000000-0000-0000-0000-00000000002c (example usage for unresolvable targets  1) ===

The respond for an annotation with unresolved targets and the respond for an annotation with resolved targets (see above) are both instances of the same schema element.  However, one of the targets of the first annotations annotation refers e.g. to an obsolete version of the page. Next, having the target eferences, the client will ask for the source versions saved in the DB. The last step: having the info about the version under consideration, the client asks for cached representations of the version.

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<annotation xmlns="http://www.dasish.eu/ns/addit" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" headline="Sagrada Famiglia" 
ownerRef="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000111" 
lastModified="2013-08-12T11:25:00.383Z" 
URI="http://localhost:8080/annotator-backend/api/annotations/00000000-0000-0000-0000-00000000002c"
xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
    <body>
        <textBody mimeType="text/html">&lt;html&gt;&lt;body&gt;some html 1&lt;/body&gt;&lt;/html&gt;</textBody>
    </body>
    <targets>
        <targetInfo version="version 0.0" link="http://nl.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#De_opd" ref="http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-00000000003c"/>
        <targetInfo version="version 1.0" link="http://nl.wikipedia.org/wiki/Antoni_Gaud%C3%AD#Vroege_werk" ref="http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-000000000032"/>
    </targets>
    <permissions>
        <userWithPermission permission="owner" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000111"/>
        <userWithPermission permission="writer" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000112"/>
        <userWithPermission permission="reader" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113"/>
    </permissions>
</annotation>
}}}




=== Responding GET api/targets/00000000-0000-0000-0000-00000000003c (unresolvable target sources 2, the same as for resolvable, just the link is broken or obsolete) ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<target xmlns="http://www.dasish.eu/ns/addit" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
version="version 0.0" 
link="http://nl.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#De_opd" 
lastModified="2013-10-17T16:31:31.838Z" 
URI="http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-00000000003c" 
xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
    <siblingTargets>
        <ref>http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-00000000003c</ref>
    </siblingTargets>
    <cachedRepresentatinons>
        <cached fragmentString="(0,0),(1024, 1024)" ref="http://localhost:8080/annotator-backend/api/cached/00000000-0000-0000-0000-00000000005c"/>
    </cachedRepresentatinons>
</target>
}}}


=== Responding GET api/targets/00000000-0000-0000-0000-00000000003c/versions (unresolvable target sources 3) ===

The target has only one version in this case: itself.

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<referenceList xmlns="http://www.dasish.eu/ns/addit" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
    <ref>http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-00000000003c</ref>
</referenceList>
}}}

=== Responding GET api/cached/00000000-0000-0000-0000-00000000005c/metadata  (unresolvable target sources 4) === 

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<cashedRepresentationInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
    xmlns="http://www.dasish.eu/ns/addit" 
    type="image" 
   tool="apple-screen-shot" 
   mimeType="image/png" 
   URI="http://localhost:8080/annotator-backend/api/cached/00000000-0000-0000-0000-00000000005c" 
   xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd"/>
}}}

== Making a new annotation ==

=== Request body for POST api/annotations ===

The new annotation URI, the owner reference  will be replaced by the server. The new annotation URI is service URI + the UUID generated by the server.  The owner reference is the service URI + logged-in user UUID.

The targets's URI will be replaced if the target is new (has not been presented in the dtatabase yet).

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<annotation 
    xmlns="http://www.dasish.eu/ns/addit"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.dasish.eu/ns/addit file:/Users/olhsha/repositories/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd"
    xmlns:xhtml="http://www.w3.org/1999/xhtml/"
    lastModified="2013-09-29T19:52:28.969+02:00" 
    URI="zzz"
    ownerRef = "xxx"
    headline = "Sagrada Famiglia Dutch 2"
    >
    <body>
        <xmlBody mimeType="application/xml+xhtml">
            <xhtml:span style="background-color:rgb(0,0,153);color:rgb(255,255,255);border: thick solid rgb(0, 0, 153);">Some background information on Sagrada Família.</xhtml:span>
            </xmlBody>
    </body>
    <targets>
        <targetInfo ref="http://localhost:8080/annotator-backend/api/targets/00000000-0000-0000-0000-0000000000cc"
            link ="http://nl.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia"
            version="Version 1.0"/>
    </targets>
    <permissions>
        <userWithPermission permission="owner" ref="ZZZ"/>
    </permissions>
</annotation>
}}}


 

=== Response body (envelope) for POST api/annotations ===

The temporary URIs/references  are  replaced with permanent references. However, no cahced representation is found for the target. Therefore, in the action part of the envelope there is an action CREATE_CACHED_REPRESENTATION for the object which is the target for the web-page.

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<responseBody xmlns="http://www.dasish.eu/ns/addit" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
  <annotation headline="Sagrada Famiglia Dutch 2" ownerRef="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113" lastModified="2013-12-18T09:50:43.803706Z" URI="http://localhost:8080/annotator- backend/api/annotations/7e7609d9-a04e-41bc-b773-337a11210336">
     <body>
         <xmlBody mimeType="application/xml+xhtml">
            <xhtml:span xmlns:xhtml="http://www.w3.org/1999/xhtml/" style="background-color:rgb(0,0,153);color:rgb(255,255,255);border: thick solid rgb(0, 0, 153);">Some background information on Sagrada Família.</xhtml:span>
         </xmlBody>
    </body>
    <targets>
       <targetInfo version="Version 1.0" link="http://nl.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia" ref="http://localhost:8080/annotator-backend/api/targets/1ad5928a-8957-42ea-be67-02eb9f334647"/>
    </targets>
    <permissions>
       <userWithPermission permission="owner" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113"/>
    </permissions>
   </annotation>
   <actionList>
      <action message="CREATE_CACHED_REPRESENTATION" object="http://localhost:8080/annotator-backend/api/targets/1ad5928a-8957-42ea-be67-02eb9f334647"/>
   </actionList>
</responseBody>
}}}

The client sends metadata cached representation in the POST body, and a cached representation itself. An example of serialized metadata  for a cached representation has been considered above, so we do not give it here.


== Editing an annotation ==

=== PUT api/annotations/6a01ba7b-2a15-47d4-bf1c-a14b46eb953f ===

Request body : an updated annotation

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<annotation 
    xmlns="http://www.dasish.eu/ns/addit"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.dasish.eu/ns/addit file:/Users/olhsha/repositories/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd"
    timeStamp="2013-09-29T19:52:28.969+02:00" 
    URI="http://localhost:8080/annotator-backend/api/annotations/6a01ba7b-2a15-47d4-bf1c-a14b46eb953f"
    ownerRef = "http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113"
    headline = "Sagrada Famiglia Dutch"
    >
    <body>
        <textBody mimeType="text/plain">
            Construction process of S.F.
        </textBody>
    </body>
    <targets>
        <targetInfo ref="http://localhost:8080/annotator-backend/api/sources/00000000-0000-0000-0000-0000000000cc"
            link ="http://nl.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Bouw"
            version="Version 1.0"/>
    </targets>
    <permissions>
        <userWithPermission permission="owner" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113"/>
    </permissions>
</annotation>
}}}

Enveloped respond containing  new (updated) annotation and a list of actions:

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<responseBody xmlns="http://www.dasish.eu/ns/addit" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
  <annotation headline="Sagrada Famiglia Dutch" ownerRef="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113" lastModified="2013-12-18T10:09:43.952594Z" URI="http://localhost:8080/annotator- backend/api/annotations/6a01ba7b-2a15-47d4-bf1c-a14b46eb953f">
    <body>
      <textBody mimeType="text/plain">
          Construction process of S.F.
      </textBody>
      </body>
      <targets>
        <targetInfo version="Version 1.0" link="http://nl.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Bouw" ref="http://localhost:8080/annotator-backend/api/targets/7f09b2fe-0fce-4570-8071-1cc57fa26f3c"/>
      </targets>
      <permissions>
        <userWithPermission permission="owner" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113"/>
      </permissions>
  </annotation>
  <actionList>
    <action message="CREATE_CACHED_REPRESENTATION" object="http://localhost:8080/annotator-backend/api/targets/7f09b2fe-0fce-4570-8071-1cc57fa26f3c"/>
   </actionList>
</responseBody>
}}}


=== PUT api/annotations/6a01ba7b-2a15-47d4-bf1c-a14b46eb953f/body ===

Request body:

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<annotationBody xmlns="http://www.dasish.eu/ns/addit"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xhtml="http://www.w3.org/1999/xhtml/" 
    xsi:schemaLocation="http://www.dasish.eu/ns/addit file:/Users/olhsha/repositories/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
    <xmlBody mimeType="application/xml">
        <any>
            <xhtml:span style="background-color:rgb(0,0,153);color:rgb(255,255,255);border: thick solid rgb(0, 0, 153);">Some background information on Sagrada Família. attempt # 1</xhtml:span>
        </any>
    </xmlBody>
</annotationBody>
}}}

Response:

{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<responseBody xmlns="http://www.dasish.eu/ns/addit" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
   <annotation headline="Sagrada Famiglia Dutch" ownerRef="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113" lastModified="2013-12-19T13:36:47.543945Z" URI="http://localhost:8080/annotator-backend/api/annotations/6a01ba7b-2a15-47d4-bf1c-a14b46eb953f">
      <body>
         <xmlBody mimeType="application/xml">
            <any xmlns:xhtml="http://www.w3.org/1999/xhtml/">
                  <xhtml:span style="background-color:rgb(0,0,153);color:rgb(255,255,255);border: thick solid rgb(0, 0, 153);">Some background information on Sagrada Família. attempt # 1</xhtml:span>
            </any>
         </xmlBody>
      </body>
      <targets>
         <targetInfo version="Version 1.0" link="http://nl.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Bouw" ref="http://localhost:8080/annotator-backend/api/targets/db66c15c-aa35-4d16-8fc7-619f1fbef128"/>
      </targets>
      <permissions>
         <userWithPermission permission="owner" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113"/>
      </permissions>
   </annotation>
   <actionList>
      <action message="CREATE_CACHED_REPRESENTATION" object="http://localhost:8080/annotator-backend/api/targets/db66c15c-aa35-4d16-8fc7-619f1fbef128"/>
   </actionList>
</responseBody>
}}}


=== PUT api/annotations/6a01ba7b-2a15-47d4-bf1c-a14b46eb953f/permissions ===


Supplementary updating the list of permissions in the annotation:

Example 1.

Request body: 
{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<userWithPermissionList xmlns="http://www.dasish.eu/ns/addit"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.dasish.eu/ns/addit file:/Users/olhsha/repositories/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
    <userWithPermission ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000111" permission="reader"/>
    <userWithPermission ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000112" permission="writer"/>
 </userWithPermissionList>
}}}


Respond
{{{#!xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<responseBody xmlns="http://www.dasish.eu/ns/addit" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
   <permissions>
      <userWithPermission permission="owner" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113"/>
      <userWithPermission permission="reader" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000111"/>
      <userWithPermission permission="writer" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000112"/>
   </permissions>
  <actionList/>
</responseBody>
}}}


Example 2: user 00000000-0000-0000-0000-000000000114 is not known to the DASISH data base

Request body: 
{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<userWithPermissionList xmlns="http://www.dasish.eu/ns/addit"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://www.dasish.eu/ns/addit file:/Users/olhsha/repositories/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
    <userWithPermission ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000111" permission="reader"/>
    <userWithPermission ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000114" permission="writer"/>
 </userWithPermissionList>
}}}


Respond
{{{#!xml
    <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
    <responseBody xmlns="http://www.dasish.eu/ns/addit" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.dasish.eu/ns/addit https://svn.clarin.eu/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
    <permissions>
       <userWithPermission permission="owner" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000113"/>
       <userWithPermission permission="reader" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000111"/>
       <userWithPermission permission="writer" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000112"/>
       <userWithPermission permission="writer" ref="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000114"/>
    </permissions>
    <actionList>
        <action message="PROVIDE_USER_INFO" object="http://localhost:8080/annotator-backend/api/users/00000000-0000-0000-0000-000000000114"/>
    </actionList>
    </responseBody>
}}}

=== PUT api/annotations/6a01ba7b-2a15-47d4-bf1c-a14b46eb953f/permissions/00000000-0000-0000-0000-000000000111 ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<permission xmlns="http://www.dasish.eu/ns/addit"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.dasish.eu/ns/addit file:/Users/olhsha/repositories/DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd">
   writer
</permission>
}}}

Response: string "1 rows are updated/added". 


== Managing Notebooks  (obsolete section) ==

=== GET api/notebooks ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<notebooks xmlns="http://www.dasish.eu/ns/addit"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.dasish.eu/ns/addit http://dasish.eu/DASISH-schema.xsd">
    <notebook ref="http://dasish.eu/notebooks/NIDxyxy">
        <title>Gaudi</title>
    </notebook>
    <notebook ref="http://dasish.eu/notebooks/NIDxefef">
        <title>Douglas Adams</title>
    </notebook>
</notebooks>
}}}


=== GET api/notebooks/NIDxyxy ===


{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<notebook xmlns="http://www.dasish.eu/ns/addit"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.dasish.eu/ns/addit
 http://dasish.eu/DASISH-schema.xsd" 
 ref="http://dasish.eu/notebooks/NIDxyxy">
    <title>Gaudi</title>
</notebook>
}}}

=== GET api/notebooks/NIDxyxy/annotations/ ===

Respond is a list of annotation info,  is similar to the respond on 

 {{{GET api/annotations?link="http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia"&access=read}}}.


= Issues with the schema =

As regards all future schema updates, please make sure to remember to update all available scenario xml documents on trac.clarin.eu accordingly, and preferably, with as little delay as possible. It might also be a good idea to validate all of these documents against the revised schema with a reliable XML parser like e.g. the Xerces-J XML parser. Also, if you like, you can check by validating some of our current "real-life" mock xml documents that we have been using for client development ([source:DASISH/t5.6/client/trunk/chrome/markingcollection/content/markingcollection/annotator-service/test/mockjax/mocks]).


== Cached Representation BLOB  ==

For the back-end (and the database!):  the cached representation for now is stored in the database as a BLOB. See: http://dba.stackexchange.com/questions/803/blobs-or-references-in-postgresql/815#815. 

Also, see https://trac.clarin.eu/ticket/366
[[BR]][[BR]]
''Stephanie:'' Please define what data needs to be sent from the client regarding cached representations (the HTML markup, any css files, images, ...?). In Wired-Marker, what is called "cache" is a locally saved copy of the HTML markup plus a css file with content aggregated from the css files used by the original website (cf. DiscussionPage: Answer 1 on Versioning).

''Twan:'' no specific format is expected but in the current specification 'a cached representation' matches up with a single file. So according to this the client should choose a representation that can be represented as a single file or use some method of wrapping multiple files up into a single entity. Apart from that, the exact nature of the cached representation is taken to be client specific, so you can choose what format suits the plugin best. If the current single file situation really turns out to be problematic, let us know and we could consider alternative solutions that do support grouping multiple files together as a single cached representation entity.

''Olof + Stephanie:'' For a start, we can tune the client to send the HTML representation as a single file only. A refined solution might be to extend the content of this file by adding the complete, aggregated css content from the stylesheets inline, i.e. within the range of {{{<style...> ... </style>}}} in the {{{<head>}}}-tag.

''Olha, Menzo, Twan:'' If that's relatively easy for you to do, that would probably suffice in the initial phase. For a more complete solution (i.e. including images, scripts etc) you could perhaps consider [https://en.wikipedia.org/wiki/MHTML MIME HTML] or alternatively something like [https://en.wikipedia.org/wiki/Mozilla_Archive_Format the Mozilla Archive Format]. Cross-browser support could be a bit of an issue there but the situation does not look too bad.