wiki:DASISH/XSD and XML

Version 21 (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?source="​http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia"&access=read
    3. Responding GET api/annotations/AID02 (example usage for resolvable target sources)
    4. Responding GET api/annotations/AID01 (example usage for unresolvable target sources)
    5. Responding GET api/annotations/AID01/sources (example usage for unresolvable target sources)
      1. Remarks by Menzo
      2. Olha's comment:
    6. Responding GET api/sources/SID05/cached/CID005A/metadata (example usage for unresolvable target sources)
    7. Request body for POST api/annotations

XSD Schema

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


    <!-- Body -->

    <xs:complexType name="Body">
        <xs:sequence>
            <xs:any processContents="lax" maxOccurs="unbounded"/>
        </xs:sequence>
        <xs:anyAttribute processContents="lax"/>
    </xs:complexType>

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

    <xs:complexType name="CachedRepresentation">
        <xs:attribute ref="xml:id" use="required"/>
        <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="listCachedRepresentations">
        <xs:sequence>
            <xs:element name="cachedRepresentation" type="CachedRepresentation"
                maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <!--////////////////////////////-->
    <!-- Versions -->
    <xs:complexType name="sourceREF">
        <xs:attribute name="ref" type="xs:NCName" use="required"/>
    </xs:complexType>

    <xs:complexType name="listVersionREFs">
        <xs:sequence>
            <xs:element name="version" type="sourceREF" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

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

     <xs:simpleType name="Action">
         <xs:restriction base="xs:string">
             <xs:enumeration value="CREATE_CACHED_REPRESENTATION"/>
         </xs:restriction>
     </xs:simpleType>

    <xs:complexType name="Source">
        <xs:sequence>
            <xs:element name="URI" type="xs:anyURI" minOccurs="1"/>
            <xs:element name="version" type="xs:string" minOccurs="1"/>
            <xs:element name="versions" type="listVersionREFs" minOccurs="1"/>
            <xs:element name="cachedRepresentations" type="listCachedRepresentations" minOccurs="1"
            />
            <xs:element name="action" type="Action" minOccurs="0"/>
        </xs:sequence>
        <xs:attribute ref="xml:id" use="required"/>
        <xs:attribute name="lastModified" type="xs:dateTime" use="required"/>
    </xs:complexType>


    <xs:complexType name="SourceInfoForAnnotation">
        <xs:sequence>
            <xs:element name="URI" type="xs:anyURI" minOccurs="1"/>
            <xs:element name="version" type="xs:string" minOccurs="1"/>
            <xs:element name="action" type="Action" minOccurs="0"/>
        </xs:sequence>
        <xs:attribute ref="xml:id" use="required"/>
    </xs:complexType>




    <!--////////////////////////////-->
    <!-- Human Agents (Users) -->

    <xs:complexType name="userREF">
        <xs:annotation>
            <xs:documentation xml:lang="nl">De referentiele integriteit moet door de backend
                afgedwongen worden.</xs:documentation>
            <xs:documentation xml:lang="en">The integrity of the references must be forced via the
                backend</xs:documentation>
        </xs:annotation>
        <xs:attribute name="ref" type="xs:NCName" use="required"/>
    </xs:complexType>


    <!--////////////////////////////-->
    <!-- Annotation -->

    <xs:complexType name="listReaderREFs">
        <xs:sequence>
            <xs:element name="reader" type="userREF" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="listWriterREFs">
        <xs:sequence>
            <xs:element name="writer" type="userREF" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="listSourceInfoForAnnotation">
        <xs:sequence>
            <xs:element name="targetSource" type="SourceInfoForAnnotation" minOccurs="1"
                maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="notebookInfo">
        <xs:sequence>
            <xs:element name="title" type="xs:string" minOccurs="1"/>
        </xs:sequence>
        <xs:attribute name="ref" type="xs:NCName" use="required"/>
    </xs:complexType>

    <xs:complexType name="listNotebookInfos">
        <xs:sequence>
            <xs:element name="notebook" type="notebookInfo" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="Annotation">
        <xs:sequence>
            <xs:element name="owner" type="userREF" 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="listSourceInfoForAnnotation" minOccurs="1"/>
            <xs:element name="readers" type="listReaderREFs" minOccurs="1"/>
            <xs:element name="writers" type="listWriterREFs" minOccurs="1"/>
            <!-- <xs:element name="notebooks" type="listNotebookInfos" minOccurs="1"/> -->
        </xs:sequence>
        <xs:attribute ref="xml:id" use="required"/>
        <xs:attribute name="URI" type="xs:anyURI"/>
        <xs:attribute name="timeStamp" type="xs:dateTime" use="required"/>
    </xs:complexType>





    <!--////////////////////////////-->
    <!-- Notebook -->

    <xs:complexType name="listAnnotations">
        <xs:sequence>
            <xs:element name="annotation" type="Annotation" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="Notebook">
        <xs:sequence>
            <xs:element name="title" type="xs:string"/>
            <xs:element name="annotations" type="listAnnotations"/>
            <xs:element name="readers" type="listReaderREFs"/>
            <xs:element name="writers" type="listWriterREFs"/>
        </xs:sequence>
        <xs:attribute ref="xml:id" use="required"/>
        <xs:attribute name="URI" type="xs:anyURI" use="required"/>
        <xs:attribute name="timeStamp" type="xs:dateTime" use="required"/>
    </xs:complexType>

    <xs:complexType name="NotebookInfo">
        <xs:sequence>
            <xs:element name="title" type="xs:string"/>
        </xs:sequence>
        <xs:attribute name="ref" type="xs:NCName" use="required"/>
    </xs:complexType>

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



    <!--/////////////////////////////////////-->
    <!-- GET api/user respond -->


    <xs:complexType name="UserInfoExtended">
        <xs:sequence>
            <xs:element name="uid" type="xs:NCName"/>
            <xs:element name="notebooksToRead" type="listNotebooks"/>
            <xs:element name="notebooksToWrite" type="listNotebooks"/>
        </xs:sequence>
    </xs:complexType>


    <xs:element name="userInfoExtended" type="UserInfoExtended"/>


    <!--/////////////////////////////////////-->
    <!-- GET api/user/uid respond -->


    <xs:complexType name="UserInfo">
        <xs:sequence>
            <xs:element name="uid" type="xs:NCName"/>
        </xs:sequence>
        <xs:attribute name="currentUser" type="xs:boolean"/>
    </xs:complexType>


    <xs:element name="userInfo" type="UserInfo"/>


    <!--/////////////////////////////////////-->
    <!-- GET api/annotations?source="http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia"&access=read  respond -->

    <xs:complexType name="SourceRef">
        <xs:attribute name="ref" type="xs:NCName"/>
    </xs:complexType>


    <xs:complexType name="listSourceRef">
        <xs:sequence>
            <xs:element name="targetSource" type="SourceRef" minOccurs="1"
                maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:complexType name="OwnerRef">
        <xs:attribute name="ref" type="xs:NCName"/>
    </xs:complexType>

    <xs:complexType name="AnnotationInfo">
        <xs:sequence>
            <xs:element name="owner" type="OwnerRef" minOccurs="1"/>
            <xs:element name="headline" type="xs:string" minOccurs="1"/>
            <xs:element name="targetSources" type="listSourceRef" minOccurs="1"/>
            <!-- <xs:element name="notebooks" type="listNotebookInfos" minOccurs="1"/> -->
        </xs:sequence>
        <xs:attribute name="id" type="xs:NCName" use="required"/>
    </xs:complexType>

    <xs:complexType name="listAnnotationInfo">
        <xs:sequence>
            <xs:element name="annotation" type="AnnotationInfo" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>



    <xs:complexType name="AnnotationsOfSource">
        <xs:sequence>
            <xs:element name="annotations" type="listAnnotationInfo"/>
        </xs:sequence>
    </xs:complexType>


    <xs:element name="annotationsOfSource" type="AnnotationsOfSource"/>

    <!--/////////////////////////////////////-->
    <!-- GET api/annotations/AID01  respond -->
    <!-- GET api/annotations/AID02  respond -->

    <xs:element name="annotation" type="Annotation"/>


    <!--/////////////////////////////////////-->
    <!--  GET api/annotations/AID01/sources   respond (non-resolvable, obsolete target sources)-->

    <xs:complexType name="listSources">
        <xs:sequence>
            <xs:element name="targetSource" type="Source" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>

    <xs:element name="sources" type="listSources"/>


    <!--/////////////////////////////////////-->
    <!--  GET api/sources/SID05/cached    respond -->

    <xs:element name="cashedRepresentations" type="listCachedRepresentations"/>

    <!--/////////////////////////////////////-->
    <!--  GET api/sources/SID05/cached/CID005A    respond -->

    <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"?>
<userInfo
    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"
    currentUser="true">
    <uid>ID01</uid>
</userInfo>

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

<?xml version="1.0" encoding="UTF-8"?>
<annotationsOfSource 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"> 
    <annotations>
        <annotation id="AID03">
            <owner ref="ID02"/>
            <headline>My client is not in a hurry</headline>
            <targetSources>
                <targetSource ref="SID015"/>
            </targetSources>
        </annotation>
        <annotation id="AID02">
            <owner ref="ID01"/>
            <headline>Nativity Facade</headline>
            <targetSources>
                <targetSource ref="SID015"/>
                <targetSource ref="SID017"/>
            </targetSources>
        </annotation>
        <annotation id="AID01">
            <owner ref="ID01"/>
            <headline>Nativity Facade (old site)</headline>
            <targetSources>
                <targetSource ref="SID005"/>
                <targetSource ref="SID007"/>
            </targetSources>
        </annotation>
    </annotations>
</annotationsOfSource>

Responding GET api/annotations/AID02 (example usage for 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" 
 xml:id="AID02" 
 URI="http://www.dasish.eu/DB/AID002" 
 timeStamp="2013-05-04T18:13:51.0Z">
    <owner ref="ID01"/>
    <headline>Nativity Facade</headline>
    <body type="relation">
        <relation>different</relation>
        <this ref="SID015"/>
        <that ref="SID017"/>   
    </body>
    <targetSources>
        <targetSource xml:id="SID015">
            <URI>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Nativity_Fa.C3.A7ade</URI>
            <version>5.0</version>
        </targetSource>
        <targetSource xml:id="SID017">
            <URI>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Passion_Fa.C3.A7ade</URI>
            <version>5.0</version>
        </targetSource>
    </targetSources>
    <readers>
        <reader ref="ID01"/>
        <reader ref="ID03"/>
        <reader ref="ID04"/>
    </readers>
    <writers>
        <writer ref="ID01"/>
        <writer ref="ID03"/>
    </writers>
</annotation>

Responding GET api/annotations/AID01 (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. 

<?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" 
    xml:id="AID01" 
    URI="http://www.dasish.eu/DB/AID002" 
    timeStamp="2010-05-04T18:13:51.0Z">
    <owner ref="ID01"/>
    <headline>Nativity Facade (old site)</headline>
    <body type="relation">
        <relation>different</relation>
        <this ref="SID005"/>
        <that ref="SID007"/>   
    </body>
    <targetSources>
        <targetSource xml:id="SID005">
            <URI>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Nativity_Fa.C3.A7ade</URI>
            <version>1.0</version>
        </targetSource>
        <targetSource xml:id="SID007">
            <URI>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Passion_Fa.C3.A7ade</URI>
            <version>1.0</version>
        </targetSource>
    </targetSources>
    <readers>
        <reader ref="ID01"/>
        <reader ref="ID03"/>
        <reader ref="ID04"/>
    </readers>
    <writers>
        <writer ref="ID01"/>
        <writer ref="ID03"/>
    </writers>
</annotation>

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

<?xml version="1.0" encoding="UTF-8"?>
<sources 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">
    <targetSource xml:id="SID005" lastModified="2006-05-04T18:13:51.0Z">
        <URI>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Nativity_Fa.C3.A7ade</URI>
        <version>1.0</version>
        <versions>
            <version ref="SID005"/>
            <version ref="SID015"/>
        </versions>
        <cachedRepresentations>
            <cachedRepresentation xml:id="CID005" URI="http://www.dasish.eu/DB/CID005" mimeType="text/html" tool="tool1" type="text"/>
            <cachedRepresentation xml:id="CID005A" URI="http://www.dasish.eu/DB/CID005A" mimeType="image/png" tool="tool2" type="screenshot"/>
            <cachedRepresentation xml:id="CID015" URI="http://www.dasish.eu/DB/CID015" mimeType="mimeType3" tool="tool3" type="type3"/>
        </cachedRepresentations>
    </targetSource>
    <targetSource xml:id="SID007" lastModified="2006-05-04T18:13:51.0Z">
        <URI>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Passion_Fa.C3.A7ade</URI>
        <version>1.0</version>
        <versions>
            <version ref="SID007"/>
            <version ref="SID017"/>
        </versions>
        <cachedRepresentations>
            <cachedRepresentation xml:id="CID007" URI="http://www.dasish.eu/DB/CID007" mimeType="mimeType5" tool="tool5" type="type5"/>
            <cachedRepresentation xml:id="CID017" URI="http://www.dasish.eu/DB/CID017" mimeType="mimeType7" tool="tool7" type="type7"/>
        </cachedRepresentations>
    </targetSource>
</sources>

Remarks by Menzo

The versions list contains the version you looking at as well, e.g., the version list of SID005 consists of SID005 and SID015. Is this so because the list is ordered and we can determine the position of the version under consideration?

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/SID05/cached/CID005A/metadata (example usage for unresolvable target sources)

<?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" 
 xml:id="CID005A" URI="http://www.dasish.eu/DB/CID005A" mimeType="image/png" tool="tool2" type="screenshot"/>

Request body for POST api/annotations

<?xml version="1.0" encoding="UTF-8"?>
<newAnnotation 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" 
    xml:id="tempAID06" 
    timeStamp="2013-05-04T18:13:51.0Z">
    <owner ref="ID02"/>
    <headline>Organ</headline>
    <body>
        <note>installed in 2010</note>
    </body>
    <targetSources>
        <targetSource xml:id="SID018">
            <URI>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Organ</URI>
            <version>5.0</version>
        </targetSource>
    </targetSources>
    <readers>
        <reader ref="ID02"/>
    </readers>
    <writers>
        <writer ref="ID02"/>
    </writers>
</newAnnotation>

The version of the POST with an unknown target source, signalling the client to provide a cached representation for it: 

<?xml version="1.0" encoding="UTF-8"?>
<newAnnotation 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" 
    xml:id="tempAID06" 
    timeStamp="2013-05-04T18:13:51.0Z">
    <owner ref="ID02"/>
    <headline>Organ</headline>
    <body>
        <note>installed in 2010</note>
    </body>
    <targetSources>
        <targetSource xml:id="SID018">
            <URI>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Organ</URI>
            <version>5.0</version>
            <action>CREATE_CACHED_REPRESENTATION</action>
        </targetSource>
    </targetSources>
    <readers>
        <reader ref="ID02"/>
    </readers>
    <writers>
        <writer ref="ID02"/>
    </writers>
</newAnnotation>