Version 49 (modified by 11 years ago) (diff) | ,
---|
Contents
- XSD Schema
-
Scenario XML's validated vs the given schema
- Responding GET api/user/uid
- Responding GET api/annotations?link="http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia"&access=read
- Responding GET api/annotations/AIDzzz (example of resolvable target sources)
- Responding GET api/annotations/AIDzyy (example usage for unresolvable target sources)
- Responding GET api/sources/SIDbbb (example usage for unresolvable target sources)
- Responding GET api/sources/SIDbbb/cached/CIDtttt/metadata (example usage for unresolvable target sources)
- Request body for POST api/annotations
XSD Schema
Preamble
The xsd schema is designed according to the following paradigm:
-- There are 6 xsd-types corresponding to five sorts of resources in DASISH: CachedRepresentation
, Source
, User
, Annotation
, Notebook
., Lists of Permissions
.
-- 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 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: SourceInfo
, UserInfo
, AnnotationInfo
, NotebookInfo
. They contain reference to the corresponding resource plus the most important information about the resource. We have not introduced the info-type for Cached representations because there is no actual need for it and the type itself not that big. There is no info version of a list of permission either.
-- 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 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" />
.
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-xsd.
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.
The reference to the second, "weakly-typed", version of the XSD-schema is left for the reference, however it 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"/>
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/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)
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 the cached representations of the obsolete web-page.
The serialization compliant with the strongly-typed schema:
<?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/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>29.01.2010</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>29.01.2010</version> </source> </target> </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>
The serialization compliant with the weakly-typed schema:
<?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/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 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="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 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" 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:
TODO: Action element is removed, instead note that we have to think about a solution, probably using an envelope with annotation result and set of action requests
The serialization compliant with the strongly-typed schema:
<?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="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> <readers> <reader ref="http://dasish.eu/users/UIde1fe1f"/> </readers> <writers> <writer ref="http://dasish.eu/users/UIde1fe1f"/> </writers> </annotation>
The serialization compliant with the weakly-typed schema:
<?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="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> <targetSource ref="http://dasish.eu/sources/SIDaaabbb"> <link>http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#History</link> <version>20.04.2012</version> </targetSource> <targetSource 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> </targetSource> </targetSources> <readers> <reader ref="http://dasish.eu/users/UIde1fe1f"/> </readers> <writers> <writer ref="http://dasish.eu/users/UIde1fe1f"/> </writers> </annotation>
Request body for POST api/annotations: another example
The serialization of the POST body for another example (UGOT), compliant with the strongly typed schema.
<?xml version="1.0" encoding="UTF-8"?> <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> <readers> <reader ref="http://dasish.eu/users/user123"/> </readers> <writers> <writer ref="http://dasish.eu/users/user123"/> </writers> </annotation>
The serialization of the POST body for another example (UGOT), compliant with the weakly typed schema.
<?xml version="1.0" encoding="UTF-8"?> <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> <targetSource 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> </targetSource> </targetSources> <readers> <reader ref="http://dasish.eu/users/user123"/> </readers> <writers> <writer ref="http://dasish.eu/users/user123"/> </writers> </annotation>
TODO: POST response