wiki:DASISH/XSD and XML

Version 96 (modified by sroth, 11 years ago) (diff)

Added missing ".eu" in URI attribute.

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. Responding GET api/user/uid
    2. Retrieving annotations
      1. Responding GET api/annotations?link="​http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia"&access=read
      2. Responding GET api/annotations/AIDzzz (example of resolvable target sources)
      3. Responding GET api/annotations/AIDzyy (example usage for unresolvable target sources 1)
      4. Responding GET api/sources/SIDbbb (unresolvable target sources 2)
      5. Responding GET api/sources/SIDbbb/versions (unresolvable target sources 3)
      6. Responding GET api/sources/SIDbbb/cached/CIDtttt/metadata (unresolvable target sources 4)
    3. Making a new annotation
      1. Request body for POST api/annotations
      2. Request body for POST api/annotations: another example
      3. 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/

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

Responding GET api/user/uid

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