{{{ #!html

Contents

}}} [[PageOutline(1-3, , inline)]] {{{ #!comment Obviously, your page starts below this block }}} = XSD Schema = == Preamble == There are 5 sorts of resources in DASISH: {{{CachedRepresentation}}}, {{{Target}}}, {{{Principal}}}, {{{Annotation}}}, {{{Notebook}}}. Each of them has the corresponding xsd-type in the schema. There is no an xsd-schema with the name {{{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}}} type. Each of these 5 types has an obligatory attribute "URI" which contains DASISH identifier pointing to the location of the resource on the DASISH server. Resource-info types {{{TargetInfo}}}, {{{AnnotationInfo}}}, {{{NotebookInfo}}} contain reference to the corresponding resource plus the most important information about the resource. There are corresponding list-of-resource-info types: {{{TargetInfos}}}, {{{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. The schema is located at [source:DASISH/t5.6/schema/trunk/annotator-schema/src/main/resources/DASISH-schema.xsd DASISH-schema]. = Scenario XML's validated vs the given schema = See [[DASISH/Scenario]] === GET api/principals/00000000-0000-0000-0000-000000000112 === {{{#!xml Peter Peter.Withers@mpi.nl false }}} === GET api/principals/info?email=twagoo@mpi.nl === {{{#!xml Twan Twan.Goosen@mpi.nl }}} == Retrieving annotations == === Responding GET api/annotations?link=Sagrada === all annotations which annotating links containing "Sagrada" {{{#!xml Sagrada Famiglia 2013-08-12T09:25:00.383Z https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-000000000031 https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-000000000032 Sagrada Família - Wikipedia, the free encyclopedia 2014-04-01T14:06:04.328613Z https://lux17.mpi.nl/ds/webannotator/api/targets/fa4bbfff-bca7-47cc-ab48-bb68fe943758 de author van het idee 2014-04-01T15:06:32.587747Z https://lux17.mpi.nl/ds/webannotator/api/targets/d9651f71-42a6-455c-9609-ea856ac227e3 Sagrada Família - Wikipedia 2014-04-01T13:45:49.029405Z https://lux17.mpi.nl/ds/webannotator/api/targets/9d645fa5-026d-49a7-885d-235a5ae8520d }}} === Responding GET api/annotations/00000000-0000-0000-0000-000000000021 === {{{#!xml Sagrada Famiglia 2013-08-12T09:25:00.383Z text/html <html><body>some html 1</body></html> http://nl.wikipedia.org/wiki/Sagrada_Fam%C3%ADlia#de_Opdracht version 1.0 http://nl.wikipedia.org/wiki/Antoni_Gaud%C3%AD#Vroege_werk version 1.1 }}} === GET api/annotations/00000000-0000-0000-0000-000000000021/targets === {{{#!xml https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-000000000031 https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-000000000032 }}} === GET api/annotations/00000000-0000-0000-0000-000000000021/permissions === {{{#!xml }}} === GET api/targets/00000000-0000-0000-0000-000000000032 === An unresolvable target obeys the same schema. A target becomes unresolvable if e.g. its link becomes obsolete or broken. {{{#!xml 2014-03-13T09:52:51.004723Z http://nl.wikipedia.org/wiki/Antoni_Gaud%C3%AD#Vroege_werk version 1.1 https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-000000000032 Vroeger Werk }}} === GET api/targets/00000000-0000-0000-0000-000000000032/versions === {{{#!xml https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-000000000032 https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-00000000003c }}} === GET api/cached/00000000-0000-0000-0000-000000000051/metadata === {{{#!xml image/png some tool 1 image }}} === Responding GET api/annotations/00000000-0000-0000-0000-00000000002c (example usage for unresolvable targets, step 1) === The respond for an annotation with unresolved targets and the respond for an annotation with resolved targets (see above) are both instances of the same schema element. However, one of the targets of the first annotations annotation refers e.g. to an obsolete version of the page. Next, having the target eferences, 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 Sagrada Famiglia 2013-08-12T09:25:00.383Z text/html <html><body>some html 1</body></html> http://nl.wikipedia.org/wiki/Antoni_Gaud%C3%AD#Vroege_werk_old version 1.1 }}} === Responding GET api/targets/00000000-0000-0000-0000-00000000003c (unresolvable target sources , step 2; the same as for resolvable, just the link is broken or obsolete) === {{{#!xml 2012-03-13T09:52:51.004723Z http://nl.wikipedia.org/wiki/Antoni_Gaud%C3%AD#Vroege_werk_old version 1.1 https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-00000000003c https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-000000000032 Vroeger Werk }}} === Responding GET api/targets/00000000-0000-0000-0000-00000000003c/versions (unresolvable target sources, step 3) === {{{#!xml https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-000000000032 https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-00000000003c }}} === Responding GET api/cached/00000000-0000-0000-0000-000000000052/metadata (unresolvable target sources, step 5) === {{{#!xml image/png some tool 2 image }}} == Making a new annotation == === Request body for POST api/annotations === The new annotation URI, the owner reference will be replaced by the server. The new annotation URI is service URI + the UUID generated by the server. The owner reference is the service URI + logged-in user UUID. The targets's URI will be replaced if the target is new (has not been presented in the dtatabase yet). {{{#!xml X-Pointer test annotation 6667 2013-09-29T19:52:28.969+02:00 application/xml+xhtml X pointer experiment tmpTarget https://developer.mozilla.org/en-US/docs/Building_an_Extension#xpointer(start-point(string-range(//h2[@id="Create_a_Chrome_Manifest"]/text()[1],'',0))/range-to(string-range(//h2[@id="Create_a_Chrome_Manifest"]/text()[1],'',24))) 1.0 }}} === Response body (envelope) for POST api/annotations === The temporary URIs/references are replaced with permanent references. However, no cahced representation is found for the target. Therefore, in the action part of the envelope there is an action CREATE_CACHED_REPRESENTATION for the object which is the target for the web-page. {{{#!xml X-Pointer test annotation 6667 2014-04-09T12:46:51.754226Z application/xml+xhtml X pointer experiment 1db0dbe6-ac89-4a4f-ac4c-c8ff764db232 https://developer.mozilla.org/en-US/docs/Building_an_Extension#xpointer(start-point(string-range(//h2[@id="Create_a_Chrome_Manifest"]/text()[1],'',0))/range-to(string-range(//h2[@id="Create_a_Chrome_Manifest"]/text()[1],'',24))) 1.0 http://lux17.mpi.nl/ds/webannotator/api/targets/1db0dbe6-ac89-4a4f-ac4c-c8ff764db232 CREATE_CACHED_REPRESENTATION }}} 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 an annotation == === PUT api/annotations/1d02f393-da25-4246-934c-876222a2d7fb === Request body : an updated annotation {{{#!xml update X-Pointer test annotation 6667 2014-04-09T12:46:51.754226Z application/xml+xhtml update X pointer experiment 1db0dbe6-ac89-4a4f-ac4c-c8ff764db232 https://developer.mozilla.org/en-US/docs/Building_an_Extension#xpointer(start-point(string-range(//h2[@id="Create_a_Chrome_Manifest"]/text()[1],'',0))/range-to(string-range(//h2[@id="Create_a_Chrome_Manifest"]/text()[1],'',24))) 1.0 }}} Enveloped respond containing new (updated) annotation and a list of actions: {{{#!xml update X-Pointer test annotation 6667 2014-04-09T12:58:32.793453Z application/xml+xhtml update X pointer experiment 1db0dbe6-ac89-4a4f-ac4c-c8ff764db232 https://developer.mozilla.org/en-US/docs/Building_an_Extension#xpointer(start-point(string-range(//h2[@id="Create_a_Chrome_Manifest"]/text()[1],'',0))/range-to(string-range(//h2[@id="Create_a_Chrome_Manifest"]/text()[1],'',24))) 1.0 https://lux17.mpi.nl/ds/webannotator/api/targets/1db0dbe6-ac89-4a4f-ac4c-c8ff764db232 CREATE_CACHED_REPRESENTATION }}} === PUT api/annotations/1d02f393-da25-4246-934c-876222a2d7fb/body === Request body: {{{#!xml application/xml+xhtml 2 UPDATE X pointer experiment UPDATE body }}} Response: {{{#!xml update X-Pointer test annotation 6667 2014-04-09T13:01:21.900643Z application/xml+xhtml 2 UPDATE X pointer experiment UPDATE body https://developer.mozilla.org/en-US/docs/Building_an_Extension#xpointer(start-point(string-range(//h2[@id="Create_a_Chrome_Manifest"]/text()[1],'',0))/range-to(string-range(//h2[@id="Create_a_Chrome_Manifest"]/text()[1],'',24))) 1.0 https://lux17.mpi.nl/ds/webannotator/api/targets/1db0dbe6-ac89-4a4f-ac4c-c8ff764db232 CREATE_CACHED_REPRESENTATION }}} === PUT api/annotations/1d02f393-da25-4246-934c-876222a2d7fb/permissions === Supplementary updating the list of permissions in the annotation: if the principal is not listed in the permission of the annotation, it is added to the list of permissions, otherwise her/his access level is updated in the existing list. Request body: {{{#!xml }}} Respond {{{#!xml }}} Now, assume that principal 00000000-0000-0000-0000-000000000114 is not known to the DASISH data base then respond bey would be: Respond {{{#!xml }}} === PUT api/annotations/1d02f393-da25-4246-934c-876222a2d7fb/permissions/00000000-0000-0000-0000-000000000114 === {{{#!xml write }}} Response: string "1 rows are updated/added". == Managing Notebooks (obsolete section) == === GET api/notebooks === {{{#!xml Gaudi Douglas Adams }}} === GET api/notebooks/NIDxyxy === {{{#!xml Gaudi }}} === 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}}}. = Issues with the schema = As regards all future schema updates, please make sure to remember to update all available scenario xml documents on trac.clarin.eu accordingly, and preferably, with as little delay as possible. It might also be a good idea to validate all of these documents against the revised schema with a reliable XML parser like e.g. the Xerces-J XML parser. Also, if you like, you can check by validating some of our current "real-life" mock xml documents that we have been using for client development ([source:DASISH/t5.6/client/trunk/chrome/markingcollection/content/markingcollection/annotator-service/test/mockjax/mocks]). == Cached Representation BLOB == For the back-end (and the database!): the cached representation for now is stored in the database as a BLOB. See: http://dba.stackexchange.com/questions/803/blobs-or-references-in-postgresql/815#815.