}}}
[[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
PeterPeter.Withers@mpi.nlfalse
}}}
=== GET api/principals/info?email=twagoo@mpi.nl ===
{{{#!xml
TwanTwan.Goosen@mpi.nl
}}}
== Retrieving annotations ==
=== Responding GET api/annotations?link=Sagrada ===
all annotations which annotating links containing "Sagrada"
{{{#!xml
Sagrada Famiglia2013-08-12T09:25:00.383Zhttps://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-000000000031https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-000000000032Sagrada Família - Wikipedia, the free encyclopedia2014-04-01T14:06:04.328613Zhttps://lux17.mpi.nl/ds/webannotator/api/targets/fa4bbfff-bca7-47cc-ab48-bb68fe943758de author van het idee2014-04-01T15:06:32.587747Zhttps://lux17.mpi.nl/ds/webannotator/api/targets/d9651f71-42a6-455c-9609-ea856ac227e3Sagrada Família - Wikipedia2014-04-01T13:45:49.029405Zhttps://lux17.mpi.nl/ds/webannotator/api/targets/9d645fa5-026d-49a7-885d-235a5ae8520d
}}}
=== Responding GET api/annotations/00000000-0000-0000-0000-000000000021 ===
{{{#!xml
Sagrada Famiglia2013-08-12T09:25:00.383Ztext/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-000000000031https://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.1https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-000000000032Vroeger Werk
}}}
=== GET api/targets/00000000-0000-0000-0000-000000000032/versions ===
{{{#!xml
https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-000000000032https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-00000000003c
}}}
=== GET api/cached/00000000-0000-0000-0000-000000000051/metadata ===
{{{#!xml
image/pngsome tool 1image
}}}
=== 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 Famiglia2013-08-12T09:25:00.383Ztext/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.1https://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-00000000003chttps://lux17.mpi.nl/ds/webannotator/api/targets/00000000-0000-0000-0000-000000000032Vroeger 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-000000000032https://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/pngsome tool 2image
}}}
== 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 66672013-09-29T19:52:28.969+02:00application/xml+xhtmlX 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 66672014-04-09T12:46:51.754226Zapplication/xml+xhtmlX 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.0CREATE_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 66672014-04-09T12:46:51.754226Zapplication/xml+xhtmlupdate 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 66672014-04-09T12:58:32.793453Zapplication/xml+xhtmlupdate 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.0CREATE_CACHED_REPRESENTATION
}}}
=== PUT api/annotations/1d02f393-da25-4246-934c-876222a2d7fb/body ===
Request body:
{{{#!xml
application/xml+xhtml2 UPDATE X pointer experiment UPDATE body
}}}
Response:
{{{#!xml
update X-Pointer test annotation 66672014-04-09T13:01:21.900643Zapplication/xml+xhtml2 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.0CREATE_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
GaudiDouglas 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.