Changes between Version 43 and Version 44 of Discovery/DiscoveryWebServiceMEDIN


Ignore:
Timestamp:
03/12/09 22:07:40 (10 years ago)
Author:
mpritcha
Comment:

Changed capitalisation

Legend:

Unmodified
Added
Removed
Modified
  • Discovery/DiscoveryWebServiceMEDIN

    v43 v44  
    9393[[Image(doSearchSchema.png, 400px)]] 
    9494 
    95 ==== Choice of search criteria: <termSearch>, <spatialSearch> and <temporalSearch> ==== 
    96 The <searchCriteria> element acts as a container enabling the selection of one or more of <termSearch>, <spatialSearch> and <temporalSearch>. Multiple <termSearch> elements, but only one of each of <spatialSearch> and <temporalSearch> may be included, so that the search has at least one component. If more than one of these three main types is specified, the resulting search combines the components in "AND" combination (i.e. metadata records should match the term search AND the spatial search AND the temporal search criteria). 
    97  
    98 ===== termSearch ===== 
    99 !TermSearch is a full-text search invoked on a specific target field in the discovery database. Child elements <term> and <termTarget> should be populated as follows: 
    100   * <term> : text term to search for. Whitespace separates component words, which are searched in "OR" combination unless the "+" symbol is used between them, in which case the words joined in this way are searched in "AND" combination. 
    101   * <termTarget> : target field name taken from the [#termTargetList termTargetList] list of valid term targets. 
    102 If multiple <termSearch> elements are present (e.g. to search different <termTargets) ), these are interpreted as successive term searches to be combined in "AND" combination. For example: 
    103  
    104 {{{ 
    105   <termSearch> 
    106     <term>snow + rain</term> 
    107     <termTarget>abstract</termTarget> 
    108   </termSearch> 
    109   <termSearch> 
    110     <term>lawrence</term> 
    111     <termTarget>author</termTarget> 
    112   </termSearch> 
     95==== Choice of search criteria: <TermSearch>, <SpatialSearch> and <TemporalSearch> ==== 
     96The <SearchCriteria> element acts as a container enabling the selection of one or more of <TermSearch>, <SpatialSearch> and <TemporalSearch>. Multiple <TermSearch> elements, but only one of each of <SpatialSearch> and <TemporalSearch> may be included, so that the search has at least one component. If more than one of these three main types is specified, the resulting search combines the components in "AND" combination (i.e. metadata records should match the term search AND the spatial search AND the temporal search criteria). 
     97 
     98===== TermSearch ===== 
     99!TermSearch is a full-text search invoked on a specific target field in the discovery database. Child elements <Term> and <TermTarget> should be populated as follows: 
     100  * <Term> : text term to search for. Whitespace separates component words, which are searched in "OR" combination unless the "+" symbol is used between them, in which case the words joined in this way are searched in "AND" combination. 
     101  * <TermTarget> : target field name taken from the [#TermTargetList TermTargetList] list of valid term targets. 
     102If multiple <TermSearch> elements are present (e.g. to search different <TermTargets) ), these are interpreted as successive term searches to be combined in "AND" combination. For example: 
     103 
     104{{{ 
     105  <TermSearch> 
     106    <Term>snow + rain</Term> 
     107    <TermTarget>abstract</TermTarget> 
     108  </TermSearch> 
     109  <TermSearch> 
     110    <Term>lawrence</Term> 
     111    <TermTarget>author</TermTarget> 
     112  </TermSearch> 
    113113}}} 
    114114 
     
    120120    author contains "lawrence" 
    121121}}} 
    122 If we were to extend the example by adding an additional termSearch '''also''' targetted at the abstract, this would be combined in OR combination with the first termSearch for '''that''' target (abstract), i.e. 
    123  
    124 {{{ 
    125   <termSearch> 
    126     <term>snow + rain</term> 
    127     <termTarget>abstract</termTarget> 
    128   </termSearch> 
    129   <termSearch> 
    130     <term>lawrence</term> 
    131     <termTarget>author</termTarget> 
    132   </termSearch> 
    133   <termSearch> 
    134     <term>hail</term> 
    135     <termTarget>abstract</termTarget> 
    136   </termSearch> 
     122If we were to extend the example by adding an additional <TermSearch> '''also''' targetted at the abstract, this would be combined in OR combination with the first <TermSearch> for '''that''' target (abstract), i.e. 
     123 
     124{{{ 
     125  <TermSearch> 
     126    <Term>snow + rain</Term> 
     127    <TermTarget>abstract</TermTarget> 
     128  </TermSearch> 
     129  <TermSearch> 
     130    <Term>lawrence</Term> 
     131    <TermTarget>author</TermTarget> 
     132  </TermSearch> 
     133  <TermSearch> 
     134    <Term>hail</Term> 
     135    <TermTarget>abstract</TermTarget> 
     136  </TermSearch> 
    137137}}} 
    138138  
     
    145145}}} 
    146146 
    147 ===== Spatial searching : <spatialOperator> and <boundingBox> ===== 
    148 The search may incorporate a spatial query to restrict results to those metadata records having spatial coverage(s) matching the search criteria defined by the <boundingBox> elements <limitNorth>, <limitSouth>, <limitEast> and <limitWest>. An optional element <spatialReferenceSystem> may be populated with an entry from the [#spatialReferenceSystem spatialReferenceSystem] list to specify an alternative spatial reference system (SRS) of the bounding box coordinates. (*Note : this feature is included for future development e.g. ability to supply spatial search coordinates in British National Grid coordinates. Currently the only supported SRS is EPSG:4326 (WGS84 lat/lon), and this will remain as the default if no SRS is specified. 
    149  
    150 When using SRS EPSG:4326 (default), values for <limitNorth>, <limitSouth>, <limitEast> and <limitWest> should be given in decimal degrees latitude and longitude. <limitNorth> and <limitSouth> must be in the range -90.0 to +90.0, with <limitNorth> greater than <limitSouth>. <limitWest> and <limitEast> must be in the range -180.0 to 180.0 and <limitEast> should be greater than <limitWest>. Bounding boxes that span the -180 degree meridian, or the poles, are not supported. 
    151  
    152 An optional <spatialOperator> may be included, populated with a term from the [#spatialOperatorList spatialOperatorList], defining the comparison to be applied to spatial coverage(s) related to metadata records. The default value is "overlaps". Note that in the discovery index database, metadata records may contain several spatial coverages, so a match can occur if any of the spatial coverages related to the metadata item match the criteria specified in the spatial search.  
     147===== Spatial searching : <SpatialOperator> and <BoundingBox> ===== 
     148The search may incorporate a spatial query to restrict results to those metadata records having spatial coverage(s) matching the search criteria defined by the <BoundingBox> elements <LimitNorth>, <LimitSouth>, <LimitEast> and <LimitWest>. An optional element <SpatialReferenceSystem> may be populated with an entry from the [#SpatialReferenceSystem SpatialReferenceSystem] list to specify an alternative spatial reference system (SRS) of the bounding box coordinates. (*Note : this feature is included for future development e.g. ability to supply spatial search coordinates in British National Grid coordinates. Currently the only supported SRS is EPSG:4326 (WGS84 lat/lon), and this will remain as the default if no SRS is specified.) 
     149 
     150When using SRS EPSG:4326 (default), values for <LimitNorth>, <LimitSouth>, <LimitEast> and <LlimitWest> should be given in decimal degrees latitude and longitude. <LimitNorth> and <LimitSouth> must be in the range -90.0 to +90.0, with <LimitNorth> greater than <LimitSouth>. <LimitWest> and <LimitEast> must be in the range -180.0 to 180.0 and <LimitEast> should be greater than <LimitWest>. Bounding boxes that span the -180 degree meridian, or the poles, are not supported. 
     151 
     152An optional <SpatialOperator> may be included, populated with a term from the [#SpatialOperatorList SpatialOperatorList], defining the comparison to be applied to spatial coverage(s) related to metadata records. The default value is "overlaps". Note that in the discovery index database, metadata records may contain several spatial coverages, so a match can occur if any of the spatial coverages related to the metadata item match the criteria specified in the spatial search.  
    153153 
    154154===== Temporal searching : <!DateRange> ===== 
    155 The search may incoporate a temporal query to restrict results to those metadata records having temporal coverage(s) matching the search criteria specified within <DateRange>. One or two <date> elements may be specified, to represent either a single date, or a date range. Each <date> element must contain a <DateValue> element populated in the form YYYY-MM-DD, and optionally a <temporalOperator> element, populated with a value from [#temporalOperatorList temporalOperatorList], defining the semantic meaning of this date criterion in the search. In addition, an optional <dateRangeTarget> element may be included, populated with a value from the [#dateRangeTargetList dateRangeTargetList], to enable searching of dates other than the default of "temporal coverage of data".  
     155The search may incoporate a temporal query to restrict results to those metadata records having temporal coverage(s) matching the search criteria specified within <DateRange>. One or two <date> elements may be specified, to represent either a single date, or a date range. Each <Date> element must contain a <DateValue> element populated in the form YYYY-MM-DD, and optionally a <TemporalOperator> element, populated with a value from [#TemporalOperatorList TemporalOperatorList], defining the semantic meaning of this date criterion in the search. In addition, an optional <DateRangeTarget> element may be included, populated with a value from the [#DateRangeTargetList DateRangeTargetList], to enable searching of dates other than the default of "temporal coverage of data".  
    156156Examples are shown below: 
    157157 
    158158{{{ 
    159159<DateRange> 
    160   <date> 
     160  <Date> 
    161161    <DateValue>2001-01-01</DateValue>     
    162   </date> 
    163   <date> 
     162  </Date> 
     163  <Date> 
    164164    <DateValue>2002-02-03</DateValue>     
    165   </date> 
    166 </dateRange> 
     165  </Date> 
     166</DateRange> 
    167167}}} 
    168168means 
     
    174174{{{ 
    175175<DateRange> 
    176   <date> 
     176  <Date> 
    177177    <DateValue>2001-01-01</DateValue> 
    178178    <temporalOperator>before</temporalOperator>     
    179   </date> 
    180   <date> 
     179  </Date> 
     180  <Date> 
    181181    <DateValue>2002-02-03</DateValue>     
    182182    <temporalOperator>after</temporalOperator>     
    183   </date> 
    184 </dateRange> 
     183  </Date> 
     184</DateRange> 
    185185}}} 
    186186means 
     
    193193{{{ 
    194194<DateRange> 
    195   <date> 
     195  <Date> 
    196196    <DateValue>2001-01-01</DateValue> 
    197197    <temporalOperator>onOrbefore</temporalOperator>     
    198   </date> 
    199 </dateRange> 
     198  </Date> 
     199</DateRange> 
    200200}}} 
    201201{{{ 
     
    206206{{{ 
    207207<DateRange> 
    208   <date> 
     208  <Date> 
    209209    <DateValue>2001-01-01</DateValue> 
    210210    <temporalOperator>onOrbefore</temporalOperator>     
    211   </date> 
    212   <dateRangeTarget>lastRevisionDate</dateRangeTarget> 
    213 </dateRange> 
     211  </Date> 
     212  <DateRangeTarget>lastRevisionDate</dateRangeTarget> 
     213</DateRange> 
    214214}}} 
    215215means 
     
    219219}}} 
    220220 
    221 > Looking at these examples we might need to tidy up the capitalisation of elements in the schema & WSDL. 
    222  
    223 ==== Paging : <start> and <howMany> ==== 
    224 The optional elements <start> and <howMany> control which records from the result set should be returned (although the total number of hits is always returned as a number to aid with paging in clients). If <start> is omitted, the default value used is 1 (i.e. the first record). If <howMany> is omitted, '''all''' records are returned. 
    225  
    226  
    227 ==== Ordering: <orderBy> and <orderByDirection> ==== 
    228 Ordering of the result set can optionally be requested by providing an <orderBy> element containing one or more <orderByField>s, each with an optional associated <orderByDirection> (default : descending). Available fields for use as an <orderByField> are listed in the [#orderByFieldsList orderByFieldList]. 
    229  
    230 ==== Scope of search: <scope> ==== 
    231 The optional <scope> element can be used to restrict the search to onr or more of the supported NDG Data Provider Groups, defined in NDG controlled vocabulary http://vocab.ndg.nerc.ac.uk/list/N010/0. Currently supported values from this vocabulary are these are given in the the [#scopeList scopeList] list accessible via the getList operation. 
    232 If <scope> is omitted, the search is not restricted in this way. 
     221==== Paging : <Start> and <HowMany> ==== 
     222The optional elements <Start> and <HowMany> control which records from the result set should be returned (although the total number of hits is always returned as a number to aid with paging in clients). If <Start> is omitted, the default value used is 1 (i.e. the first record). If <HowMany> is omitted, '''all''' records are returned. 
     223 
     224 
     225==== Ordering: <OrderBy> and <OrderByDirection> ==== 
     226Ordering of the result set can optionally be requested by providing an <OrderBy> element containing one or more <OrderByField>s, each with an optional associated <orderByDirection> (default : descending). Available fields for use as an <OrderByField> are listed in the [#OrderByFieldsList OrderByFieldList]. 
     227 
     228==== Scope of search: <Scope> ==== 
     229The optional <Scope> element can be used to restrict the search to onr or more of the supported NDG Data Provider Groups, defined in NDG controlled vocabulary http://vocab.ndg.nerc.ac.uk/list/N010/0. Currently supported values from this vocabulary are these are given in the the [#ScopeList ScopeList] list accessible via the getList operation. 
     230If <Scope> is omitted, the search is not restricted in this way. 
    233231 
    234232==== Format ==== 
    235 The optional <format> element can be used to restrict the search to records in the discovery index whose original (harvested) representation was in the format specified. The format must be one of the values listed in the [#metadataFormatList metadataFormatList] available from the getList operation. Default behaviour if this element is omitted is not to restrict the search in this way (and return results irrepsective of their harvested format). 
     233The optional <Format> element can be used to restrict the search to records in the discovery index whose original (harvested) representation was in the format specified. The format must be one of the values listed in the [#metadataFormatList metadataFormatList] available from the getList operation. Default behaviour if this element is omitted is not to restrict the search in this way (and return results irrepsective of their harvested format). 
    236234 
    237235==== !RecordDetail ==== 
    238 The optional <recordDetail> element enables selection of the level of detail included in each result returned in the search result. Values must be one of those available from the [#recordDetailList recordDetailList]. Default is documentId, which simply returns the id of the document corresponding to the result. See [#SearchResults Search Results] section for further explanation of the structures returned in each of these cases. 
    239  
    240  
    241 ==== Search results ==== 
     236The optional <RecordDetail> element enables selection of the level of detail included in each result returned in the search result. Values must be one of those available from the [#RecordDetailList RecordDetailList]. Default is DocumentId, which simply returns the id of the document corresponding to the result. See [#SearchResults Search Results] section for further explanation of the structures returned in each of these cases. 
     237 
     238 
     239==== Search Results ==== 
    242240The doSearchResponse message is defined in the WSDL as shown below (click image for larger version): 
    243241 
    244242[[Image(doSearchReturnSchema.png, 400px)]] 
    245243 
    246 The <doSearchReturn> element contains the following top-level elements: 
    247  
    248   status:: 
     244The <DoSearchReturn> element contains the following top-level elements: 
     245 
     246  Status:: 
    249247    true if successful AND number of hits > 0, false otherwise (designed so that a client need only proceed to parse the rest of the message if results were successfully returned)  
    250   statusMessage:: 
     248  StatusMessage:: 
    251249    Textual information regarding success / failure / errors  
    252   resultId:: 
     250  ResultId:: 
    253251    reserved for future use  
    254   hits:: 
     252  Hits:: 
    255253    TOTAL number of hits returned  
    256   documents:: 
    257     parent element for <documentId>, <documentBrief> OR <documentSummary> elements (as per choice in search request) containing returned results.  
     254  Documents:: 
     255    parent element for <DocumentId>, <DocumentBrief> OR <DocumentSummary> elements (as per choice in search request) containing returned results.  
    258256 
    259257A result where no hits were returned is shown below: 
    260258{{{ 
    261 <doSearchReturn xmlns="urn:DiscoveryServiceAPI"> 
    262         <status>false</status> 
    263         <statusMessage>Search was successful but generated no results.</statusMessage> 
    264         <resultId>0</resultId> 
    265         <hits>0</hits> 
    266 </doSearchReturn> 
    267 }}} 
    268  
    269 A result where 2 hits were returned, with the recordDetail set to documentId, is shown below: 
    270 {{{ 
    271 <doSearchReturn xmlns="urn:DiscoveryServiceAPI"> 
    272         <status>true</status> 
    273         <statusMessage>Search was successful.</statusMessage> 
    274         <resultId>0</resultId> 
    275         <hits>2</hits> 
    276         <documents> 
    277           <documentId>idForResult1GoesHere</documentId> 
    278           <documentId>idForResult2GoesHere</documentId> 
    279         </documents> 
    280 </doSearchReturn> 
    281 }}} 
    282  
    283 If <documentBrief> is specified as the recordDetail, a <documentBrief> element is returned for each result, as outlined in the doSearchResponeMessage, above. This contains the <documentId> element, containing the id of the document, but is accompanied by the additional element <title>, containing the title from the metadata record, and a set of <orderedField> elements corresponding to the <orderByField>s used in the search request. In other words, the requested ordering fields are returned alongside the results so that a client can display the content of those fields which contributed to the resulting record ordering. The purpose of this <documentBrief> detail option is to enable clients to render a results list directly from the search response, without having immediately to invoke the doPresent operation to retrieve additional detail. 
    284  
    285 Similarly, if <documentSummary> is specified as the recordDetail, a <documentSummary> element is returned for each result, as outlined in the doSearchResponseMessage, above. In addition to the content added by the <documentBrief> option, <documentSummary> includes the metadata abstract, and temporal and spatial information. For the temporal and spatial components of this <documentSummary> the schema reuses the structures used for the search request, hence the optional temporalOperator are spatialOperator elements are redundant (and will be omitted) from the return context, however the dateRangeTarget element is useful as a contextual reminder of what the returned date pertains to (temporal coverage of data, last revision date of data, or ingestion date of metadata, etc.). 
    286  
    287 A corresponding <documentFull> structure is used in the [#doPresentoperation doPresent operation] operation as the structure in which the document payload is returned. 
     259<DoSearchReturn xmlns="urn:DiscoveryServiceAPI"> 
     260        <Status>false</Status> 
     261        <StatusMessage>Search was successful but generated no results.</StatusMessage> 
     262        <ResultId>0</ResultId> 
     263        <Hits>0</hits> 
     264</DoSearchReturn> 
     265}}} 
     266 
     267A result where 2 hits were returned, with the <RecordDetail> set to DocumentId, is shown below: 
     268{{{ 
     269<DoSearchReturn xmlns="urn:DiscoveryServiceAPI"> 
     270        <Status>true</Status> 
     271        <StatusMessage>Search was successful.</StatusMessage> 
     272        <ResultId>0</ResultId> 
     273        <Hits>2</Hits> 
     274        <Documents> 
     275          <DocumentId>idForResult1GoesHere</DocumentId> 
     276          <DocumentId>idForResult2GoesHere</DocumentId> 
     277        </Documents> 
     278</DoSearchReturn> 
     279}}} 
     280 
     281If <DocumentBrief> is specified as the recordDetail, a <DocumentBrief> element is returned for each result, as outlined in the doSearchResponeMessage, above. This contains the <DocumentId> element, containing the id of the document, but is accompanied by the additional element <Title>, containing the title from the metadata record, and a set of <OrderedField> elements corresponding to the <OrderByField>s used in the search request. In other words, the requested ordering fields are returned alongside the results so that a client can display the content of those fields which contributed to the resulting record ordering. The purpose of this <DocumentBrief> detail option is to enable clients to render a results list directly from the search response, without having immediately to invoke the doPresent operation to retrieve additional detail. 
     282 
     283Similarly, if <DocumentSummary> is specified as the recordDetail, a <DocumentSummary> element is returned for each result, as outlined in the doSearchResponseMessage, above. In addition to the content added by the <DocumentBrief> option, <DocumentSummary> includes the metadata abstract, and temporal and spatial information. For the temporal and spatial components of this <DocumentSummary> the schema reuses the structures used for the search request, hence the optional temporalOperator are spatialOperator elements are redundant (and will be omitted) from the return context, however the dateRangeTarget element is useful as a contextual reminder of what the returned date pertains to (temporal coverage of data, last revision date of data, or ingestion date of metadata, etc.). 
     284 
     285A corresponding <DocumentFull> structure is used in the [#doPresentoperation doPresent operation] operation as the structure in which the document payload is returned. 
    288286 
    289287=== doPresent operation === 
     
    293291[[Image(doPresentSchema.png, 400px)]] 
    294292 
    295 Within the <documents> element, one or more <documentId> elements should each contain the name of a document (in the form returned in the <documentId> of the doSearchReturn message) to be retrieved. The optional <format> element should be populated with one of the supported format names as listed by the presentFormatList accessible via the [#getListoperation getList] operation. All documents returned by a single invocation of the doPresent operation are returned in the same format, i.e. the choice of presentFormat applies to the doPresent request and not individual documents. 
    296 For information, it should be noted that documents harvested (via OAI-PMH) are, at the time of ingest, stored in their native format but additionally converted to static copies of each of the supported return formats (listed in the [#presentFormatList presentFormatList].) When a document is requested for presenation in a particular format, the static copy (either the native copy or the generated copy in the requested format) is returned from the database. 
     293Within the <Documents> element, one or more <DocumentId> elements should each contain the name of a document (in the form returned in the <DocumentId> of the doSearchReturn message) to be retrieved. The optional <Format> element should be populated with one of the supported format names as listed by the PresentFormatList accessible via the [#getListoperation getList] operation. All documents returned by a single invocation of the doPresent operation are returned in the same format, i.e. the choice of presentFormat applies to the doPresent request and not individual documents. 
     294For information, it should be noted that documents harvested (via OAI-PMH) are, at the time of ingest, stored in their native format but additionally converted to static copies of each of the supported return formats (listed in the [#PresentFormatList PresentFormatList].) When a document is requested for presenation in a particular format, the static copy (either the native copy or the generated copy in the requested format) is returned from the database. 
    297295 
    298296==== doPresent response ==== 
     
    301299[[Image(doPresentReturnSchema.png, 400px)]] 
    302300 
    303 The <doPresentReturn> element contains the following top-level elements: 
    304  
    305   <status>:: 
     301The <DoPresentReturn> element contains the following top-level elements: 
     302 
     303  <Status>:: 
    306304    true if there are any documents returned in the payload, false otherwise.  
    307   <statusMessage>:: 
     305  <StatusMessage>:: 
    308306    Textual information regarding success / failure / errors.  
    309   <documents>:: 
    310     If some documents have been successfully returned, a <documents> element is present and will contain a child <document> element for each document retrieved. In the case where some but not all documents are successfully returned, the <documents> element will contain populated <document> elements for the successfully-retrieved documents, but an empty <document> element for those where retrieval failed. If NO documents are successfully returned, however, then the <status> is set to false and no <documents> element is included in the doPresentResponse message. 
    311  
    312 The <document> element, if present and populated, contains the retrieved document as an encapsulated string representation of the XML. Depending on the client used to display the payload document, it either appears contained within a <![CDATA[ ... ]]> construct, or as XML with the opening angle brackets "<" escaped as "&lt;". Most XML parsers should successfully parse the string to reconstruct the XML document, but it is returned in this form to avoid namespace issues.  
     307  <Documents>:: 
     308    If some documents have been successfully returned, a <documents> element is present and will contain a child <DocumentFull> element for each document retrieved. In the case where some but not all documents are successfully returned, the <Documents> element will contain populated <DocumentFull> elements for the successfully-retrieved documents, but <DocumentFull> elements containing a populated <DocumentId> but unpopulated <Document> element for those where retrieval failed. If NO documents are successfully returned, however, then the <Status> is set to false and no <Documents> element is included in the doPresentResponse message. 
     309 
     310The <Document> element, if present and populated, contains the retrieved document as an encapsulated string representation of the XML. Depending on the client used to display the payload document, it either appears contained within a <![CDATA[ ... ]]> construct, or as XML with the opening angle brackets "<" escaped as "&lt;". Most XML parsers should successfully parse the string to reconstruct the XML document, but it is returned in this form to avoid namespace issues.  
    313311 
    314312The following request / response sequence shows a successful doPresent operation: 
     
    316314Request: 
    317315{{{ 
    318 <m:doPresent xmlns:m="urn:DiscoveryServiceAPI"> 
    319     <m:documents> 
    320         <m:documentId>badc.nerc.ac.uk__DIF__dataent_claus.xml</m:documentId> 
    321     </m:documents> 
    322     <m:format>DIF_v9.4</m:format> 
    323 </m:doPresent> 
     316<m:DoPresent xmlns:m="urn:DiscoveryServiceAPI"> 
     317    <m:Documents> 
     318        <m:DocumentId>badc.nerc.ac.uk__DIF__dataent_claus.xml</m:DocumentId> 
     319    </m:Documents> 
     320    <m:Format>DIF_v9.4</m:Format> 
     321</m:DoPresent> 
    324322}}} 
    325323 
    326324Response: 
    327325{{{ 
    328 <doPresentReturn xmlns="urn:DiscoveryServiceAPI"> 
    329     <status>true</status> 
    330     <statusMessage>Success</statusMessage> 
    331     <documents> 
    332         <documentFull> 
    333            <documentId>badc.nerc.ac.uk__DIF__dataent_claus.xml</documentId> 
    334            <title>Cloud Archive User Service data (CLAUS)</title> 
    335            <abstract>Global Brightness Temperature imagery from the  
     326<DoPresentReturn xmlns="urn:DiscoveryServiceAPI"> 
     327    <Status>true</Status> 
     328    <StatusMessage>Success</StatusMessage> 
     329    <Documents> 
     330        <DocumentFull> 
     331           <DocumentId>badc.nerc.ac.uk__DIF__dataent_claus.xml</DocumentId> 
     332           <Title>Cloud Archive User Service data (CLAUS)</Title> 
     333           <Abstract>Global Brightness Temperature imagery from the  
    336334Cloud Archive User Service project. This project produced a long  
    337335time-series of global thermal infra-red imagery of the Earth using  
    338336data from operational meteorological satellites, which was used in  
    339 validating atmospheric General Circulation Models</abstract> 
    340            <document>&lt;DIF xmlns="http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/"  
     337validating atmospheric General Circulation Models</Abstract> 
     338           <Document>&lt;DIF xmlns="http://gcmd.gsfc.nasa.gov/Aboutus/xml/dif/"  
    341339xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> 
    342340&lt;Entry_ID>badc.nerc.ac.uk:DIF:dataent_claus&lt;/Entry_ID> 
    343  (.. truncated! ..) &lt;/DIF></document> 
    344         </documentFull> 
    345     </documents> 
    346 </doPresentReturn> 
     341 (.. truncated! ..) &lt;/DIF></Document> 
     342        </DocumentFull> 
     343    </Documents> 
     344</DoPresentReturn> 
    347345}}} 
    348346 
     
    352350The following lists and their contents are available via the getListNames and getList operations, but are repeated here with explanations of the list members. 
    353351 
    354 === termTargetList === 
    355  fullText:: 
     352=== TermTargetList === 
     353 FullText:: 
    356354   Target is a stored version of the original harvested XML metadata document 
    357  author:: 
     355 Author:: 
    358356   Target is the entry in the discovery index database corresponding to the author of the data described by the metadata. 
    359  parameter:: 
     357 Parameter:: 
    360358   Target is entries in the discovery index database corresponding to parameter keywords extracted from the metadata. 
    361359 MEDINTermTarget.1*:: 
    362360   Target is entry in the discovery database corresponding to the '''MEDINTermTarget.1''' field in the MEDIN metadata format. (*It has been agreed that the search capability will be extended to support direct searching of a limited number of target fields within the MEDIN metadata format. List of fields currently to be confirmed by MEDIN). 
    363361 
    364 === presentFormatList === 
     362=== PresentFormatList === 
    365363 
    366364 DC:: 
     
    373371   ISO19115 (Geographic Information: Metadata) encoded as ISO19139 XML. Currently an alias for MEDIN_v2.3.1, i.e. the MEDIN format is used as the implementation of ISO within the Discovery Service. 
    374372 
    375 === orderByFieldList === 
    376  textRelevance:: 
     373=== OrderByFieldList === 
     374 TextRelevance:: 
    377375   Ranking metric based on relevance of match to search term (metric derived by postgres text ranking function). 
    378  datasetStartDate::  
     376 DatasetStartDate::  
    379377   The start date of the date range given for the temporal coverage of the metadata record. Records with no start date defined are treated as if their start date is later than that last record with a start date defined, hence appearing at the end of the results. 
    380  datasetEndDate::  
     378 DatasetEndDate::  
    381379   The end date of the date range given for the temporal coverage of the metadata record. Records with no end date defined are treated as if their end date is later than that last record with a start date defined, hence appearing at the end of the results. 
    382  dataCentre:: 
     380 DataCentre:: 
    383381   The name of the data centre supplying the metadata record. In the case of records supplied in DIF format, this is the Data_Centre_Name/Short_Name field. In the case of other metadata formats, the most appropriate equivalent field is used as this index (e.g. "DistributorName" for MDIP format) 
    384  datasetResultsetPopularity:: 
     382 DatasetResultsetPopularity:: 
    385383   Measure of the popularity of a metadata record, related to how many times it has appeared in a result set in discovery searches. 
    386  proximity:: 
     384 Proximity:: 
    387385   The geographical proximity of the centre of the spatial coverage defined in the metadata record to the centre of the original search bounding box.  Where no spatial information was originally selected proximity is calculated against the centre of a 'global' bounding box (0N, 0E).  Metadata records with no spatial information originally defined are omitted from the search 
    388  proximityNearMiss:: 
     386 ProximityNearMiss:: 
    389387   An ordering based on records that were not within the originally requested spatial extent, but that occur within an arbritrary 10% of the original bounding box extent.  Where records are present that satisfy this scenario, they are ordered according to proximity to the outside edge of the original bounding box.  This option is to give users an idea of datasets that were close to the original bounding box and still matched the search without having to redefine the original bounding box and original search terms.  
    390  datasetUpdateOrder:: 
     388 DatasetUpdateOrder:: 
    391389   Date order based on the most recent update/edit by the original provider to the metadata record. 
    392  datasetOrder:: 
     390 DatasetOrder:: 
    393391   Alphabetical order based on the name of the metadata record.  In DIF records this is the Entry_Title field and for MDIP the Title field. 
    394  discoveryIngestDate:: 
     392 DiscoveryIngestDate:: 
    395393   Date order based on the date of insertion of that record into the underlying database supporting the service.  Note that this differs from "datasetUpdateOrder" in that this records the actual date a record was placed in the database as opposed to the last edit date of that record. 
    396394 MEDINTermTarget.1*:: 
    397395   One of fields specified by MEDIN for use as a termTarget : it should be possible to configure these for use as orderByFields, too. 
    398396 
    399 === scopeList === 
     397=== ScopeList === 
    400398 MDIP:: 
    401399   Marine Data Information Partnership (organisation now renamed MEDIN) 
     
    410408 
    411409 
    412 === spatialOperatorList === 
    413  overlaps (default):: 
     410=== SpatialOperatorList === 
     411 Overlaps (default):: 
    414412   Return metadata records having one or more spatial coverages that spatially overlap the search bounding box.  
    415  doesNotOverlap:: 
     413 DoesNotOverlap:: 
    416414   Return metadata records having no spatial coverages that spatially overlap the search bounding box. 
    417  within:: 
     415 Within:: 
    418416   Return metadata records having one or more spatial coverages that are entirely within the search bounding box. 
    419417 
    420 > Should we restrict this to ("...having '''all''' spatial coverages that entirely within the..." ?). No : above definition is more intuitive. 
    421  
    422 === spatialReferenceSystemList === 
     418=== SpatialReferenceSystemList === 
    423419 EPSG:4326:: 
    424420   WGS84 Lat/Lon, in decimal degrees 
    425421 
    426 === dateRangeTargetList === 
    427  temporalCoverage:: 
     422=== DateRangeTargetList === 
     423 TemporalCoverage:: 
    428424   The temporal coverage of the data described by the metadata record. 
    429  lastRevisionDate:: 
     425 LastRevisionDate:: 
    430426   The data of last revision to the dataset, recorded in the metadata record. 
    431  discoveryIngestDate:: 
     427 DiscoveryIngestDate:: 
    432428   The date that the metadata record was (last) ingested into the discovery index. 
    433429 
    434 === temporalOperatorList === 
    435  equals:: 
     430=== TemporalOperatorList === 
     431 Equals:: 
    436432   Target date value is the same as the date specified 
    437  doesNotEqual:: 
     433 DoesNotEqual:: 
    438434   Target date values does not equal the date specified 
    439  onOrBefore:: 
     435 OnOrBefore:: 
    440436   Target date is equal to or before the date specified 
    441  onOrAfter:: 
     437 OnOrAfter:: 
    442438   Target date is equal to or after the date specified 
    443  before:: 
     439 Before:: 
    444440   Target date is before the date specified 
    445  after:: 
     441 After:: 
    446442   Target date is after the date specified 
    447443 
    448 === metadataFormatList === 
     444=== MetadataFormatList === 
    449445(Note this is separate from presentFormatList, to distinguish between purposes). metadataFormatList lists values available to distinguish the original source format of a harvested metadata item. 
    450446 
     
    458454   ISO19115 (Geographic Information: Metadata) encoded as ISO19139 XML. Currently an alias for MEDIN_v2.3.1, i.e. the MEDIN format is used as the implementation of ISO within the Discovery Service. 
    459455 
    460 === recordDetailList === 
    461  id:: 
    462    Return a <documentId> element containing the id of the matching metadata document, in a form that can be used as input to a doPresent request. 
    463  brief:: 
    464    Return a <documentBrief> element containing a <documentId> element, the title and ordering fields. 
    465  summary:: 
    466    Return a <documentSummary> element containing content as per <documentBrief> but additionally abstract, temporal and spatial information. 
    467  
     456=== RecordDetailList === 
     457 Id:: 
     458   Return a <DocumentId> element containing the id of the matching metadata document, in a form that can be used as input to a doPresent request. 
     459 Brief:: 
     460   Return a <DocumentBrief> element containing a <DocumentId> element, the title and ordering fields. 
     461 Summary:: 
     462   Return a <DocumentSummary> element containing content as per <DocumentBrief> but additionally abstract, temporal and spatial information. 
     463