home *** CD-ROM | disk | FTP | other *** search
/ Internet Info 1997 December / Internet_Info_CD-ROM_Walnut_Creek_December_1997.iso / drafts / draft_s_z / draft-vangulik-http-search-01.txt < prev    next >
Text File  |  1997-07-15  |  39KB  |  1,019 lines
  1.  
  2. INTERNET DRAFT                        Clive Best, Dirk-Willem van Gulik,
  3. draft-vangulik-http-search-01.txt     Michael Kleih, ISIS/CEO, JRC Ispra
  4. Expires: 23/01/1998                       Zavisa Bjelogrlic, Web Bridges  
  5.                                       
  6.                                
  7.  
  8.               HTTP based Geo-temporal Searching (HGS).
  9.  
  10. Status of this Memo
  11. ===================
  12.  
  13.     This document is an Internet-Draft.  Internet-Drafts are working
  14.     documents of the Internet Engineering Task Force (IETF), its
  15.     areas, and its working groups.  Note that other groups may also
  16.     distribute working documents as Internet-Drafts.
  17.   
  18.     Internet-Drafts are draft documents valid for a maximum of six
  19.     months and may be updated, replaced, or obsoleted by other
  20.     documents at any time.  It is inappropriate to use Internet-
  21.     Drafts as reference material or to cite them other than as
  22.     ``work in progress.''
  23.   
  24.     To learn the current status of any Internet-Draft, please check
  25.     the ``1id-abstracts.txt'' listing contained in the Internet-
  26.     Drafts Shadow Directories on ftp.is.co.za (Africa),
  27.     nic.nordu.net (Europe), munnari.oz.au (Pacific Rim),
  28.     ds.internic.net (US East Coast), or ftp.isi.edu (US West Coast).
  29.  
  30.     This draft expires in six months.
  31.   
  32. Abstract:
  33. =========
  34.  
  35. This draft specifies the first three levels of operation of an http 
  36. based distributed search protocol. It is designed for parallel 
  37. client-side searching  of geospatial  catalogues. An important design 
  38. objective is to minimize the impact and extra resources for catalogue 
  39. sites which already have existing WWW gateways and search interfaces. 
  40.  
  41. Recent Changes: 00 to 01
  42. ========================
  43.  
  44. Since the first draft; several interoperable prototypes are made availble
  45. from the url: http://www.ceo.org/hgs/ which span a wide array of EO data
  46. services such as ewse, enrm, isis, dali, fgdc, etc, etc..
  47.  
  48. Removal of Keywords on Directory level, because of difficulty of defining 
  49. a standard thesaurus. Generalise the Advertise directory structure to allow
  50. distributed collections of resources. Explain now referenced by URI and 
  51. made explicitly for allowing local attribute searching. 'SetURI' and 'SiteURI'
  52. merged into 'URI'. 'free' vs 'text' tag names corrected.
  53.     
  54.                          
  55. Introduction
  56. ============
  57.  
  58. WWW interfaces to databases referenced by geospatial and temporal
  59. attributes are a growing public resource for Environment, GIS and
  60. Earth Observation.  Each provider has developed their own specialised
  61. Web interface that best represents their particular database schema.
  62. These databases are then searched by a Web Browser typically via a map
  63. and time interface. The results are returned by generated html.
  64.  
  65. Experience with these interfaces suggests that the most sought-after
  66. requirements of end-users for searching these databases are few in
  67. number and relatively standard in form.  End-Users require to  search
  68. for resources which relate to a spatial area, a certain temporal
  69. coverage, and perhaps one or more keywords. This search-request is
  70. typically repeated on different data collections at several,
  71. operationally disjoint sites. Only if sufficient information is
  72. found, is the user willing to explore the collection-specific 
  73. retrieval facility.
  74.  
  75. The  HTTP based Geo-temporal Searching (HGS) protocol then
  76. defines a mechanism whereby disparate remote databases can be searched
  77. through a single standard  HTTP interface.  Making use of either HTTP
  78. based GET or POST operations, several standard queries are defined. A
  79. database with an HGS  interface will become remote searchable
  80. via any HTTP client, robot, or special user-agent. Easy deployment will
  81. have  minimal impact on existing web-based query-and-retrieval
  82. infrastructure. This has been one of the main design considerations.
  83.  
  84. The core of the protocol consists of three types of stateless
  85. client-server interactions over HTTP: 'Advertise', 'Search' and
  86. 'Explain'. The 'Advertise' request yields information on the dataset
  87. and services provided by an information provider; the 'Search' request
  88. allows for actual searching; whereas 'Explain' provides a mechanism to
  89. publish specific database attributes in use by a specific provider.
  90. This information can then be used to enhance the 'Search' beyond
  91. the simple, and mandatory, spatial, temporal and free text
  92. criteria. 
  93.  
  94. There is no 'Retrieve' request as such since existing (perhaps
  95. standard) web interfaces will to be pointed to by means of a URI. 
  96. The URI itself can contain services like Browse and Ordering, 
  97. but this is outside the domain of HGS.
  98.  
  99. One aim of HGS is to allow the construction of general purpose
  100. (Java) clients and user-agents.  Ultimately a user could specify the
  101. search criteria, and then expect the user-agent to contact the
  102. various collections, and present a single collated result set.
  103. Once one or more promising resources are identified via URIs,
  104. conventional technology is used to further interface to  the site. 
  105. HGS does not aim to intervene in this part of the process, since 
  106. it will be site dependent.
  107.  
  108. Service discovery will be supported by maintaining a register of
  109. compliant servers, possibly distributed at each site. These registries
  110. allow clients to configure themselves dynamically. This service layer
  111. is defined as the 'Advertise' layer.
  112.  
  113. All servers must support the 'Advertise' layer even if they contain
  114. just one reference to the self same service. However it is expected
  115. that user and research communities will maintain structured lists of 
  116. related services. In addition one can envisage that a specialist client will
  117. support a local user defined register of search sites customised
  118. according  to given interests.
  119.  
  120. The above notion of service discovery borrows from the popularity of
  121. 'hotlists' and lists-of-lists.  The idea is that this level 0
  122. information might be presented by the user-agent in a partially nested
  123. or linked way. The user is than able to select certain services or
  124. groups of services, and move these to a list of preferred servers.
  125.  
  126. The advertise layer is both distributed and structured. Entries can
  127. be grouped into "collections". Entries can point directly to a "Search"
  128. URI or link to another collection. A provider can therefore publish 
  129. their data holdings according to different classifications (collections)
  130. e.g. 'by Platform', 'by Sensor', 'by Dataset'. 
  131.  
  132. The 'Search' function will be satisfied by all servers and allow  an
  133. interoperable geographic/temporal search across all systems. An
  134. additional, optional free text field will be supported. It is
  135. envisioned that the returned information will allow the construction
  136. of graphic coverage maps and footprints.
  137.  
  138. The optional 'Explain' function allows a server to publish their particular
  139. database scheme for more targeted searching. Such customised searching
  140. can only apply to servers with the same attributes. The Explain data is 
  141. accessed on demend by the client.
  142.  
  143.  
  144. Architecture
  145. ============
  146.  
  147. Although the protocol definition allows for a very flexible 
  148. infrastructure. The dogma that 'a client can do what it
  149. wants' holds true. The design assumes that:
  150.  
  151. 1. The client will do most of the work. It will contact the
  152.    advertise and search services directly; and will be responsible 
  153.    for any of caching. The cleint is responsible for result 
  154.    collation and possible state handling.
  155.  
  156. 2. The Advertise services do not nessesarily share the same
  157.    machine as the Search services. Furthermore it is expected that
  158.    user-communities might operate shared directory services or
  159.    interconnected directories for specific datasets and resources.
  160.  
  161. 3. The search service does not nessesarily share the same machine
  162.    as the normal web-based retrival interface; a third party may
  163.    also reverse engineer an retrival URL on an arbitrary web 
  164.    catalogue.
  165.  
  166. 4. Although the search request can be 'fuzzy'; the returned records
  167.    do have accurate spatial and temporal coverage information; thus
  168.    reducing; where possible, the need for repeated, refining, queries.
  169.  
  170.  
  171. 'Advertise'
  172. ===========
  173.  
  174. A directory of servers is accessed via a url. Servers should
  175. publish and maintain the directory on a standard url construction,
  176. such as http://fully.qualified.host.name/hgs.txt. Agencies can 
  177. maintain master copies of directories and each server can 
  178. maintain a local version for updating and access. Service discovery 
  179. can therefore be distributed. A given physical http server can 
  180. support more than one service. Each service should be specified 
  181. by a short text descriptor.
  182.  
  183. The information below is provided over the normal HTTP service
  184. layer, including the MIME encapsulation of specific languages,
  185. character sets and encoding. A server must be able to serve a
  186. request for a version of this document in the latin-1 character
  187. set, 8 bit encoding and the English language. 
  188.  
  189. The cache/mirror support of HTTP can be used by providers to
  190. give an indication of the time-to-live, date of last modification
  191. and or expiry date. Thus enabling a clever enough UserAgent to
  192. be able to refresh the directory data when needed.
  193.  
  194. The content of the reply to the 'Advertise' request uri consists of an
  195. entry describing the discovery service, followed by a series of
  196. directory entries, separated by a blank line. The entry for the
  197. discovery service is identical to the directory entry, except for
  198. the omission of the URL entry. In addition a pointer to an optional
  199. 'Explain' resource may be provided.
  200.  
  201. Server Specific Information
  202. ---------------------------
  203. Firstly the general collection/directory information itself is
  204. presented  from the server.
  205. The content of the collection node for directory discovery  is as
  206. follows, each item is encoding using colon separated RFC822 field
  207. value pairs.
  208.  
  209. Version          The HGS protocol version understood by this
  210.               directory service; major and minor version number.
  211.               Changes in minor version number are expected to be
  212.               backward and forward compatible (at a possible loss
  213.               of functionality).
  214.  
  215.               Example: 1.00
  216.               Mandatory, non-repeatable
  217.  
  218. Name          The name of this directory service. Clients must be
  219.               able to cope with names of at least 70 symbols in
  220.               length. However a client should be able to handle
  221.               strings of arbitrary length.
  222.  
  223.               Example: The Wetland HGS Directory service
  224.               Mandatory, non-repeatable
  225.  
  226.  
  227. Description   A short description of this directory service and
  228.               the community it addresses. Clients must be able to
  229.               cope with a description of at least 4 kbyte in
  230.               length.
  231.  
  232.               Example: A collection of services, with dataset
  233.                     relating to wetlands, marches, estuaries  and
  234.                     coastal zones, mostly in a ecology and bio-
  235.                     diversity context.
  236.               Optional, non-repeatable
  237.  
  238. URI           A full URL to a more elaborate description of this
  239.               directory service, the organization which operates it
  240.               and a possible contact addresses. Repeatable entries
  241.               are each to refer to pages which convey the same
  242.               information.
  243.  
  244.               Example: http://www.ceo.org/wetland-hgs-service.html
  245.               Optional, repeatable
  246.  
  247. Contact ???
  248.  
  249. Currently under consideration is the addition of Expiry and Time
  250. to live information; and its position relative to similar information
  251. already passed in the HTTP request.
  252.  
  253.  
  254. Directory Information
  255. ---------------------------
  256.  
  257. A server then presents  the entries in the directory held at that
  258. site, separated by a blank line.
  259.  
  260. The content of each entry in the directory  for the given
  261. collection node is as follows; each item is encoded using colon
  262. separated RFC822 field value pairs.
  263.  
  264.  
  265.  
  266. Version       The HGS protocol version, major and minor
  267.               version number. Changes in minor version number are
  268.               expected to be backward and forward compatible (at a
  269.               possible loss of functionality).
  270.  
  271.               Example: 1.00
  272.               Mandatory, non-repeatable
  273.  
  274. Name          The name of the service or the collection. Clients
  275.               must be able to cope with names of at least 70
  276.               symbols in length. However a client should be able
  277.               to handle strings of arbitrary length.
  278.  
  279.               Example: BRSC Bird sightings, by location, time and
  280.               stock migration
  281.               Mandatory, non-repeatable
  282.  
  283. Description   A short description of the service or data
  284.               collection. Clients must be able to cope with a
  285.               description of at least 4 kbyte in length.
  286.  
  287.               Example: Processed Field data collected by the BRSC
  288.                     service for the mainland of Germany, the Ems
  289.                     Estuary, the Waddensea and the Skylle. With
  290.                     confirmed sightings and ring identifier
  291.                     numbers.
  292.               Optional, non-repeatable
  293.  
  294. URI           A full URL to a more elaborate description of the
  295.               resource, collection and organization responsible for
  296.               the service pointed at by the 'URL'. Repeatable
  297.               entries are each to refer to pages which convey the
  298.               same information.
  299.  
  300.               Example: http://www.rbrc.org/field/desc.html
  301.               Optional, repeatable
  302.  
  303. DirectoryURI  The full URL pointing to another Advertise directory.
  304.           The presense of this variable indicated that this
  305.           resource is effectively a collection of resources
  306.           which can be broken into one or more resource sets.
  307.  
  308.               Example: http://www.rbgs.org/hgs.txt
  309.               Optional, repeatable
  310.  
  311. SearchURI     The full URL of  the search interface(s) Repeatable
  312.               entries are each to refer to pages which operate on
  313.               the same information space. 
  314.  
  315.           The presense of this entry indicates that this resource
  316.               is a searchable set.
  317.  
  318.               Example: http://fully.qualified.domain.name/cgi-
  319.               bin/hgs-search.pl
  320.               Mandatory, repeatable
  321.  
  322. ExplainURI    The full URL of an optional "Explain" resource. 
  323.  
  324.               Example: http://www.food.bar/explain.txt
  325.               Optional, repeatable
  326.  
  327. It is of importance that the 'DirectoryURI', 'SearchURI' and 'ExplainURI'
  328. are not mutually exclusive; but can be used in parallel. Most databases
  329. consists of logical datasets; and often the publisher whishes to make
  330. possible searches on both the entire dataset as well as on individual sets.
  331.  
  332. Currently under consideration is the addition of administrative
  333. information, such as a technical contact email address and date
  334. of last modification, expiry and time to live.
  335.  
  336.  
  337. Example: Service Information
  338. -------------------------------
  339.  
  340. Version: 1.00
  341. Name: Marine Environment Resources
  342.   Description: The Marine Environment Unit aims to develop,
  343.   demonstrate and validate methodologies for the use of data from
  344.   space and airborne Platforms in both operational applications and
  345.   scientific investigations related to the marine environment.
  346. URI: http://me-www.jrc.it
  347.  
  348. Example: Service Directory
  349. ---------------------------
  350.  
  351. Version: 1.00
  352. Name: CORSA / Ocean Colour European Archive Network
  353. Type: Searchable
  354. Description: The Ocean Colour European Archive Network (OCEAN)
  355.   Project, was established in 1990 as a co-operation between the
  356.   Joint Research Centre (JRC) of the European Commission (EC), with
  357.   the support of the EC Directorate General XI, and the European
  358. URI: http://me-www.jrc.it/OCEAN/ocean.html
  359. SearchURI: http://www.ceo.org/hgs/dbi.pl/corsa
  360.  
  361. Version: 1.00
  362. Name: CORSA / Cloud and Ocean Remote Sensing around Africa
  363. Description: The Cloud and Ocean Remote Sensing around Africa
  364.   (CORSA) project aims to provide a quality controlled data set of
  365.   surface, atmospheric and cloud parameters over a time period, and
  366.   at a resolution, not available from any other source. The proj
  367. URI: http://me-www.jrc.it/CORSA/index.html
  368. SearchURI: http://www.ceo.org/hgs/dbi.pl/ocean
  369.  
  370. Version: 1.00
  371. Name: AVHRR Seachable HGS Resources
  372. Description: A locall held list of searchable AVHRR resources 
  373. relevant to the CORSA Project of the Marine Environment Unit
  374. URI: http://me-www.jrc.it/CORSA/AVHRR.html
  375. DirectoryURI: SetURI: http://me-www.jrc.it/CORSA/AVHRR/hgs.txt
  376.  
  377.  
  378. Higher Levels
  379. =============
  380.  
  381. 'Search' queries are to use standard HTTP GET and
  382. POST requests; conveying values using the CGI/1.0 standard.
  383.  
  384. A number of field/value pairs in the request is defined for
  385. all requests. The standard HTTP Accept-type, encoding and
  386. language specifications are to be followed.
  387.  
  388.  
  389. UserAgent    The requesting user agent; string followed by a version
  390.         number.
  391.  
  392.         Example: GeoSpava 1.00 (Sol 2.4/X11)
  393.         Mandatory, non-repeatable
  394.  
  395. Version        Version of the request protocol used,
  396.  
  397.         Example: 1.00
  398.         Mandatory, non-repeatable
  399.  
  400. Upgrade        Client side request to upgrade to a different
  401.         protocol version.
  402.  
  403.         Example: 1.02
  404.         Optional, non-repeatable
  405.  
  406. The reply of the server is governed by the normal HTTP protocol
  407. and status codes. It is stressed that HTTP/1.1 already allows 
  408. for caching, proxying and access authorization. If the Content-type
  409. of the reply is set to text/x-hgs; the reply is to be in rfc822
  410. colon separated field/value pair format.
  411.  
  412. The following field/value pairs have a meaning across all levels:
  413.  
  414. Version       Version of the protocol used by the server when
  415.               sending out the reply. Changes in minor version
  416.               number are to be both backward and forward
  417.               compatible; whereas major version are used to denote
  418.               an incompatible change. A server should upgrade, if
  419.           the client has send a supported 'Upgrade' version. 
  420.  
  421.               Example: 1.00
  422.               Mandatory, Non repeatable
  423.  
  424. Engine        Software used to carry out the request; name,
  425.               followed by a version number. (see http spec for
  426.               this, copy that bit) A server should support this.
  427.  
  428.               Example; HGSGeoTem 0.01beta
  429.               Optional, Non-repeatable
  430.  
  431. Upgrade       Version number of a higher level protocol, for which
  432.               the server is capable of handling requests. A client
  433.           can, if desired upgrade to this protocol level.
  434.  
  435.               Example: 1.09
  436.               Optional, Non-repeatable
  437.  
  438. Comment       A message, optionally displayed to the user
  439.  
  440.               Example: Your search on the blabla returned 5 hits.
  441.               Optional, repeatable
  442.  
  443. Error         An error occured. The field value is intended for
  444.               the end user.
  445.  
  446.  
  447. Standard Search Request
  448. =======================
  449.  
  450. Up to three  search criteria can be imposed upon a search during
  451. the request. In the reply the server indicates which of these
  452. conditions was applied. A server, or the properties of the dataset
  453. searched, might not support any, one or more of the limitations.
  454. In this case the search is to continue as if that limitation was
  455. not applied. The server MUST be able to cope with a client
  456. breaking the connection when the number of records returned exceed
  457. the clients resources.
  458.  
  459. In the most extreme case, when the user agent does not specify any
  460. criteria, or when the server cannot apply any of the criteria,
  461. all records are to be returned.
  462.  
  463. As the search request is a one-off stateless interaction;
  464. discrepancies and inaccurate matching, conversions and comparisons
  465. are to be expected. For this reason the three search criteria are
  466. intentionally in-exact. This allows the server to return possibly
  467. false positives, and it puts some of the burden for detecting this
  468. upon the user-agent and the final user.  Unlike the more machine-
  469. oriented exchange of the 'Explain' request, Human pattern recognition
  470. and iterative refining is relied on. The user-agent application is
  471. to be designed with such interaction in mind.
  472.  
  473. Type definition of criteria
  474. ---------------------------
  475.  
  476. Three datatypes are in use at the level-1 queries; for geospatial
  477. coordinates, for time specifications and for partial substrings.
  478.  
  479. Servers and Clients must be able to handle floating point numbers
  480. which have the fractional and integral part separated by a period 
  481. as well as a comma, regardless of the local and/or language/charset
  482. and encoding triple specified by HTTP. 
  483.  
  484. Servers and Clients must use the following format for all floating
  485. point numbers, regardless of the Locale.
  486.  
  487.     digit     = <0|1|2|3|4|5|6|7|8|9>
  488.     digits     = < digit [digits] >
  489.     E    = 'E'
  490.     sep    = < . >
  491.     sign     = <+ | ->
  492.     float     = <[sign] digits [ sep [ digits ]] [ E [sign] <digits> ] >
  493.  
  494. In particular, no separation on the powers of thousand
  495. is allowed; such as 10,000.00 .
  496.  
  497. Geospatial Coordinates (GC)
  498. ---------------------------
  499.  
  500. The format for the Geospatial coordinate is as defined in the FGDC 1994
  501. standard Content Standards for Digital Geospatial Metadata, with the 
  502. exception of the length of the integral part of the latitude of longitude 
  503. ( two or three digits).
  504.  
  505. Values for latitude and longitude shall be expressed as decimal
  506. fractions of degrees.  Whole degrees of latitude shall be represented
  507. by a two-digit decimal number ranging from 0 through 90.  Whole degrees
  508. of longitude shall be represented by a decimal number
  509. ranging from 0 through 180.  When a decimal fraction of a degree is
  510. specified, it shall be separated from the whole number of degrees by a
  511. decimal point.  Decimal fractions of a degree may be expressed to the
  512. precision desired.
  513.  
  514. Latitudes north of the equator shall be specified by a plus sign (+),
  515. or by the absence of a minus sign (-), preceding the 
  516. designating degrees.  Latitudes south of the Equator shall be
  517. designated by a minus sign (-) preceding the two digits designating
  518. degrees.  A point on the Equator shall be assigned to the Northern
  519. Hemisphere.
  520.  
  521. Longitudes east of the prime meridian shall be specified by a plus sign
  522. (+), or by the Longitudes west of the meridian shall be designated by
  523. minus sign (-) preceding the digits designating degrees.  A point
  524. on the prime meridian shall be assigned to the Eastern Hemisphere.  A
  525. point on the 180th meridian shall be assigned to the Western
  526. Hemisphere.  One exception to this last convention is permitted.  For
  527. the special condition of describing a band of latitude around the
  528. earth, the East Bounding Coordinate data element shall be assigned the
  529. value +180 (180) degrees.
  530.  
  531. Any spatial address with a latitude of +90 (90) or -90 degrees will
  532. specify the position at the North or South Pole, respectively.  The
  533. component for longitude may have any legal value.
  534.  
  535. With the exception of the special condition described above, this form
  536. is specified in Department of Commerce, 1986, Representation of
  537. geographic point locations for information interchange (Federal
  538. Information Processing Standard 70-1):  Washington,  Department of
  539. Commerce, National Institute of Standards and Technology.
  540.  
  541. Servers and Clients must be able to handle floating point numbers
  542. which have the fractional and integral part separated by a period 
  543. as well as comma, regardless of the locale and/or language/charset
  544. and encoding triple specified by HTTP. 
  545.  
  546. Servers and Clients must use the specified float format for
  547. all latitude and longitude formats.
  548.  
  549. Temporal Dimension (JF)
  550. ---------------------------
  551.  
  552. The temporal dimension is either as defined per rfc1123, as a Julian
  553. date or relative in days. A relative day and a Julian date is expresses
  554. as a Floating point number of arbitrary accuracy denoting the number of
  555. days before (negative), or after (positive) the 14th of September 1752 
  556. (for julian days), or the number of days before or after the current day,
  557. i.e. the day the query was dispatched. Relative and Julian days have
  558. a 'R' and a 'J' prefix. This prefix is not case sensitive.
  559.  
  560. Examples:
  561.  
  562.     J 0
  563.     R -5.62E+8 (1.5 Million years ago)
  564.         R -1 ( Yesterday )
  565.         Wed, 02 Apr 1997 17:06:40 GMT
  566.  
  567. When the rfc1123 format is used, the zone should be UT or GMT, and 
  568. the date-name is optional. Please note that rfc1123 specifies a four 
  569. digit year (unlike rfc822).
  570.  
  571. Search Sub String (SS)
  572. ---------------------------
  573.  
  574. A partial search string, in the appropriate language and charset
  575. as specified on the HTTP transport level.
  576.  
  577. The criteria names are not case sensitive. 
  578.  
  579. Spatial Limit
  580. -------------
  581.  
  582. A spatial limit can be imposed on the records returned. In this
  583. case each of the returned records must be partially within the
  584. specified bounding box. The server may only apply this limitation
  585. to records with which a spatial domain can be associated. For each
  586. of the records to which spatial limitation was imposed, the
  587. spatial coverage associated with the record should be returned;
  588. thus allowing the user-agent to do subsequent processing.  It is
  589. proposed that rectangles are defined in simple lat/lon co-
  590. ordinates, with up to a tenth of a degree accuracy.
  591.  
  592.     latmin   GC  the resource(s) returned are to cover a
  593.                  latitude equal or larger than
  594.                  the latmin specified.
  595.     latmax   GC  the resource(s) returned are to cover a
  596.                  latitude equal or smaller than
  597.                  the latmax specified
  598.     lonmax   GC  the resource(s) returned are to cover a
  599.                  longitude equal or larger than
  600.                  the lonmin specified
  601.     lonmax   GC  the resource(s) returned are to cover a
  602.                  longitude equal or smaller than
  603.                  the lonmax specified
  604.  
  605.     Each of the above is optional and non-repeatable.
  606.  
  607. Absent values, for any of the above fields are to be treated as
  608. not-limiting in any way. Consequently if all values are absent, no
  609. spatial limit is to be applied at all.
  610.  
  611.  
  612. Temporal Limit
  613. --------------
  614.  
  615. Time intervals are a pair of dates or Julian day numbers which define 
  616. a temporal search interval. The server must be able to handle these
  617. numbers up to a tenth of day accuracy. The client must be able to
  618. cope with a search applied with less accuracy than specified in
  619. the request. The implementation on the server must be designed
  620. with this in-accuracy in mind; possibly at the expense of
  621. returning false positives.
  622.  
  623. There are three criteria specifying date searching; please note
  624. that, insofar as the service is concerned, the timespan associated
  625. with a resource can effectively be a single point in time.
  626.  
  627.     date_after    JF  (part of) the timespan of the returned
  628.                       records is after the date specified
  629.     date_before   JF  (part of) the timespan of the returned
  630.                       records is before the date specified
  631.     date_on       JF  The date_on is within the timespan of the
  632.                       returned records
  633.  
  634. This allows search of  the types on-a-date, before-a-date, after-a-
  635. date and any combination; thus making ranges and partial ranges
  636. possible. In particular the server should must make no assumptions
  637. on which, or what combination of these three specifiers is
  638. requested.
  639.  
  640. Free text limit
  641. ---------------------------
  642.  
  643. Additionally a search string can specify one or  more partial
  644. substrings to be matched upon. This option is repeatable and non-
  645. mandatory. Repeatable entries are to be used in parallel; i.e. a
  646. record has to relate to, or contain one or more of the substrings
  647. specified by the user agent.
  648.  
  649.     text    SS    Partial string.
  650.             optional, repeatable
  651.  
  652. Standard http get and post requests will be supported. 
  653.  
  654.  
  655. Request procedure
  656. ---------------------------
  657.  
  658.  
  659. A)  HTTP get.  Example
  660.  
  661.     http://hgs.ceo.org/cgi/search.pl?latmin=-30&lonmin=30&
  662.         latmax=-40&lonmax=40&date_on=27585.1203&Text=Geology&
  663.         UserAgent=DraftEx+1.00
  664.  
  665. B)  HTTP Post. Example
  666.  
  667.     <form method='post' action=' hgs.ceo.org/cgi/search.pl'>
  668.     <input name='UserAgent' value='DraftEx 1.00'>
  669.     <input name='Version' value='1.00'>
  670.     <input name='text' value='Geology'>
  671.     <input name='latmin' value='-39'>
  672.     <input name='latmax' value='30'>
  673.     <input name='lonmin' value='-40'>
  674.     <input name='lonmax' value='40'>
  675.     <input name='date_on' value='27585.1203'>
  676.     <input type='submit'>
  677.     </form>
  678.  
  679. C)  HTTP Reply
  680.  
  681. Status of the reply is either 200, for results follow, or 404,
  682. for nothing found, depending on the success of the search. All
  683. other headers, as described in rfc2068, have their normal 
  684. meaning. In particular a 401 reply might cause the UserAgent
  685. to prompt for a username and password.
  686.  
  687. Replies such as 500 indicate a failure. The Normal MIME rules
  688. for labeling the reply apply. The returned content type is
  689. either text/html, text/plain, or text/x-hgs. Only the latter is
  690. intended for machine parsing. Replies in html or plain text should
  691. be forwarded to the user directly.
  692.  
  693. The content of the reply consist of a header and a set of entries;
  694. each separated by a blank line. Each line contains a field value
  695. pair, in a RFC822 colon separated encoding. Field names are not
  696. case sensitive.
  697.  
  698.  
  699. Header Fields
  700. ---------------------------
  701.  
  702. A number of header fields are mandatory; a few are optional;
  703. primarily for user interface purposes. In addition to the normal 
  704. reply headers; the following field/value pairs are 'Search'
  705. request type specific.
  706.  
  707. Applied       List of search criteria which where applied
  708.               successfully. Space separated, case in-sensitive.
  709.  
  710.               Example: latmin latmax date_on
  711.               Mandatory, non repeatable
  712.  
  713. Name          Short, Symbolic name for the dataset(s) or systems
  714.               searched; often the same as the value of the 'Name' 
  715.               field in the directory advert. Allows the user-agent
  716.               to distinctly mark the results from a query when
  717.               results from more than one HGS interface are collated.
  718.  
  719.               This field has in particular value for searched across
  720.               multiple interfaces; without the context of the directory
  721.               advert.
  722.  
  723.               Example: CORSA
  724.               Optional, non-repeatable
  725.     
  726. [--- back pointers to directory advert              ----]
  727. [--- kind of impossible due to many2many relation   ----]
  728. [--- perhaps just the URI/Description/Name info ?   ----]
  729.  
  730. EntriesExpected
  731.               A, possible not correct, number of entries
  732.               likely to be returned by the server. A server should
  733.               try to ensure that this number is accurate. But the
  734.               client must not depend on this number to be correct.
  735.               It must not be used as an upper limit.
  736.  
  737.               Example: 5
  738.               Optional, non-repeatable
  739.  
  740.  
  741. Example of a full header;
  742.  
  743.     Version:         hgs/1.00
  744.     Engine:              GeoLite 0.01a
  745.     Applied:         text latmin latmax lonmin lonmax ton
  746.     EntriesExpected:       5
  747.     Comment:         Your search on the RCS database yielded 5 entries
  748.  
  749.  
  750. Record Entries,
  751. ---------------------------
  752.  
  753. Record entries again follow the rfc822 colon separated field value
  754. format; and are separated by a blank line. A server which is able
  755. to apply a spatial or temporal limit should (or must?) confirm the
  756. coverage of the records returned for at least those criteria
  757. specified in the original search; with as much accuracy as
  758. possible.
  759.  
  760. URI         Universal resource identifier; such as a URN or a URL.
  761.  
  762.             Example: http://server.company.org/cgibin/show.pl?1e441aef
  763.             Mandatory, Non-repeatable
  764.  
  765. Name        Short descriptive name
  766.  
  767.             Example: Wetlands Survey 1996, Alabama
  768.             Optional, non-repeatable
  769.  
  770. Description       Short description of the record, clients must be
  771.                   able to cope with up to 4k and ..
  772.  
  773.             Example: Someblurp on etc, from the gcmd
  774.             Optional, non-repeatable
  775.  
  776. Coverage     Spatial area related to the resource, 2 or 4 space
  777.              separated GC, with as much accuracy as possible. A server
  778.              should supply this; especially when it was able to
  779.              effectuate one or more spatial criteria. If the entry is
  780.              repeated, each of the sets should fit the criteria
  781.              applied. An absent or criteria is denoted by a '*',
  782.              asterisk.
  783.  
  784.             Example: 12 33 33 44
  785.             Optional, repeatable
  786.  
  787. OtherCoverage   Any spatial coverage related to the resource, not
  788.         relayed in the Coverage field
  789.  
  790.             Example: 12,33 33,44
  791.             Optional, repeatable
  792.  
  793. Period       Temporal  range or point related to the resource, 1 or 2
  794.              space separated JF, with as much accuracy as possible. A
  795.              server should supply this; especially when it was able to
  796.              effectuate one or more temporal criteria. If the field is
  797.              replated; each of the repeated entries should fulfill the
  798.              criteria applied.
  799.  
  800.              Example:  1112.33 1198.11
  801.             Optional, repeatable
  802.  
  803. OtherPeriod ??  Any temporal ranges or points not relayed in the
  804.         Period field.
  805.  
  806.                Example: 12,33 33,44
  807.             Optional, repeatable
  808.  
  809. Example;
  810.     
  811.     Name:        Wetlands in eastern Alabama
  812.     URI:         http://ala.www.edu/sand.html
  813.     Coverage:    12.33 13.44 44.12 34.23
  814.     Period:      123.34 125.12
  815.  
  816.  
  817. 'Explain' Resource
  818. =================
  819.  
  820. The 'Explain' is an optional object description level for a given
  821. server. It allows a server to define an ordered list of locally
  822. defined searchable object types and their associated attributes.
  823. It is advertised via a uri resource "ExplainURI" at the directory
  824. level. The Explain service is optional, and the search server may 
  825. ignore it. It then must send back an http error such as "not supported".
  826.  
  827. Thus Explain allows customisable local attributes to be defined.
  828. Using this configuration information the  client software can
  829. therefore configure the search interface accordingly.
  830.  
  831. The actual attribute ID numbers used, should be standardised up
  832. to a certain extend; especially in user communities with similar
  833. database schema's. More work will be done in this area.
  834.  
  835. The format is best illustrated in the following example
  836.  
  837.    Version: 1.00
  838.    Name: Advanced Interface to the SatCom data site
  839.  
  840.    Version: 1.00
  841.    SearchURI: http://www.ceo.org/hgs/serverside_examples/ISIS.pl
  842.    Name: OCEAN Data/Product selection(s)
  843.  
  844.    Id: 100
  845.    Name: DALI Dataset name
  846.    URI: http://www.dali.fr/guide/datasets.html
  847.  
  848.    Id: 200
  849.    Name: COLOUR (Multispectral)
  850.    Mother: 100
  851.    URI: http://www.dali.fr/guide/datasets.html#MSPT
  852.  
  853.    Id: 201
  854.    Name: BLACK and WHITE (Panchromatic) 
  855.    Mother: 100
  856.    URI: http://www.dali.fr/guide/datasets.html#PAN
  857.  
  858. In the above example a search for 100=200 would mean a search for
  859. the dataset type set to 'Multispectral'. Whereas a search for
  860. 100=200&100=201 would imply a search across both datasets. 
  861.  
  862. Another example is depicted below; it concerns a dataset with several
  863. classes of cloud coverage as well as a second dimension concerning the
  864. type of pass the satallite made.
  865.  
  866.    Version: 1.00
  867.    Name: Cloud Coverage DBMA
  868.  
  869.    Version: 1.00
  870.    SearchURI: http://www.ceo.org/hgs/serverside_examples/PPY.pl
  871.    Name: OCEAN Data/Product selection(s)
  872.  
  873.    Id: 100
  874.    Name: Cloud Cover
  875.    URI: http://www.dali.fr/guide/coverdef.html
  876.  
  877.    Id: 200
  878.    Name: below 10%
  879.    Mother: 100
  880.    URI: http://www.dali.fr/guide/clouds.html#scale
  881.  
  882.    Id: 210
  883.    Name: below 10%
  884.    Mother: 100
  885.    URI: http://www.dali.fr/guide/clouds.html#scale
  886.  
  887.    Id: 220
  888.    Name: 10% .. 30%
  889.    Mother: 100
  890.    URI: http://www.dali.fr/guide/clouds.html#scale
  891.  
  892.    Id: 220
  893.    Name: 30 ..60%
  894.    Mother: 100
  895.    URI: http://www.dali.fr/guide/clouds.html#scale
  896.  
  897.    Id: 220
  898.    Name: 60% and more
  899.    Mother: 100
  900.    URI: http://www.dali.fr/guide/clouds.html#scale
  901.  
  902.    Id: 300
  903.    Name: Pass Type
  904.    URI: http://www.dali.fr/guide/path.html
  905.  
  906.    Id: 301
  907.    Name: Ascending Pass
  908.    URI: http://www.dali.fr/guide/path.html#ASC
  909.    Mother: 300
  910.  
  911.    Id: 302
  912.    Name: Descending Pass
  913.    URI: http://www.dali.fr/guide/path.html#DEC
  914.    Mother: 300
  915.  
  916.  
  917.  
  918.  
  919. Customised searching
  920. ==============================
  921.  
  922. Upon receipt of 'Explain' configuration data, the client interface
  923. should be configured dynamically,  for example by use of pull
  924. down menus. The interface should allow users to select one or more
  925. object types. These will then be used for subsequent level 1
  926. searches to that server.
  927.  
  928. The selected object types will be appended to a level 1 search.
  929.  
  930. GET
  931.     http://hgs.ceo.org/cgi/search.pl?latmin=-30&lonmin=30&latmax=-
  932.     40&lonmax=40&Ton=27585.1203&text=Geology&Object=101,104,106&
  933.     Version=1.00&UserAgent=JavaGot+1.00
  934.  
  935. POST
  936.  
  937. <Object=101>
  938. <Object=104>
  939. <Object=106>
  940.  
  941.    Selected objects include all child objects.
  942.    Servers not supporting level 2 ignore all Object definitions.
  943.  
  944.  
  945. Implementations
  946. ===============
  947.  
  948. An HGS interface to a database will be implemented using CGI
  949. scripts. These can be expected to be similar and developed using a
  950. standard stub. Existing Web gateways to databases are unaffected.
  951. All that is required is an add on CGI gateway which supports HGS.
  952.  
  953. Multiple server searching at level 1 will be  possible. Thus a
  954. distributed search can be made by the client across several
  955. servers contained within a given server directory. In this case
  956. result collation at the client side is necessary.
  957.  
  958. The level 0 reply typically consists of a simple text file in
  959. a directory 'hgs' under the server root and/or AliasMapping 
  960. directives in the server setup
  961.  
  962. Scalability
  963. ===========
  964.  
  965. Issues of scale are not addressed, in particular broad searches
  966. yeilding thousands of hits are potentially possible; and will 
  967. be a pose a serious challenge for User Agent implementors. More work
  968. will be done in this area.
  969.  
  970. However it is stressed that; because of the mandatory use of complete
  971. URLs on all levels; query interfaces can be distributed; even in
  972. one collection. Furthermore support for mirroring, caching and duplication
  973. of services is potentially avaible; but as 'a client can do what it whats'
  974. it is as yet unclear how to effectuate.
  975.    
  976. Security Implications
  977. =====================
  978.     
  979. Security implications are not address; nor are they well understood.
  980. More work is to be done in this area.
  981.  
  982.  
  983. Acknowledgements
  984. ================
  985.  
  986. The development of HGS has benefitted from the work done by CEONet, Canada 
  987. and presentations at 1996 workshop organised by the CEOS (Commitee on 
  988. Earth Observation Satellites) WGISS (Working Group on Information Systems 
  989. and Services) WWW task team. Michael Kleih implemented and tested some 
  990. early client applications written in Java. Ladson Hayes provided remote 
  991. sensing specific information and proof-read this document. 
  992.  
  993. The work has been carried out in part for the Centre for Earth Observation,
  994. of Space Applications Institute by the Software Technologies and automation
  995. unit of the Institute for Systems, Informatics and Safety; both at the
  996. Joint Research Centre Ispra of the European Communities.
  997.  
  998.  
  999. Contacts
  1000. ========
  1001.  
  1002.     URL:         http://www.ceo.org/hgs/index.html
  1003.     Mailinglist:     hgs@harp.gsfc.nasa.gov (Majordomo)
  1004.  
  1005.     Clive Best               Clive.Best@jrc.it
  1006.     Dirk-Willem van Gulik      Dirk.vanGulik@jrc.it
  1007.  
  1008.     ISIS/STA/CEO - TP 270
  1009.     Joint Research Centre Ispra
  1010.     21020 Ispra (Va)
  1011.     Italy.
  1012.  
  1013.     Phone: +39 332 78 9549 or 5044    
  1014.     Fax: +39 332 78 9185
  1015.  
  1016.  
  1017.  
  1018. draft-vangulik-http-search-01.txt                       Expires: 23/01/1998    
  1019.