wiki:DASISH/XSD and XML

Version 26 (modified by olhsha, 11 years ago) (diff)

--

Contents

  1. XSD Schema
  2. Scenario XML's validated vs the given schema
    1. Responding GET api/user/uid
    2. Responding GET api/annotations?link="​http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia"&access=read
    3. Responding GET api/annotations/AIDzzz (example of resolvable target sources)

XSD Schema

The xsd schema is designed according to the following paradigm:

-- There are five xsd-types corresponding five sorts of resources in DASISH: CachedRepresentation, Source, User, Annotation, Notebook.

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

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

-- There five corresponding resource-infor types: CachedRepresentationInfo, SourceInfo, UserInfo, AnnotationInfo, NotebookInfo. They contain reference to the corresponding resource plus the most important information about the resource.

-- There five corresponding list-of-resource-infor types: CachedRepresentationInfos, 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 have announce elements-references and avoid mixing-them-up with elements-resources, without adding REF to the name. For instance <owner ref="http:/dasish.eu/users/UIDefef" />. 

<?xml version="1.1" encoding="UTF-8"?>
<xs:schema targetNamespace="http://www.dasish.eu/ns/addit"
    xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="http://www.dasish.eu/ns/addit"
    elementFormDefault="qualified">
    <xs:import namespace="http://www.w3.org/XML/1998/namespace"
        schemaLocation="http://www.w3.org/2005/08/xml.xsd"/>


    <!--////////////////////////////////////////////////////-->
    <!-- Annotation-body types according to the UML diagram -->
    
    <!-- DASISH resources (cached representations, sources, users, annotations, notebooks) have an obligatory URIdasih element-->
    <!-- The integrity of the references must be forced via the backend -->
    
        
    
    <xs:complexType name="ResourceREF">
        <xs:attribute name="ref" type="xs:anyURI"></xs:attribute>
    </xs:complexType>
    <!-- for a new annotation the reference to the source is absent, that's why this attribute is not obligatory-->
    

    
    <!--////////////////////////-->
    <!--Cached representations -->

    <xs:complexType name="CachedRepresentation">
        <xs:attribute name="URI" type="xs:anyURI" use="required"/>
        <xs:attribute name="mimeType" type="xs:string" use="required"/>
        <xs:attribute name="tool" type="xs:string" use="required"/>
        <xs:attribute name="type" type="xs:string" use="required"/>
    </xs:complexType>
   

    <xs:complexType name="CachedRepresentations">
        <xs:sequence>
            <xs:element name="cachedRepresentation" type="ResourceREF"
                maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <!--////////////////////////////-->
    <!-- Sources (== Targets in OA) -->


    <xs:complexType name="Source">
        <xs:sequence>
            <xs:element name="cachedRepresentations" type="CachedRepresentations" minOccurs="1"/>
            <xs:element name="action" type="Action" minOccurs="0"/>
            <xs:element name="versions-siblings" type="Versions" minOccurs="1"/>
        </xs:sequence>
        <xs:attribute name="URI" type="xs:anyURI" use="required"/>
        <xs:attribute name="timeSatmp" type="xs:dateTime" use="required"/>
        <xs:attribute name="link" type="xs:anyURI" use="required"/>
        <xs:attribute name="version" type="xs:string" use="required"/>
    </xs:complexType>

 
    <xs:complexType name="Sources">
        <xs:sequence>
            <xs:element name="targetSource" type="ResourceREF" minOccurs="1"
                maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>
    
    
    <xs:complexType name="SourceInfo">
        <xs:complexContent>
            <xs:extension base="ResourceREF">
                <xs:sequence>
                    <xs:element name="action" type="Action" minOccurs="0" maxOccurs="1"/>
                    <xs:element name="link" type="xs:anyURI" minOccurs="1" maxOccurs="1"/>
                    <xs:element name="version" type="xs:string" minOccurs="1" maxOccurs="1"/>
                </xs:sequence>  
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
    
    <xs:complexType name="SourceInfos">
        <xs:sequence>
            <xs:element name="targetSource" type="SourceInfo" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>
    

    <xs:simpleType name="Action">
        <xs:restriction base="xs:string">
            <xs:enumeration value="CREATE_CACHED_REPRESENTATION"/>
        </xs:restriction>
    </xs:simpleType>
   
    
    <xs:complexType name="Versions">
        <xs:sequence>
            <xs:element name="version" type="ResourceREF" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>
 
    <!--////////////////////////////-->
    <!-- Human Agents (Users) -->

    <xs:complexType name="User">
        <xs:sequence>
            <xs:element name="notebooksToRead" type="NotebookInfos"/>
            <xs:element name="notebooksToWrite" type="NotebookInfos"/>
            <xs:element name="additionalInfo">
                <xs:complexType>
                    <xs:sequence>
                        <xs:any processContents="lax" maxOccurs="unbounded"/>
                    </xs:sequence>
                    <xs:anyAttribute processContents="lax"/>
                </xs:complexType>
            </xs:element>
        </xs:sequence>
        <xs:attribute name="URI" type="xs:anyURI" use="required"/>
        <xs:attribute name="name" type="xs:string" use="required"/>
    </xs:complexType>
    
    <xs:complexType name="Users">
        <xs:sequence>
            <xs:element name="user" type="ResourceREF" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>


    <xs:complexType name="UserInfo">
        <xs:complexContent>
            <xs:extension base="ResourceREF">
                <xs:sequence>
                    <xs:element name="notebooksToRead" type="NotebookInfos"/>
                    <xs:element name="notebooksToWrite" type="NotebookInfos"/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
    
    
    <xs:complexType name="UserInfos">
        <xs:sequence>
            <xs:element name="user" type="UserInfo" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="CurrentUserInfo">
        <xs:complexContent>
            <xs:extension base="ResourceREF">
                <xs:attribute name="currentUser" type="xs:boolean" use="required"/>   
            </xs:extension>
        </xs:complexContent>
    </xs:complexType>
    


    <!--////////////////////////////-->
    <!-- Annotation -->
    
    
    <xs:complexType name="Annotation">
        <xs:sequence>
            <xs:element name="owner" type="ResourceREF" minOccurs="1"/>
            <xs:element name="headline" type="xs:string" minOccurs="1"/>
            <!-- schematron checks the length <== 100 -->
            <xs:element name="body" type="Body" minOccurs="1"/>
            <xs:element name="targetSources" type="SourceInfos" minOccurs="1"/>
            <xs:element name="readers" type="Readers" minOccurs="1"/>
            <xs:element name="writers" type="Writers" minOccurs="1"/>
        </xs:sequence>
        <xs:attribute name="URI" type="xs:anyURI" use="required"/>
        <xs:attribute name="timeStamp" type="xs:dateTime" use="required"/>
    </xs:complexType>

  
    <xs:complexType name="Annotations">
        <xs:sequence>
            <xs:element name="annotation" type="ResourceREF" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType> 
    
    <xs:complexType name="AnnotationInfo">
        <xs:complexContent>
            <xs:extension base="ResourceREF"> 
                <xs:sequence>
                    <xs:element name="owner" type="ResourceREF" minOccurs="1" maxOccurs="1"/>
                    <xs:element name="headline" type="xs:string" minOccurs="1" maxOccurs="1"/>
                    <xs:element name="targetSources" type="Sources" minOccurs="1" maxOccurs="1"/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent> 
    </xs:complexType>
    
    <xs:complexType name="AnnotationInfos">
        <xs:sequence>
            <xs:element name="annotation" type="AnnotationInfo" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>
    
    <xs:complexType name="Body">
        <xs:sequence>
            <xs:any processContents="lax" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:anyAttribute processContents="lax"/>
    </xs:complexType>
    
    <xs:complexType name="Readers">
        <xs:sequence>
            <xs:element name="reader" type="ResourceREF" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>
    
    <xs:complexType name="Writers">
        <xs:sequence>
            <xs:element name="writer" type="ResourceREF" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>
    
   
    <!--////////////////////////////-->
    <!-- Notebook -->

    <xs:complexType name="Notebook">
        <xs:sequence>
            <xs:element name="title" type="xs:string"/>
            <xs:element name="annotations" type="Annotations"/>
            <xs:element name="readers" type="Readers"/>
            <xs:element name="writers" type="Writers"/>
        </xs:sequence>
        <xs:attribute name="URI" type="xs:anyURI"/>
        <xs:attribute name="timeStamp" type="xs:dateTime" use="required"/>
    </xs:complexType>
    
 
    <xs:complexType name="Notebooks">
        <xs:sequence>
            <xs:element name="notebook" type="ResourceREF" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="NotebookInfo">
        <xs:complexContent>
            <xs:extension base="ResourceREF"> 
                <xs:sequence>
                    <xs:element name="notebook" type="ResourceREF"/>
                    <xs:element name="title" type="xs:string"/>
                </xs:sequence>
            </xs:extension>
        </xs:complexContent> 
    </xs:complexType>

    <xs:complexType name="NotebookInfos">
        <xs:sequence>
            <xs:element name="notebook" type="NotebookInfo" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>



    <!--/////////////////////////////////////-->
    <!-- GET api/user/uid respond -->
    <xs:element name="currentUserInfo" type="CurrentUserInfo"/>
    
    <!--/////////////////////////////////////-->
    <!-- GET api/annotations?source="http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia"&access=read  respond -->
    <xs:element name="annotationsOfLink" type="AnnotationInfos"></xs:element>
   

    <!--/////////////////////////////////////-->
    <!-- GET api/annotations/AIDxyz  respond -->
    <xs:element name="annotation" type="Annotation"/>


    <!--/////////////////////////////////////-->
    <!--  GET api/annotations/AID0xyz/sources   respond (non-resolvable)-->
    <xs:element name="sources" type="SourceInfos"/>

    <!--/////////////////////////////////////-->
    <!--  GET api/sources/SID0xyz/  respond  -->
    <xs:element name="source" type="Source  "/>
  
       <!--/////////////////////////////////////-->
    <!-- GET api/sources/SID05/cached/CID0efef/metadata (example usage for unresolvable target sources)   -->
    <xs:element name="cashedRepresentation" type="CachedRepresentation"/>

    <!--/////////////////////////////////////-->
    <!-- POST api/annotation, annotation body  -->
    <xs:element name="newAnnotation" type="Annotation"/>

</xs:schema>

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 file:/Users/olhsha/repositories/DASISH/t5.6/docs/XMLandXSD/DASISH-schema.xsd"
 ref="http://dasish.eu/users/UIDefef"
 currentUser="true"/>

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"?>
<annotationsOfLink 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/docs/XMLandXSD/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>
</annotationsOfLink>

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

<?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/docs/XMLandXSD/DASISH-schema.xsd" 
 URI="http://dasish/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>
        <targetSource 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>
        </targetSource>
        <targetSource 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>
        </targetSource>
    </targetSources>
    <readers>
        <reader ref="http://dasish.eu/users/UIde1fe1f"/>
        <reader ref="http://dasish.eu/users/UIdefef"/>
        <reader ref="http://dasish.eu/users/UIdefff"/>
    </readers>
    <writers>
        <writer ref="http://dasish.eu/users/UIde1fe1f"/>
        <writer ref="http://dasish.eu/users/UIdefef"/>
    </writers>
</annotation>}}}



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

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. Later, having the target source references, the client will ask for cached representations of the obsolete web-page.

{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<annotation xmlns="http://www.dasish.eu/ns/addit"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.dasish.eu/ns/addit file:/Users/olhsha/repositories/DASISH/t5.6/docs/XMLandXSD/DASISH-schema.xsd" 
 URI="http://dasish/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>
        <targetSource ref="http://dasish.eu/sources/SIDbbb">
            <link>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Nativity_Fa.C3.A7ade</link>
            <version>29.01.2010</version>
        </targetSource>
        <targetSource ref="http://dasish.eu/sources/SIDrrrr"> 
            <link>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Passion_Fa.C3.A7ade</link>
            <version>29.01.2010</version>
        </targetSource>
    </targetSources>
    <readers>
        <reader ref="http://dasish.eu/users/UIde1fe1f"/>
        <reader ref="http://dasish.eu/users/UIdefef"/>
        <reader ref="http://dasish.eu/users/UIdefff"/>
    </readers>
    <writers>
        <writer ref="http://dasish.eu/users/UIde1fe1f"/>
        <writer ref="http://dasish.eu/users/UIdefef"/>
    </writers>
</annotation>
}}}


== Responding GET api/sources/SIDbbb (example usage for unresolvable target sources) ==

{{{#!xml
<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 file:/Users/olhsha/repositories/DASISH/t5.6/docs/XMLandXSD/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="1.0">
    <cachedRepresentations>
        <cachedRepresentation ref="http://dasish.eu/cached/CIDtttt"/>
        <cachedRepresentation ref="http://dasish.eu/cached/CIDttxvv"/>
    </cachedRepresentations>
    <versions-siblings>
        <version ref="http://dasish.eu/sources/SIDaacc"/>
    </versions-siblings>
</source>}}}

=== Remarks by Menzo ===


For very dynamic and popular target sources the version list might become big, that could be a reason to move it to a separate call. Actually we have already GET api/sources/<sid>/versions, so I would leave them out here.

=== Olha's comment:===
We have agreed earlier that the list of versions would include all the "siblings", include the source itself.Are there alternative ways to get all the siblings of a given source?


== Responding GET api/sources/SIDbbb/cached/CIDtttt/metadata (example usage for unresolvable target sources) == 

{{{#!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 file:/Users/olhsha/repositories/DASISH/t5.6/docs/XMLandXSD/DASISH-schema.xsd" 
 URI="http://dasish.eu/cached/CIDtttt" 
 mimeType="image/png" 
 tool="tool1" 
 type="screenshot"/>}}}

== Request body for POST api/annotations ==



The version of the POST with an unknown target source, signalling the client to provide a cached representation for it:  
{{{#!xml
<?xml version="1.0" encoding="UTF-8"?>
<annotation xmlns="http://www.dasish.eu/ns/addit"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.dasish.eu/ns/addit file:/Users/olhsha/repositories/DASISH/t5.6/docs/XMLandXSD/DASISH-schema.xsd" 
 URI="tempAIDgfgf"
 timeStamp="2013-05-29T18:13:51.0Z">
    <owner ref="http://dasish.eu/users/UIde1fe1f"/>
    <headline>Organ</headline>
    <body>
        <note>installed in 2010</note>
    </body>
    <targetSources>
        <targetSource>
            <action>CREATE_CACHED_REPRESENTATION</action>
            <link>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Organ</link>
            <version>20.04.2013</version>
        </targetSource>
    </targetSources>
    <readers>
        <reader ref="http://dasish.eu/users/UIde1fe1f"/>
    </readers>
    <writers>
        <writer ref="http://dasish.eu/users/UIde1fe1f"/>
    </writers>
</annotation>
}}}
}}}
}}}