{{{ #!html

Contents

}}} [[PageOutline(1-3, , inline)]] {{{ #!comment Obviously, your page starts below this block }}} = 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 {{{}}}. === 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 [source:DASISH/t5.6/docs/XMLandXSD/DASISH-schema.xsd 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. See [source:DASISH/t5.6/docs/XMLandXSD/DASISH-schema-alternative.xsd 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 }}} == 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 My client is not in a hurry Nativity Facade Nativity Facade (old site) }}} == Responding GET api/annotations/AIDzzz (example of resolvable target sources) == {{{#!xml Nativity Facade different http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Nativity_Fa.C3.A7ade 20.04.2013 http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Passion_Fa.C3.A7ade 20.04.2013 }}} == 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 ?xml version="1.0" encoding="UTF-8"?> Nativity Facade (old page) different http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Nativity_Fa.C3.A7ade 29.01.2010 http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#Passion_Fa.C3.A7ade 29.01.2010 }}} == Responding GET api/sources/SIDbbb (unresolvable target sources 2) == {{{#!xml }}} == Responding GET api/versions/VIDaacc (unresolvable target sources 3) == {{{#!xml 29.01.2010 20.04.2013 }}} == Responding GET api/sources/SIDbbb/cached/CIDtttt/metadata (unresolvable target sources 4) == {{{#!xml }}} == Making a new annotation == === Request body for POST api/annotations === {{{#!xml Comapring English and Catalan Wiki History http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#History 20.04.2012 http://ca.wikipedia.org/wiki/Temple_Expiatori_de_la_Sagrada_Fam%C3%ADlia#Hist.C3.B2tia 20.04.2013 }}} === Request body for POST api/annotations: another example === The serialization of the POST body for another example (UGOT): {{{#!xml Douglas Adams - Wikipedia, the free encyclopedia Adams was born 1952-03-11 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))) 2013-04-26T11:23:26.000Z }}} === 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 Comapring English and Catalan Wiki History http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#History 20.04.2012 http://ca.wikipedia.org/wiki/Temple_Expiatori_de_la_Sagrada_Fam%C3%ADlia#Hist.C3.B2tia 20.04.2013 }}} 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 History in English and Catalan }}} === 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 Comapring English and Catalan Wiki History in English and Catalan http://en.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#History 20.04.2012 http://ca.wikipedia.org/wiki/Temple_Expiatori_de_la_Sagrada_Fam%C3%ADlia#Hist.C3.B2tia 20.04.2013 }}} == Managing permission lists of users == === GET api/annotations/AIDzyy/permissions === {{{#!xml }}} === GET api/users/info?email="alecor@mpi.nl" === {{{#!xml }}} === 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 output of "GET api/annotations/AIDzyy/permissions" above. Request body: {{{#!xml }}} 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 writer }}} == Managing Notebooks == === GET api/notebooks === {{{#!xml Gaudi Douglas Adams }}}