Understanding WPS parameter types

This page describes the type system of the WPS 1.0.0 specification and practices for definining process parameters with real-world types, such as GML geometries, GML feature collections and raster data.

1. The WPS type system

The actual flexibility and power of the WPS specification lies in the complex input and output parameter types and the ways to use them (inline or by reference). The deegree 3 WPS supports every variant that is definied in the WPS 1.0.0 specification. Please refer to the ParameterDemo example and the corresponding example requests. These demonstrate all variants of parameter types and executions (asynchronous, storing of documents, etc.)

The majority of the data structures outlined within the following sections are taken from the OGC WPS specification 1.0.0. You will find the corresponding schemas here: http://schemas.opengis.net/wps/1.0.0/http://schemas.opengis.net/wps/1.0.0/. The more general (from an OGG viewpoint) schemas are defined within the OWS Common specification (version 1.1), which you will also find online: http://schemas.opengis.net/ows/1.1.0/http://schemas.opengis.net/ows/1.1.0/

The WPS specification permits three different types of input and output parameters:

• Literal,

• BoundingBox,

• Complex.

Literal is used for simple input and output parameters with literal values, that are given as a simple string e.g. "red", "42", "highway 101" (no nested XML fragments or similarly complex inputs). A BoundingBox input and output specifies a certain bounding box given in a specified or a default CRS. The content of a complex input and output can be a complex XML structure as well as binary data (must be base64-encoded when given as an inline value).

In general, each input is defined by an input-element containing the description data structure as defined by:

• Identifier: an unambiguous identifier or name (ows:CodeType) of the title,

• Title: human readable title describing the process
• Abstract: a human readable description of the input

An example for a Input data structure:

...
<Input minOccurs="1" maxOccurs="1">
   <ows:Identifier>LiteralInput</ows:Identifier>
   <ows:Title>Example literal input </ows:Title>
   <ows:Abstract>This parameter specifies how long the execution of the process takes (the process sleeps for this time). May be specified in seconds or minutes.</ows:Abstract>
...
</Input>
...

Output data structures are very similar to input data structures, therefore detailed output examples are omitted.

The latter sections describe these parameter types and their usage in more detail.

1.1. Literal

A LiteralData indicates that the input or output is a simple literal value (e.g. an integer, a string, etc.). Within WPS a LiteralData is used conditionally. Other options are ComplexData and BoundingBoxData; LiteralData is the simplest option.

LiteralData may be used as an input parameter as well as an output parameter.

The LiteralInput, although it is as simple as a string or integer value, can be described by a LiteralInput data structure which is comprised of:

• DataType: an optional DataType as defined by ows:DataType.

• UOMs: An optional list containing the supported units of measure. This data structure should be included whenever a unit of measure corresponds to the specific data type (e.g. meter, seconds, etc.)

• LiteralValuesChoice: A mandatory data structure limiting the kind of parameters allowed (e.g. finite set of values and ranges or just the declaration that any kind of value is allowed here).

• DefaulValue: An optional string defining a default value for this LiteralInput.

The DataType element can reference an URN for a well-known data type; essentially, it is a string, but if linked to a URN, other datatypes (e.g. integers) might be specified and used for data parsing and validation.

Example DataType definition:

...
<ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#integer">integer</ows:DataType>
...

The UOM (= units of measure) data structure is comprised of two mandatory elements:

• Default: declaring the default unit of measure (only one unit).
• Supported: declaring the supported unit of measure. This element is handy if you need to declare alternatively supported UOM (e.g. the Default UOM is meter but you process also supports calculations based on centimeter and milimeter).

Example UOM paramter definition:

...
<UOMs>
   <Default>
      <ows:UOM>meter</ows:UOM>
   </Default>
   <Supported>
      <ows:UOM>feet</ows:UOM>
      <ows:UOM>centimeter</ows:UOM>
   </Supported>
</UOMs>
...

The LiteralValuesChoice data structure allows you to chose from either one of the elements:

• AllowedValues: indicates a finite set of values and ranges allowed for this input

• AnyValue: indicates, that any value is allowed here

• ValuesReference: like AllowedValues, this element indicates a finite set of values and ranges, but these are defined externally by reference.

An example for AllowedValues:

...
<ows:AllowedValues>
   <ows:Value>ServiceIdentification</ows:Value>
   <ows:Value>ServiceProvider</ows:Value>
   <ows:Value>OperationsMetadata</ows:Value>
   <ows:Value>Contents</ows:Value>
   <ows:Value>Filter_Capabilities</ows:Value>
   <ows:Value>All</ows:Value>
</ows:AllowedValues>
...

AnyValue as defined within the ows:AnyValue data structure declares that any kind of input is allowed within this element. An example for a request containing ows:AnyValue:

...
<LiteralData>
   <ows:DataType ows:reference="http://www.w3.org/TR/xmlschema-2/#double">double</ows:DataType>
      <ows:AnyValue />
   </ows:DataType>
</LiteralData>
...

ValuesReference is defined by a reference element (usually an URL) wich provides the ranges of allowed values. Additionally, this reference element is further described by a valuesForm describing the mimetype, encoding, and schema used for these values. The recent WPS specification lacks an example for requests based on ValuesReference.

1.2. BoundingBox

BoundingBox input data indicates that input is based on a BoundingBox data structure. It is more complex than literal data but less complex than complex data.

A BoundingBox data structure is comprised of:

• one Default-element: referencing the default coordinate reference system (CRS) of the bounding box
• one or more Supported-elements: referencing the supported CRSs

The CRS itself is declared as an URI type, e.g. EPSG:4326

An example input parameter definition for BoundingBox:

...
<Input minOccurs="1" maxOccurs="1">
  <ows:Identifier>BBOXInput</ows:Identifier>
  <ows:Title>BBOXInput</ows:Title>
  <BoundingBoxData>
    <Default>
      <CRS>EPSG:4326</CRS>
    </Default>
    <Supported>
      <CRS>EPSG:4326</CRS>
      <CRS>EPSG:31466</CRS>
      <CRS>EPSG:31467</CRS>
    </Supported>
  </BoundingBoxData>
</Input>
...

1.3. Complex

The complex data structure is presumably the most used data structure within WPS since it allows the transmitting and receiving data structures like GML or binary data. Complex data may be embedded inside a request/response (inline) or reside on a remote ressource (as reference). The ComplexData structure consists once again of a hierarchy of data structures. The top level data structure is comprised of:

• Default: Element declaring the default Format, Encoding, and Schema of the complex data.
• Supported: Element hosting one or more Format elements declaring the formats supported by a process.
• maximumMegabytes: An integer value declaring the maximum file size in megabytes for a specific input.

The Format data structure is comprised of the elements:

• MimeType: a ows:MimeType identifying the default format of a process input/output

• Encoding: an optional reference (URI) to a encoding
• Schema: an optional reference (URI) to a XML schema document. Note: this element shall be omitted when there is no XML Schema associated with this input/output.

The Supported data stracuture is used to describe the supported formats for inputs/outputs based on the Format data structure (incl. MimeType, Encoding and Schema).

Example input parameter definition containing one default and onde supported format:

...
<Input minOccurs="1" maxOccurs="1">
   <ows:Identifier>GMLInput</ows:Identifier>
   <ows:Title>GMLInput</ows:Title>
   <ComplexData>
      <Default>
         <Format>
            <MimeType>text/xml</MimeType>
            <Encoding>UTF-8</Encoding>
            <Schema>http://schemas.opengis.net/gml/3.1.1/base/gml.xsd</Schema>
         </Format>
      </Default>
      <Supported>
         <Format>
            <MimeType>text/xml</MimeType>
            <Encoding>UTF-8</Encoding>
            <Schema>http://schemas.opengis.net/gml/3.1.1/base/gml.xsd</Schema>
         </Format>
      </Supported>
   </ComplexData>
</Input>
...

2. Defining real-world geospatial parameter types in the WPS

Real-world geospatial systems are usually based on the processing of vector or raster data types. Obviously, the only WPS parameter type thats suited for representing these two data types is the Complex one. However, it's not so obvious how the signature of a complex WPS format (mime type, encoding, schema) should be chosen in order to precisely define that the expected payload is a vector or raster type.

2.1. Vector data: GML geometry

TBD

2.2. Vector data: GML feature / feature collection parameters

TBD

2.3. Vector data: Shapefile

TBD

2.4. Raster data

TBD

CategoryDeegree3