Digital Earth Weblog

In Part 1 of this post I briefly detailed some reasons why I think the WMS GetFeatureInfo response format could be improved. In this post I will detail a response format and attempt to explain why it solves the problems listed in Part 1.

Proposed Response Format

Notes: This is just a draft, a straw man, not a final proposal or specification. It is intended for discussion purposes only. I’m looking for a simple solution that meets the majority of needs (90/10).

GetFeatureInfo Request

The proposed response format is a simple XML document, therefore the INFO_FORMAT parameter in the GetFeatureInfo request should have a value of “text/xml”.

Alan Doyle, in a comment on Part 1 of this post, has suggested the use of a Vendor Specific Parameter. The WMS 1.3 specification does not seem to provide an information on Vendor Specific Parameters, so I’ll suggest RESPONSE_SCHEMA=generic-1.0& to support versioning of the response schema. (Suggestions are welcome.)

Example Response Document

<?xml version="1.0" encoding="UTF-8"?>

<FeatureInfoResponse>
  <!— First layer from the requests QUERY_LAYER parameter.
  [Mandatory for each parameter value.]
  —>
  <Layer>
    <name>bores</name>
    <title>Water Bores</title>


  <!— One or more features may be returned per WMS layer.
  This allows for multiple features to be queried with a 
  single click.  
  —>

  <!— First queried feature in layer "bores". This is optional 
  because no features may exist in this layer near the users 
  click point. If a Feature element exists it must contain an
  id attribute. [Optional]
  —>
    <Feature id="1234">

  <!— A list of feature properties prepared for on 
  screen display.  Properties are expressed as 
  title/value pairs. Titles must be user readable,
  and should not be database column names. 
  Values containing quantities should include 
  units of measure. 
  [Mandatory within a Feature element.]
  —>
      <Properties>
        <Property>
          <title>ID</title>
          <value>1234</value>
        </Property>
        <Property>
          <title>Depth</title>
          <value>30.0 m</value>
        </Property>
      </Properties>

  <!— Links to alternate representations of this Feature
  or related resources. Links with a type of "text/html"
  should have a title attribute that contains a user readable
  title for the link. [Optional] 
  —>
      <link rel="related" type="text/html"
        href="http://somedomain/bore/report?id=1234"
        title="Salinity Report for Bore 1234"/>
      <link rel="alternate" type="application/vnd.ogc.gml"
        href="http://anotherdomain/bore?id=1234"/>
      <link rel="alternate" type="text/plain"
        href="http://anotherdomain/bore/text?id=1234"/>
    </Feature>

  <!— More than one Feature element is allowed per WMS layer. 
  [Optional] 
  —>
    <Feature>
      <!— See above elements —>
    </Feature>
  </Layer>

  <!— Second layer from the requests QUERY_LAYER parameter.
  [Mandatory for each parameter value.]
  —>
  <Layer>
    <name>salin_stat</name>
    <title>Watercourse Salinity Measuring Stations</title>
    <!— Extrapolate example content from above. —>
  </Layer>
</FeatureInfoResponse>

Download the example XML instance document.

Rationale

XML, not GML

XML was chosen as the response document encoding to allow the consuming application to have total control over the presentation of information. If you are building a Web application you should be able to use a single XSL stylesheet to display the GetFeatureInfo response in the layout and style that you require. You do not want the map server to give you a horizontal table containing serif 12pt text on a yellow background when you need a vertical table with 10pt sans serif text on a pale green background.

GUI applications can also reliably obtain data for on-screen display because the schema is generalised.

While the above instance document could be GML it doesn’t feel like it should be. In order to use a consistent schema there are no typed features, they are generic. (I am open to suggestions on the use of GML.)

Layers

One Layer element is present for each value in the QUERY_LAYER parameter. Each Layer is identified by its layer name and title (as per the associated Capabilities document). If the query returns no features on a particular layer then no Feature element will be present as a child of that Layer element.

Generic Features

Since the WMS specification does not use the concept of feature types the response document contains generic features. Clicking on a map image implies that you are querying the features in that map image. There are two assumptions:

1. Multiple features can be queried on a single map layer. This occurs when multiple features are within proximity of the user’s click point, or where overlapping polygons exist. (See also the FEATURE_COUNT parameter which can be used to restrict the “number of features per layer for which feature information shall be returned”.)
2. The map server allows “drill through” queries across multiple layers, and does not return only the first feature that matches the query.

Feature ID

Each Feature element must contain an “id” attribute (as per GML 2). That attribute must contain a unique feature identifier. It is useful when a registry contains a partial URI onto which the id value can be appended in order to create a URI to which the client application can redirect to obtain a related resource. For example:

Partial URI: http://somedomain/bore/report?id=
Feature id attribute value: 1234

URI of related resource: http://somedomain/bore/report?id=1234

Properties

Each Feature element contains a list of properties (a.k.a. attributes). The the list of properties are designed for on-screen display, most likely in a tabular format. Properties are expressed as title/value pairs.

Titles should be user readable, and should not be database column names. E.g. “Depth” instead of “br_depth”, or worse “schema.water_bores.depth_in_metres”. Values containing quantities should include units of measure. E.g. “30.0 m” instead of “30.0”.

Personally, I think that displaying database column names to users is poor form, but realise that changing this will require a significant amount of work in some map server implementations. Hence the use of “should” and not “must”.

Links

The current GetFeatureInfo query mechanism assumes that the map server can provide all the information you need about a particular feature. The Capabilities document tells you what the available GetFeatureInfo response formats are supported by the map server. These are available through the INFO_FORMAT parameter.

However, if alternate representations of a feature, or related resource representations, exist on another server the only way to get them is to use the mechanism described above using the feature id value. This relies on the client application knowing a partial URI onto which an id value can be appended. A client application would most likely get this from a registry.

Instead of using a registry to store one or more partial URIs the map server could use link elements to inform the client application of alternate feature representations and related resources. This removes the need to storing such information in a registry. Cool URIs don’t change but that is not always the case. Using hypermedia is the engine of state bypasses the need to maintain such registry entries.

The “rel” attribute should have a value of either “alternate” or “related”:

• alternate: an alternate representation of the feature the link element is contained within. E.g. a GML document containing geometry.
• related: an document related to the feature the link element is contained within. E.g. an HTML report describing sensor measurements provided by the feature.

The “type” attribute value is the expected MIME type of the resource identified by the links “href” attribute. This can be used to select which link to follow. If the value of the type attribute is “text/html” then the link should have a human readable value in the “title” attribute. This would be the text that is displayed to the user as a hyperlink.

Conclusion

There are many WMS compliant map servers installed. Expecting the developers of those map servers to upgrade them to support a non-standard GetFeatureInfo response format, and administrators of those map servers to install the upgrade, would be foolish. Much work has already been done to provide interoperability using the WMS standard’s GetFeatureInfo rules.

What I would like to see happen is some discussion around the idea of a standardised mandatory GetFeatureInfo response, and possibly consensus amongst map server developers on implementing it in the future.

Constructive criticism of this document is most welcome. If there is any interest I will create an XML schema for the above response format.

Update 2006-01-27: A new version of the proposed format has been posted.

[tags]WMS, interoperability, web services[/tags]