{{{
#!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]]

== Responding GET api/user/uid ==


{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<currentUserInfo 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/users/UIDefef"
 currentUser="true"/>
}}}

== Retrieving annotations ==

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

The root element below is of type {{{AnnotationInfos}}} (the list of {{{AnnotationInfo}}}).

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- list of annotation-infos -->
<annotations 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">
    <annotation ref="http://dasish.eu/annotations/AIDxyxy">
        <owner ref="http://dasish.eu/users/UIDefef"/>
        <headline>My client is not in a hurry</headline>
        <targetSources>
            <targetSource ref="http://dasish.eu/sources/SIDacdc"/>
        </targetSources>
    </annotation>
    <annotation ref="http://dasish.eu/annotations/AIDzzz">
        <owner ref="http://dasish.eu/users/UIDe1fe1f"/>
        <headline>Nativity Facade</headline>
        <targetSources>
            <targetSource ref="http://dasish.eu/sources/SIDaacc"/>
            <targetSource ref="http://dasish.eu/sources/SIDaaaa"/>
        </targetSources>
    </annotation>
    <annotation ref="http://dasish.eu/annotations/AIDzyy">
        <owner ref="http://dasish.eu/users/UIDefef"/>
        <headline>Nativity Facade (old site)</headline>
        <targetSources>
            <targetSource ref="http://dasish.eu/sources/SIDbbbb"/>
            <targetSource ref="http://dasish.eu/sources/SIDrrrr"/>
        </targetSources>
    </annotation>
</annotations>
}}}



=== Responding GET api/annotations/AIDzzz (example of resolvable target sources) === 


{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- annotation as it is presented in the DB;
    (also sent in the respond envelope after creating/updating an annotation, 
    if its targets  are resolved) --> 
<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 http://dasish.eu/DASISH-schema.xsd"
    URI="http://dasish.eu/annotations/AIDzzz" timeStamp="2013-05-04T18:13:51.0Z">
    <owner ref="http://dasish.eu/users/UIde1fe1f"/>
    <headline>Nativity Facade</headline>
    <body type="relation">
        <relation>different</relation>
        <this ref="http://dasish.eu/sources/SIDaacc"/>
        <that ref="http://dasish.eu/sources/SIDaaaa"/>
    </body>
    <targetSources>
        <target>
            <source ref="http://dasish.eu/sources/SIDaacc">
                <link>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Nativity_Fa.C3.A7ade</link>
                <version>20.04.2013</version>
            </source>
        </target>
        <target>
            <source ref="http://dasish.eu/sources/SIDaaaa">
                <link>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Passion_Fa.C3.A7ade</link>
                <version>20.04.2013</version>
            </source>
        </target>
    </targetSources>
    <permissions ref="http://dasish.eu/permissions/PermissionsListIDefef"/>
</annotation>
}}}


=== Responding GET api/annotations/AIDzyy (example usage for unresolvable target sources 1) ===

The respond for an annotation with unresolved target sources and the respond for an annotation with resolved target sources (see above) are both instances of the same schema element.  However, the annotation refers to an obsolete version of the page. Next, having the target source references, 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"?>
<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 http://dasish.eu/DASISH-schema.xsd"
    URI="http://dasish.eu/annotations/AIDzyy" timeStamp="2013-05-04T18:13:51.0Z">
    <owner ref="http://dasish.eu/users/UIde1fe1f"/>
    <headline>Nativity Facade (old page)</headline>
    <body type="relation">
        <relation>different</relation>
        <this ref="http://dasish.eu/sources/SIDbbbb"/>
        <that ref="http://dasish.eu/sources/SIDrrrr"/>
    </body>
    <targetSources>
        <target>
            <source ref="http://dasish.eu/sources/SIDbbb">
                <link>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Nativity_Fa.C3.A7ade</link>
                <version>2010-01-29T23:59:59</version>
            </source>
        </target>
        <target>
            <source ref="http://dasish.eu/sources/SIDrrrr">
                <link>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Passion_Fa.C3.A7ade</link>
                <version>2010-01-29T23:59:59</version>
            </source>
        </target>
    </targetSources>
    <permissions ref="http:/dasish.eu/permissions/PrmIdxxx"/>
</annotation>
}}}


=== Responding GET api/sources/SIDbbb (unresolvable target sources 2) ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<source 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" 
 URI="http://dasish.eu/sources/SIDbbbb" 
 timeSatmp="2011-05-04T18:13:51.0Z" 
 link="http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Passion_Fa.C3.A7ade"
 version="2010-01-29T23:59:59">
    <versions-siblings ref="http://dasish.eu/versions/VIDaacc"/>
</source>
}}}


=== Responding GET api/sources/SIDbbb/versions (unresolvable target sources 3) ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<versions 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"
 URI="http://dasish.eu/sources/SIDbbb/versions">
    <version ref="http://dasish.eu/sources/SIDvvvv">
        <version>2010-01-29T23:59:59</version>
        <cachedRepresentations>
            <cachedRepresentation ref="http://dasish.eu/cached/CIDtttt"/>
            <cachedRepresentation ref="http://dasish.eu/cached/CIDefef"/>
        </cachedRepresentations>
    </version>
    <version ref="http://dasish.eu/sources/SIDwww">
        <version>20.04.2013</version>
        <cachedRepresentations>
            <cachedRepresentation ref="http://dasish.eu/cached/CIDabab"/>
            <cachedRepresentation ref="http://dasish.eu/cached/CIDxyxy"/>
            <cachedRepresentation ref="http://dasish.eu/cached/CIDutwz"/>
        </cachedRepresentations>
    </version>
</versions>
}}}

=== Responding GET api/sources/SIDbbb/cached/CIDtttt/metadata (unresolvable target sources 4) === 

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<cashedRepresentation 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/cached/CIDtttt" 
 mimeType="image/png" 
 tool="tool1" 
 type="screenshot"/>
}}}

== Making a new annotation ==

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

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- the request body for POSTing a new annotation -->
<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 http://dasish.eu/DASISH-schema.xsd" 
 URI="tempAIDgfgf"
 timeStamp="2013-05-29T18:13:51.0Z">
    <owner ref="http://dasish.eu/users/UIde1fe1f"/>
    <headline>Comapring English and Catalan Wiki</headline>
    <body type="relation">
        <relation>History</relation>
        <english ref="http://dasish.eu/sources/SIDaaabbb"/>
        <catalan ref="tmpSIDefef"/>  
    </body>
    <targetSources>
        <target>
            <source ref="http://dasish.eu/sources/SIDaaabbb">
            <link>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#History</link>
            <version>20.04.2012</version>
            </source>
        </target>    
        <target>
            <newSource xml:id="tmpSIDefef">
                <link>http://ca.wikipedia.org/wiki/Temple_Expiatori_de_la_Sagrada_Fam%C3%ADlia#Hist.C3.B2tia</link>
                <version>20.04.2013</version>
            </newSource>
        </target>
    </targetSources>
    <permissions ref="tmpPermissionsListIDxyz"/>
</annotation>
}}}


 === Request body for POST api/annotations: another example ===

The serialization of the POST body for another example (UGOT):

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<!-- the request body for POSTing a new annotation -->
<annotation 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 http://dasish.eu/DASISH-schema.xsd" 
    URI="tempAIDgfgf"
    timeStamp="2013-04-26T11:23:26.000Z">
    <owner ref="http://dasish.eu/users/user123"/>
    <headline>Douglas Adams - Wikipedia, the free encyclopedia</headline>
    <body ref="tmpSIDxyxy" type="Note">
        <xhtml:span style="background-color:rgb(253,49,31);color:rgb(0,0,0);">Adams was born 1952-03-11</xhtml:span>
    </body>
    <targetSources>
        <target>
            <newSource xml:id="tmpSIDxyxy">
                <link>http://en.wikipedia.org/wiki/Douglas_adams#xpointer(start-point(string-range(//div[@id="mw-content-text"]/table[1]/tbody[1]/tr[3]/td[1]/text()[1],'',12))/range-to(string-range(//div[@id="mw-content-text"]/table[1]/tbody[1]/tr[3]/td[1]/text()[1],'',25)))</link>
                <version>2013-04-26T11:23:26.000Z</version>
            </newSource>
        </target>
    </targetSources>
    <permissions ref="tmpPermissionsListIDabcd"/>
</annotation>
}}}


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

The temporary id is replaced with the permanent reference. However, no cahced representation is found for the catalan web-page. Therefore, in the action part of the envelope there is an action CREATE_CACHED_REPRESENTATION for the object which is the source for catalan web-page.

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<respondNewAnnotation 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">
    <annotationResponse>
        <content>
            <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 http://dasish.eu/DASISH-schema.xsd" 
                URI="http://dasish.eu/annotations/AIDeegf"
                timeStamp="2013-05-29T18:13:51.0Z">
                <owner ref="http://dasish.eu/users/UIde1fe1f"/>
                <headline>Comapring English and Catalan Wiki</headline>
                <body type="relation">
                    <relation>History</relation>
                    <english ref="http://dasish.eu/sources/SIDaaabbb"/>
                    <catalan ref="http://dasish.eu/sources/SIDcxcx"/>  
                </body>
                <targetSources>
                    <target>
                        <source ref="http://dasish.eu/sources/SIDaaabbb">
                            <link>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#History</link>
                            <version>20.04.2012</version>
                        </source>
                    </target>    
                    <target>
                        <source ref="http://dasish.eu/sources/SIDcxcx">
                            <link>http://ca.wikipedia.org/wiki/Temple_Expiatori_de_la_Sagrada_Fam%C3%ADlia#Hist.C3.B2tia</link>
                            <version>20.04.2013</version>
                        </source>
                    </target>
                </targetSources>
                <permissions ref="http://dasish.eu/permissions/PermissionsListIDxyz"/>
            </annotation>     
        </content>
    <actions>
        <action action="CREATE_CACHED_REPRESENTATION" object="http://dasish.eu/sources/SIDcxcx"/>
    </actions>
    </annotationResponse>
</respondNewAnnotation>
}}}

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 annotation body ==

=== Request: an updated body ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<newBody 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"    
    type="relation"    >
    <relation>History in English and Catalan</relation>
    <english ref="http://dasish.eu/sources/SIDaaabbb"/>
    <catalan ref="http://dasish.eu/sources/SIDcxcx"/> 
</newBody>
}}}

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

The list of actions is empty because there are cached representations for all the target sources.
{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<respondNewAnnotation 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">
    <annotationResponse>
        <content>
            <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 http://dasish.eu/DASISH-schema.xsd" 
                URI="http://dasish.eu/annotations/AIDeegf"
                timeStamp="2013-05-29T18:13:51.0Z">
                <owner ref="http://dasish.eu/users/UIde1fe1f"/>
                <headline>Comapring English and Catalan Wiki</headline>
                <body type="relation">
                    <relation>History in English and Catalan</relation>
                    <english ref="http://dasish.eu/sources/SIDaaabbb"/>
                    <catalan ref="http://dasish.eu/sources/SIDcxcx"/>  
                </body>
                <targetSources>
                    <target>
                        <source ref="http://dasish.eu/sources/SIDaaabbb">
                            <link>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#History</link>
                            <version>20.04.2012</version>
                        </source>
                    </target>    
                    <target>
                        <source ref="http://dasish.eu/sources/SIDcxcx">
                            <link>http://ca.wikipedia.org/wiki/Temple_Expiatori_de_la_Sagrada_Fam%C3%ADlia#Hist.C3.B2tia</link>
                            <version>20.04.2013</version>
                        </source>
                    </target>
                </targetSources>
                <permissions ref="http://dasish.eu/permissions/PermissionsListIDxyz"/>
            </annotation>     
        </content>
    <actions />    
    </annotationResponse>
</respondNewAnnotation>
}}}

== Managing permission lists of users ==

=== GET api/annotations/AIDzyy/permissions ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<permissions 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"
 URI="http:/dasish.eu/permissions/PrmIdxxx">
    <user ref="http://dasish.eu/users/UIde1fe1f" permission="owner"/>
    <user ref="http://dasish.eu/users/UIxyxy" permission="writer"/>
    <user ref="http://dasish.eu/users/UIxxzz" permission="reader"/>
    <user ref="http://dasish.eu/users/UIxaaa" permission="reader"/>
</permissions>
}}}

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

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<user 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/DASISH-schema.xsd" 
 displayName="Alexander G. Corpman" 
 eMail="alecor@mpi.nl" 
 ref="http://dasish.eu/users/UIDagc"/>
}}}

=== PUT api/annotations/AIDzyy/permissions===


Swapping rights of the users xyxy and xxzz: xyxy one becomes a reader, and xxzz becomes a writer. Updating w.r.t. 
the respond {{{GET api/annotations/AIDzyy/permissions}}}  above.

Request body: 
{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<permissions 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"
 URI="http:/dasish.eu/permissions/PrmIdxxx">
    <user ref="http://dasish.eu/users/UIde1fe1f" permission="owner"/>
    <user ref="http://dasish.eu/users/UIxyxy" permission="reader"/>
    <user ref="http://dasish.eu/users/UIxxzz" permission="writer"/>
    <user ref="http://dasish.eu/users/UIxaaa" permission="reader"/>
</permissions>
}}}


Respond body: is an envelope containing this list and no actions, since all the users are presented in the DB.

=== PUT api/annotations/AIDzyy/permissions/UIDagc ===

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<accessLevel 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">writer</accessLevel>
}}}


== Managing Notebooks ==

=== 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 =
== Possible namespace pollution: Ticket 348 to be discussed with Peter  ==

See [https://trac.clarin.eu/ticket/348]

Peter: 
"It looks like there might be some namespace pollution or some other anomaly that causes the jaxb a
uto generated classes to omit the getter for notebooks from the ObjectFactory. This is an issue 
when a jaxb root node is required, such as in the rest interface. A work around has been added 
which makes it clear where the issue is and why the ObjectFactory is required, but this needs to 
be replaced when the schema is updated."[[BR]]
[[BR]]
''Stephanie:'' If indeed, the issue lies with the plural forms of complexType names (used for lists of resources) in the schema, we think that, principally, the plural forms can - and should - be replaced more or less immediately, e.g. by adding the suffix "{{{List}}}" or "{{{Collection}}}" instead of plural "s". For instance, the serialized xml output could then match the following snippet
{{{
<annotationCollection>
   <annotations>
      <annotation>
         <!-- elements of annotation -->
      </annotation>
   </annotations>
</annotationCollection>
}}}
 
By the way, speaking of diverse "JAXB plural issues", there were some hints on the web regarding (inline and external) Java binding customization for JAXB, - it might be that this would also be a viable solution approach. Maybe this thread is worth checking as well: http://stackoverflow.com/questions/11943487/please-advise-the-best-pattern-for-serialising-jaxb-lists?

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 recently for client development ([source:DASISH/t5.6/client/trunk/chrome/markingcollection/content/markingcollection/annotator-service/test/mockjax/mocks]).

=== Resolution ===

The schema is to be fixed. The current hypothesis is that JAXB get confused by plural forms used in the schema in type names for lists of resources, 
e.g. Annotation --> Annotations, Notebook --> Notebooks etc. Replace plural forms with other wording and check if it fixes the problem. 


== New-Or-Existing-Source-Info JAXB-generated class ==

This class corresponds to the choice sub-schema within the schema-type for annotation, which tells if a target source is new or old. This means that 
the client provides the server with this information. 

It is ok, but it makes code a bit hairy. Can we remove the choice and let the backend todecide if the source is new or old, simply by looking through all the sources
to find the one with given external-id/uri.  If it is not found then the source is new. 
[[BR]][[BR]]
''Stephanie:'' Both Olof and I are somewhat unsure whether it is really necessary to differentiate between new and existing sources when sending POST, PUT, DELETE and GET requests from within the client, especially if the backend implementation is going to be changed to simply check whether the given URI already exists in the DB or not.
Could you please rethink whether we actually need to keep this concept in the schema document, DASISH-schema.xsd? This decision also has consequences for how the behavior of the client needs to be tuned (cf. [source:DASISH/t5.6/client/trunk/chrome/markingcollection/content/markingcollection/annotator-service/test/mockjax/mocks POST/GET] mock docs named above).

=== Resolution ===

The schema stays intact.  For the backend-code: the server should check if the source is indeed new, see  https://trac.clarin.eu/ticket/362 for more detail.


==    External_id (Data Base) vs URI (schema) vs UUID-based class (Java code) ==

For the time being I treat {{{extrnal_id}}} and the URI as "the same":  URI is external_id. Both are strings.

In the Java-code there are classes {{{{CachedIdentifier, VersionIdentifier, SourceIdentifier, AnnotationIdentifier, NotebookIdentifier, UserIdentifier}}}
encapsulating  UUI.  Any such class  has a string field "identifier" (corresponding to external_id) plus hash, plus internal constants for hash.

=== Resolution ===

The schema stays intact. For the back-end code: the URI must be of the form  "http(s):/<dasish-server>/externalID.  See https://trac.clarin.eu/ticket/363 for more detail.

Moreover, all {{{{CachedIdentifier, VersionIdentifier, SourceIdentifier, AnnotationIdentifier, NotebookIdentifier, UserIdentifier}}} must be removed. We will be using just  UUID type
for all  identifiers of any sort of resource. E.g.  UserIdentifier userIdentifier = New UserIdentifier("00000000-0000-0000-0000-000000000003") will be replaced with
UUID userIdentifer = UUID.fromString("00000000-0000-0000-0000-000000000003"). It is the ticket  https://trac.clarin.eu/ticket/371

== Body: must be some serialization/deserialization mechanism ==

-- "body" in the DB is just a text

-- "body" in JAXB-generated  class is a list of objects

For now, I use simple "serialize" and "deserialize" Helpers' procedures  which should be replaced by some proper marshalling-demarshalling. For simple serialization I treat the first element of the list
of objects above  as a text  whcich corresponds to the DB column "body_xml".

=== Resolution ===

The schema  stays intact. For the back-end code: still needs to be discussed "how we are going to parse annotation bodies". See https://trac.clarin.eu/ticket/364 for more detail.
[[BR]][[BR]]
''Stephanie:'' It might be preferable to abandon the helper methods in favor of using JAXB's marshal() and unmarshal() methods together with a(n) {{{Marshaller}}} / {{{Unmarshaller}}} object. Can JAXB's {{{ObjectFactory}}} methods be of any use as an alternative way to access XML data? Furthermore, you might want to have a look at Javax.xml.bind.JAXBIntrospector.getValue(Object jaxbElement). Please see: http://www.tutorialspoint.com/java/xml/; http://www.oracle.com/technetwork/articles/javase/index-140168.html; http://docs.oracle.com/javase/tutorial/jaxb/intro/index.html; http://jaxb.java.net/tutorial/ - in case you haven't come across these web resources before.


== Source ==

Misprint in timeStamp: timeSatmp.

=== Resolution ===

The schema must be fixed.  See https://trac.clarin.eu/ticket/365

== Cached Representation Info ==

Missing in the schema: the attribute/elememt "where_is_the_file" which actually points to the location 
where the file can be download. It is necessary to fulfill  

GET api/sources/<sid>/cached/<cid>/content

=== Resolution ===

The schema stays intact. For the back-end (and the database!):  the cached representation for now should be 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


== Version ==

MISSING in the schema:  attribute URI (corresponding to the external_id in the DB) is absent. Therefore it does not appear 
in the  JAXB-generated class "Version" and the java class has one attribute less than the DB table "version"

{{{
CREATE TABLE version (
    version_id SERIAL UNIQUE NOT NULL,
    external_id UUID UNIQUE NOT NULL,
    version text,
);
}}}

For now I'm using attrribute "version:String" now to keep "external_id/URI" in the java 
class "Version". 

=== Resolution ===

Fix the schema: URI must be added to the version-type. The ticket: https://trac.clarin.eu/ticket/367

==  LISTS of Resources, like "PermissionS" and "CachedRepresentationS", 
and version-siblingS connected to a particular source
cannot be standalone tables in the relational DB ==

According to the schema: a list of Cached representations is declared as a standalone resource 
of type "CachedRepresentations". Every version referres to its own list of cached representations. 
Every such list has it own ID.

According to the Rel. database: it looks a bit strange to have such lists. Instead, i have made 
a common joint table (verson_id, cached_representation_id). A pair (a, b) is listed in this table iff 
the version with  the internal id "a" has cahced representation with intrenal id "b".

=== Resolution ===

Fix the schema: all lists of resources are artifacts, they do not have URI's. Ticket: https://trac.clarin.eu/ticket/368