wiki-archive/twiki/data/TAPIR/ResponseStructure.txt,v

head	1.14;
access;
symbols;
locks; strict;
comment	@# @;


1.14
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.13;

1.13
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.12;

1.12
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.11;

1.11
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.10;

1.10
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.9;

1.9
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.8;

1.8
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.7;

1.7
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.6;

1.6
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.5;

1.5
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.4;

1.4
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.3;

1.3
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.2;

1.2
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	1.1;

1.1
date	2007.01.09.00.00.00;	author MoinMoin;	state Exp;
branches;
next	;


desc
@Initial revision
@


1.14
log
@Revision 14
@
text
@---+ Response Structure

The response structure is the "format" the data is returned in.

To define a ResponseStructure one needs to define a set of valid xml instance documents. For this several languages exist with DTDs and XML schema s being the most used and known.

There are 2 reasons for creating yet another simple language to define an xml instance document "space".
   * it is desirable to have the definition as xml. Xml schemas match this criteria.
   * we need to be able to attach to every potential valid xpath within the space of all instance documents additional information. This is needed to map the concept an element of the custom ResponseStructure to a concept defined in a ConceptualSchema.

---+++++ Proposed Response Structure Definition
   * CustomSearchProposalTwo defines the response structure with the help of XML schema.
   * CustomSearchProposalOne defines a simple response structure using a custom language following the xml schema language as far as possible. 

For both proposals we proposed to use the xpath based ConceptualBinding.
@


1.13
log
@Revision 13
@
text
@d12 2
d15 1
a15 1
   * See CustomSearchProposalOne. The definition of a simple response structure following the xml schema language as far as possible. We proposed to use the xpath based ConceptualBinding.
@


1.12
log
@Revision 12
@
text
@d3 3
a5 1
To define a ResponseStructure one needs to define a set of valid xml instance documents. For this several languages exist with the DTD and xml schema being the most used and known.
a13 1

@


1.11
log
@Revision 11
@
text
@d11 1
a11 1
   * The definition of a simple response structure following the xml schema language as far as possible. We propose to use the xpath based ConceptualBinding. See the CustomSearchProposalOne for this.
@


1.10
log
@Revision 10
@
text
@d3 1
a3 1
The definition of a response structure follows the xml schema language and allows to specify valid xml instance documents in a simple way. Instead of mapping an element to a database attribute it allows to refer to a concept of another well defined ConceptualSchema, which should be mapped to a providers database.
d5 3
a7 1
See the example below taken from the CustomSearch example or take a look at the preliminary schema of the proposed protocol: http://www.bgbm.org/biodivinf/Schema/protocol2.xsd 
d9 1
a9 1
The PyWrapperAlgorithm already uses a simliar structure as the one explained here and has proven to work when substituting the ConceptualBinding with an actual database mapping (table.attribute) of a specific provider.
d11 1
a11 26
<verbatim>
<structure xmlns:abcd="http://www.tdwg.org/schemas/abcd/1.2" xmlns:temp="http://unknown.namespace.org">
   <element name="temp:Taxon" datatype="string" min="0" max="unbounded">
      <attributes>
         <attribute name="FullName" datatype="String" min="1" datatype="string" path="abcd:/DataSets/DataSet/Units/Unit/Identifications/Identification/TaxonIdentified/NameAuthorYearString" ResponseStructure>
         <attribute name="HigherTaxon" datatype="String" min="0" datatype="string" path="abcd:/DataSets/DataSet/Units/Unit/Identifications/Identification/TaxonIdentified/HigherTaxa/HigherTaxon" ResponseStructure>
      </attributes>
      <subelements>
         <element name="temp:Coordinates" min="0" max="unbounded">
            <subelements>
               <element name="lat" min="0" max="1" datatype="string" path="abcd:/DataSets/DataSet/Units/Unit/Gathering/GatheringSite/SiteCoordinateSets/SiteCoordinates/CoordinatesLatLong/LatitudeDecimal" ResponseStructure>
               <element name="long" min="0" max="1" datatype="string" path="abcd:/DataSets/DataSet/Units/Unit/Gathering/GatheringSite/SiteCoordinateSets/SiteCoordinates/CoordinatesLatLong/LongitudeDecimal" ResponseStructure>
            </subelements>
         </element>
      </subelements>
   </element>
</structure>
</verbatim>

   * <element> defines an element for the output as in a schema
      * name = name of the element to appear in responses.
      * path = exact xpath identifying a concept of a ConceptualSchema using an xpath like ConceptualBinding.
      * min ResponseStructure max = give the minimum and maximum occurence of an element.
      * datatype = if a returned value is expected for an element (as opposed to empty "envelope" elements), a basic data type from the w3c xml schema definition is expected. See http://www.w3.org/TR/xmlschema-2/#built-in-datatypes or http://www.w3.org/2000/10/XMLSchema-datatypes for a full list of availbale datatypes.

   * <attribute> defines an attribute with all possible adjectives as an element definition except that the min/max occurence can only be 0 or 1.
@


1.9
log
@Revision 9
@
text
@d10 2
a11 2
<structure>
   <element name="Taxon" datatype="string" min="0" max="unbounded">
d17 1
a17 1
         <element name="Coordinates" min="0" max="unbounded">
d29 3
a31 3
      * schema = namespace of the ConceptualSchema being used to refer to one of its concepts
      * path = exact xpath identifying a concept of a ConceptualSchema using an xpath like ConceptualBinding
      * min ResponseStructure max = give the minimum and maximum occurence of an element. max=-1 means its "unbounded" or indefinitely repeatable
@


1.8
log
@Revision 8
@
text
@d11 1
a11 1
   <element name="Taxon" datatype="string" min="0" max="-1">
d13 2
a14 2
         <attribute name="FullName" datatype="String" min="1" datatype="string" schema="http://www.tdwg.org/schemas/abcd/1.2" path="/DataSets/DataSet/Units/Unit/Identifications/Identification/TaxonIdentified/NameAuthorYearString" ResponseStructure>
         <attribute name="HigherTaxon" datatype="String" min="0" datatype="string" schema="http://www.tdwg.org/schemas/abcd/1.2" path="/DataSets/DataSet/Units/Unit/Identifications/Identification/TaxonIdentified/HigherTaxa/HigherTaxon" ResponseStructure>
d17 1
a17 1
         <element name="Coordinates" min="0" max="-1">
d19 2
a20 4
               <element name="lat" min="0" max="1" datatype="string" schema="http://www.tdwg.org/schemas/abcd/1.2" path="/DataSets/DataSet/Units/Unit/Gathering/GatheringSite/SiteCoordinateSets/SiteCoordinates/CoordinatesLatLong/LatitudeDecimal">
               </element>
               <element name="long" min="0" max="1" datatype="string" schema="http://www.tdwg.org/schemas/abcd/1.2" path="/DataSets/DataSet/Units/Unit/Gathering/GatheringSite/SiteCoordinateSets/SiteCoordinates/CoordinatesLatLong/LongitudeDecimal">
               </element>
@


1.7
log
@Revision 7
@
text
@d18 1
a18 1
            <children>
d20 1
a20 1
            </element>
d22 2
a23 2
            </element>
            </children>
@


1.6
log
@Revision 6
@
text
@d16 1
a16 1
      <children>
d25 1
a25 1
      </children>
@


1.5
log
@Revision 5
@
text
@d7 2
@


1.4
log
@Revision 4
@
text
@d27 9
@


1.3
log
@Revision 3
@
text
@d9 1
a9 1
   <element name="Taxon" datatype="String" min="0" max="-1">
@


1.2
log
@Revision 2
@
text
@d8 1
a8 2
<customDocument responseNS="http://unknown.namespace.org">
   <recordDefinition>/Taxon</recordDefinition>
d25 1
a25 1
</customDocument>
@


1.1
log
@Initial revision
@
text
@d5 23
a27 1
See an example how it is used in the CustomSearch example or take a look at the preliminary schema of the proposed protocol: http://www.bgbm.org/biodivinf/Schema/protocol2.xsd 
@