SOAPifying WCS

SOAPifying WCS: Approach and Issues

Kari Hoijarvi, CAPITA, hoijarvi@me.wustl.edu

WCS Schema Components

The WCS schema is assembled from multiple components. The official schemas are copied into into the DataFed workspace http://datafed.net/xs/OGC/wcs/1.0.0/

describeCoverage.xsd
getCoverage.xsd
gml4wcs.xsd
owsBase.xsd
values.xsd
wcsCapabilities.xsd
wcsfix.xsd

Schema components gml4wcs.xsd, values.xsd and xlinks.xsd (from ../../gml/3.1.1/xlink/xlinks.xsd) were used as is, but the other schemas were not legal and had to be fixed.

Fixing the WCS Schema

Schemas use "import" instead of "include" from the same namespace. The rule is, that schemas with different namespaces must import and a namespace that is partitioned must be included. Therefore http://datafed.net/xs/OGC/wcs/1.0.0/wcsfix.xsd contains all the schemas from namespace http://www.opengis.net/wcs. In my opinion, xml schema include is a mistake and should not be used.

In wcsfix.xsd and owsBase.xsd had several things that .NET 1.1, .NET 2.0 and MSXML 6.0 did not consider legal. Due to complexity of the schema language, I do not know if the schemas were illegal or if they exposed bugs from Microsoft's validators. I have previously experienced both. These are tagged with comment 'FIX' in wcsfix.xsd

• wcsCapabilities had a problematic type AbstractDescriptionBaseType which was edited heavily. Again, I don't know if this was illegal or if the MS validator was unable to process it.
• wcsDescribecoverage was inserted as the were
• wcsGetCoverage has our extension FilterExtensionType which currently has only one element: loc_code to query point data for time view from a location. This cannot be implemented with bbox since locations may have the same lat+lon coordinates. WFS has a standard way to put in such a filter, but WCS does not. Here is an exaple of WFS service using loc_code filter and this is how our WCS query with loc_code looks. It would be a good idea to allow servers implement their own filter and aggregator extensions, just like WMS allows server specific parameters in the url.

WCS WSDL

The WCS web service is defined by its WSDL. The WSDL portType parts define service calls, message parts define their input and output types, and embedded schemas provide strong typing for input and output data.

All the schema components were combined into a single, 'fixed' WCS schema wcsfix.xsd. Next, the full wcsfix.xsd, as well as all the referenced schemas, were inserted into the WCS service WSDL. An outline of the WCS WSDL is pictured below.

Looking into nodes <message name="GetCapabilitiesIn">, you'll see that the input messages as well as the XML-based output messages are straight from wcs schema: input, output wcs:GetCapabilities, wcs:WCS_Capabilities wcs:DescribeCoverage, wcs:CoverageDescription wcs:GetCoverage, N/A

Create Output Type

The GetCoverage call is problematic, because WCS returns often binary types like NetCDF, GeoTIFF etc. We added the element dfc:GetCoverageResponse for output:

<xs:element name="GetCoverageResponse">
  <xs:complexType>
      <xs:all>
          <xs:element name="data" type="xs:anyURI"/>
          <xs:element name="content_type" type="xs:string"/>
          <xs:element name="format" type="xs:string"/>
          <xs:element name="domainSubset" type="wcs:DomainSubsetType"/>
          <xs:element ref="ncml:netcdf" minOccurs="0"/>
          <xs:element ref="lin:Statistics" minOccurs="0"/>
          <xs:element ref="lin:LineageList" minOccurs="0"/>
      </xs:all>
 </xs:complexType>
</xs:element>

Although it is possible to embed binary data to soap output using mime types or base64 encoding, we did not go that way. The output contains an url to data, so that it can be retrieved using HTTP-GET request. This also works around the SOAP limitation of max foure megabyte message size, which is too small for big queries. Http-get has no built-in upper limit. In addition to this pointer to data, the envelope has:

• content type: for example application/x-netcdf
• format: the format that was used to query this data, for example NetCDF
• domainSubset: space and time boundaries for data
• ncml:netcdf: ncML description of data, if the data is in NetCDF cube
• Statistics: min, max, avg, sum, total_count, null_count
• LineageList: Soap input Envelope that was used for the query, optionally
• other comments like the actual SQL clause that was performed, the actual
• URL that was retrieved, etc.

SOAP Envelope

To create SOAP out of xml (which xml?) is just matter of wrapping it into an envelope:

<Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">
  <Body>
      <GetCoverage ...
  </Body>
</Envelope>

Example SOAP Envelope

Summary

So in order to SOAPify WCS required:

• fixing some schemas
• including the combined fixed schemas in the WSDL
• creating output type in WSDL
• wraping xml into SOAP envelope

Realted Links

Link to an earlier WCS SOAP/WSDL page by Kari

Recommendation to GALEON by S. Nativi, L. Bigagli and P.Mazzetti, Feb 2006

• WCS bindings to HTTP GET/POST and SOAP should be consistent (this is a wellknown issue addressed in WCS 1.1).
• A standard description of the expected WCS SOAP interface (e.g a WCS wsdl) should be defined, to improve interoperability of SOAP-based WCS clients and servers. We would recommend SOAP service with literal encoding, due to parameters complexity using either RPC or Document style.

Early implementationof WCS SOAP wrapping at UFlorence/IMAA