wiki:DASISH/XSD and XML

Version 139 (modified by olhsha, 10 years ago) (diff)

--

Contents

  1. XSD Schema
    1. Preamble
      1. Handling new (not yet in the DB) sources
  2. Scenario XML's validated vs the given schema
      1. GET api/user/00000000-0000-0000-0000-000000000112
      2. GET api/users/00000000-0000-0000-0000-0000000000112/current
      3. GET api/users/info?email=​twagoo@mpi.nl
    2. Retrieving annotations
      1. Responding GET api/annotations?link=Sagrada
      2. Responding GET api/annotations/00000000-0000-0000-0000-000000000021
      3. GET api/annotations/00000000-0000-0000-0000-000000000021/targets
      4. GET api/annotations/00000000-0000-0000-0000-000000000021/permissions
      5. GET api/targets/00000000-0000-0000-0000-000000000032
      6. GET api/targets/00000000-0000-0000-0000-000000000032/versions
      7. GET api/cached/00000000-0000-0000-0000-000000000051/metadata
      8. Responding GET api/annotations/00000000-0000-0000-0000-00000000002c (example usage for unresolvable targets 1)
      9. 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)
      10. Responding GET api/targets/00000000-0000-0000-0000-00000000003c/versions (unresolvable target sources 3)
      11. Responding GET api/cached/00000000-0000-0000-0000-00000000005c/metadata (unresolvable target sources 4)
    3. Making a new annotation
      1. Request body for POST api/annotations
      2. Response body (envelope) for POST api/annotations
    4. Editing annotation body
      1. Request: an updated body
      2. Enveloped respond: new (updated) annotation and a list of actions
    5. Managing permission lists of users
      1. GET api/annotations/AIDzyy/permissions
      2. GET api/users/info?email="​alecor@mpi.nl"
      3. PUT api/annotations/AIDzyy/permissions
      4. PUT api/annotations/AIDzyy/permissions/UIDagc
    6. Managing Notebooks
      1. GET api/notebooks
      2. GET api/notebooks/NIDxyxy
      3. GET api/notebooks/NIDxyxy/annotations/
  3. Issues with the schema
    1. Possible namespace pollution: Ticket 348 to be discussed with Peter
      1. Resolution
    2. New-Or-Existing-Source-Info JAXB-generated class
      1. Resolution
    3. External_id (Data Base) vs URI (schema) vs UUID-based class (Java code)
      1. Resolution
    4. Body: must be some serialization/deserialization mechanism
      1. Resolution 18/09
    5. Source
      1. Resolution
    6. Cached Representation Info
      1. Resolution
    7. Version
      1. Resolution
    8. LISTS of Resources, like "PermissionS" and "CachedRepresentationS",
      1. Resolution

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 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 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 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

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

Request: an updated body

<?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 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 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 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 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 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 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 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."

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>  
   <annotation>
      <!-- elements of annotation -->
   </annotation>
</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?

Olha: we agree. See also the updated comments for the ticket 348.

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 (DASISH/t5.6/client/trunk/chrome/markingcollection/content/markingcollection/annotator-service/test/mockjax/mocks).

Olha: sure. We have not made any changes yet (before getting you opinion). Unfortunately, I will be away 27/08 - 14/09 due to urgent family circumstances. I hope that we can wait till I'm back.

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.

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. POST/GET mock docs named above).

Olha: we agree with you. See resolution below.

Resolution

The schema must be simplified. It is up to server to decide if a source is new or old. See ticket 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.

Stephanie: Apropos this subject, could you please clarify whether you intend to use "external-id (Ticket #362: externalID, see even discussion topic above)" for the database only? You use the wording "For the time being", which made us wonder whether the statement "URI is external_id" will be true even in the longer perspective, or, if not, where / how the externalID is going to be put in from the schema side, an thus within the context of the resulting, serialized xml documents? Furthermore, why is the nomenclature "external_id" used? Won't the value of URI always be an internal id, like e.g. ​http://dasish.eu/annotations/AID20130808114716, that needs to be created and set via a corresponding backend functionality?

Olha: The term "external_id" comes from the Data Base and is used for communication with the client. It is a string which satisfies UUID-format, e.g. "00000000-0000-0000-0000-000000000003". The URI in the xsd is of the form like you mentioned above e.g. ​http://dasish.eu/annotations/00000000-0000-0000-0000-000000000003. An external Id is generated by the backend whenever a resource is recognized as new in the corresponding "add"-method. It is sent to the client as a respond to the "Add" request. Just to be sure, we definitely intend to keep it this way although there should be no need for the client to be aware of the conceptual distinction between 'external id' and the URI, in other words the latter can be considered the public identifier for the client.

"Internal_id" in the database is not visible to a client. It is "next-in-the-table" number generated by the database whenever the corresponding resource is added. It is a primary key of the resource. It is used for joint tables (e.g. when you connect an annotation to a source) and for quick search by key, since it is just a number, not a string.

Also, the ticket 371 mentioned below is fixed.

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 18/09

The schema is updated (contrary to what was stated before 18/09). See https://trac.clarin.eu/ticket/364 for more detail, the comment on it.

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.

"Olha": the helpers "serialize/deserialize" are removed. We have to discuss at Goteborg our present solution 

<xs:complexType name="AnnotationBody">
<xs:simpleContent>
<xs:extension base="xs:string"> 
<xs:attribute name="mimeType" type="xs:string"/> 
</xs:extension>
</xs:simpleContent>
</xs:complexType>

The database is changed so that the column "body_xml" in the table "annotation" is replaced with two ones: "body_text" and "body_mimetype". The corresponding adjustments in the code and in the unit tests are done. So far, no special serialization menachisme is used.

The question: what does the client need to do to be able to represent the annotation body properly?

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

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 ​MIME HTML or alternatively something like ​the Mozilla Archive Format. Cross-browser support could be a bit of an issue there but the situation does not look too bad.

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

Stephanie: When removing the URI attribute for lists of resources, please make sure that the integrity of the references is still guaranteed.

Olha: lists are not stored in the DB but generated by the backend on the fly when they are needed. For instance, once the client wants to GET an annotation (whose schema contains the list of source-infos), the backend looks up the joint table "annotations_resources" and the table "source" and generates a list of resources for the annotation.