Skip to content

clause_9_process-description.adoc

Latest commit

 

History

History
422 lines (318 loc) · 23.1 KB

clause_9_process-description.adoc

File metadata and controls

422 lines (318 loc) · 23.1 KB

Requirements Class "OGC Process Description"

The following section describes the OGC Process Description requirements class.

Overview

The OGC process description is an information model that may be used to specify the interface of a process. This model is an evolution of the process description model originally defined in the OGC WPS 2.0.2 Interface Standard but also includes elements of the OpenAPI Specification. Specifically, this process description languages uses JSON Schema fragments to define the input and output parameters of a process. As such, this process description provides a bridge from legacy implementations to using the OGC API Framework.

Note
 The use of other schema languages for describing the interface to a process is permitted but is outside the scope of this Standards. A description of how other schema languages would be used to describe the interface of a process would need to be described in a new conformance class added to this Standard or in a new Part of the OGC API - Processes suite of standards.

The process description allows the following information to be specified:

  • An identifier for the process

  • Descriptive metadata about the process:

    • A title

    • A narrative description of the process

    • Keywords that can be associated with the process

    • References to additional metadata

  • A description of each process input specified using a JSON Schema fragment.

  • A description of each process output specified using a JSON Schema fragment.

  • A job control specification that indicates whether the process can be invoked synchronously, asynchronously, or either.

  • An output transmission specification that indicates how the results of a process are retrieved; either by value or by reference

  • A section for additional parameters that are intended for communities of use to extend the process description as required.

The following clause defines a JSON-encoding of the OGC process description.

OGC process description

Schema for a process
link:../../openapi/schemas/processes-core/process.yaml[role=include]
Note
 This schema can also be obtained from process.yaml

(see also processSummary.yaml)

The schema imports the elements from the process summary and specifies an object for the definition of process inputs and another object for the definition of process outputs.

Describing a process input

Overview

Schema for describing a process input
link:../../openapi/schemas/processes-core/inputDescription.yaml[role=include]
Note
 This schema can also be obtained from inputDescription.yaml
Schema for the "dataClasses" parameter
link:../../openapi/schemas/processes-core/dataClasses.yaml[role=include]
Note
 This schema can also be obtained from dataClasses.yaml
Schema for the "dataAccessAPIs" parameter
link:../../openapi/schemas/processes-core/dataAccessAPIs.yaml[role=include]
Note
 This schema can also be obtained from dataAccessApis.yaml
Schema for the "executionUnitRequirements" parameter
link:../../openapi/schemas/processes-core/executionUnitRequirements.yaml[role=include]
Note
 This schema can also be obtained from executionUnitRequirements.yaml

(see also: descriptionType.yaml).

Data classes

One common input type that a process might accept is a feature collection indicating that the process will operate over the items of the collection. This implies that the process will have certain expections about the structure of the collection with regard to which properties the collection contains, their types, etc. In order to properly handle any arbitrary input collection a process would need to inspect the structure of the collection to ensure that all the expected properties with the expected schemas and semantics are present. To alleviate the server from having to perform such a tedious, and perhaps computationally expensive, validation step this Standard introduces the concept of the Data Class via the dataClasses parameter.

Two data resources tagged with the same data class URI value can be assumed to each contain all the properties defined by the data class. This equivalence allows a server to quickly validate that an input data resource meets the server’s expections in terms of the properties available for processing simply by comparing data class URI values. If the data class URI of the input data resource matches at least one of the data class URIs specified in the description of the process input (via the dataClasses parameter) then the server can assume that the process can operate on that data resource.

Note
 Care should be taken when tagging data resources with a data class URI. Both the schema and the semantics of each property in the data class must match the correspoding properties of the data resource. Consider two data resources that both contain fields a and b with the same data types but differ in, for example, units of measure. In this case, these two data resources should not be tagged with the same data class URI. While the schemas of a and b in the two data resources are the same, the semantics are clearly different.

The dataClasses parameter is an array allowing process inputs to be described that can handle a variety of data classes. As long as the data class URI associated with an input data resource matches at least one of the data class URIs listed in the dataClasses array the server can assume that the process can operate on that input data process.

The dataClasses parameter can also be used when describing process outputs and indicates that the generated output conforms to the schema requirements of the data class. This allows, for example, for a simple determination of whether the output of one process is suitable as an input to another process.

This clause started by introducing the concept of the Data Class in relation to a feature collection but the concept is a general one applying to any number of data resources such as feature collections, coverages, styles, etc. For example, a specific data class might be defined to include a geometry property fenceLine of type polygon. Thus, any input feature collection tagged with this data class’s URI can be expected to include a fenceLine property and its type can be assumed to be polygon. Similarly, a data class could be defined that identifies a set of bands in a coverage, say R, G, B and NIR. Any coverages tagged with this data class’s URI can thus be assumed to contain these bands. The Data Class concept is also independent of the particular encoding used for the data resource. So, applying data class validation applies equally to feature collections encoded as GeoJSON documents as it does to feature collections encodes as SHAPE files. Finally, the Data Class concept is independent of whether data resource values are passed to a process by-value or by-reference. In either case the server goes through the same procedure (i.e. comparing data class URIs) to determine whether a specific input value is suitable for processing as per the process description.

Note

  1. A data resource tagged with a specific data class will contain all the properties defined for that class but may also contain additional properties that are not members of the class. A process expecting an input value of a particular data class value would simply ignore these extraneous properties.

  2. A data resource can be tagged with more than one data class URI indicating that it satisfies all the requirements of all the data classes associated with the resource.

  3. In order for the Data Class concept to be most effective a registry akin to that found at Schema.org would need to be created and maintained. The OGC definition server is likely the best place to define and manage Data Class URIs.

Data access APIs

If a server supports collection input and/or collection output, the dataAccessAPIs parameters in the process description allows the server to indicate, on a per-input/output basis, which OGC API data access mechanism(s) are supported for providing input values to the process or retrieveing output values from the process.

Schema

The following JSON Schema fragment illustrates how to define an input that allows multiple types. In this case, the imageInput input can be one of a couple of image media types.

Input of multiple types example
"imageInput": {
  "schema": {
    "oneOf": [
      {
        "type": "string",
        "contentEncoding": "binary",
        "contentMediaType": "image/tiff; application=geotiff"
      },
      {
        "type": "string",
        "contentEncoding": "binary",
        "contentMediaType": "image/jp2"
      }
    ]
  }
}

Processes that perform geo-spatial processing can be expected to have geometric and feature input types. In JSON, geometries, features and collections of feature are commonly encoded using GeoJSON. Rather the requiring processes descriptions to embed or reference the full schemas for GeoJSON geometries, features or feature collections, this Standard defines a common set of convenience tokens that can be used instead.

The JSON Schema specification defines a set of values for the format key. This Standard extends this list by defining the following additional key values for use specifically in OGC process descriptions.

Table 1. Additional values for the JSON schema format key for OGC Process Description
Key value Short code Description

http://www.opengis.net/def/format/ogcapi-processes/0/geojson-feature-collection

geojson-feature-collection

Indicates that the value is an instance of a GeoJSON feature collection (featureCollectionGeoJSON.yaml).

http://www.opengis.net/def/format/ogcapi-processes/0/geojson-feature

geojson-feature

Indicates that the value is an instance of a GeoJSON feature (featureGeoJSON.yaml).

http://www.opengis.net/def/format/ogcapi-processes/0/geojson-geometry

geojson-geometry

Indicates that the value is an instance of a GeoJSON geometry (geometryGeoJSON.yaml).

http://www.opengis.net/def/format/ogcapi-processes/0/ogc-bbox

ogc-bbox

Indicates that the value is an instance of an OGC bounding box (bbox.yaml).

http://www.opengis.net/def/format/ogcapi-processes/0/epsg-code

epsg-code

Indicates that the string value is a code from the EPSG registry.

http://www.opengis.net/def/format/ogcapi-processes/0/wkt2-definition

wkt2-definition

Indicates that the string value is a well-known text representation of a coordinate reference system.

http://www.opengis.net/def/format/ogcapi-processes/0/cql2-text-filter

cql2-text

Indicates that the string value is a filter expression encoded using the text representation of the Common Query Language (CQL2).

http://www.opengis.net/def/format/ogcapi-processes/0/cql2-json-filter

cql2-json

Indicates that the string value is a filter expression encoded using the JSON representation of the Common Query Language (CQL2).

http://www.opengis.net/def/format/ogcapi-processes/0/collection-id

collection-id

Indicates that the string value is a collection identifier (e.g. a feature collection identifier).

http://www.opengis.net/def/format/ogcapi-processes/0/stac-collection

stac-collection

Indicates that the value is an instance of a STAC collection.

http://www.opengis.net/def/format/ogcapi-processes/0/stac-catalog

stac-catalog

Indicates that the value is an instance of a STAC catalog.

http://www.opengis.net/def/format/ogcapi-processes/0/stac-item-collection

stac-item-collection

Indicates that the value is a STAC ItemCollection.

http://www.opengis.net/def/format/ogcapi-processes/0/stac-item

stac-item

Indicates that the value is an instance of a STAC item.

http://www.opengis.net/def/format/ogcapi-processes/0/stac

stac

Indicates that the value is an instance of any of the STAC types listed above (i.e. one of stac-collection, stac-catalog, stac-item-collection, or stac-item).

http://www.opengis.net/def/format/ogcapi-processes/0/ogc-feature-collection

ogc-feature-collection

Indicates that the value is an instance of an OGC feature collection.

http://www.opengis.net/def/format/ogcapi-processes/0/ogc-coverage-collection

ogc-coverage-collection

Indicates that the value is an instance of an OGC coverage collection.

http://www.opengis.net/def/format/ogcapi-processes/0/directory

directory

Indicates that the string value is a directory path.

http://www.opengis.net/def/format/ogcapi-processes/0/file

file

Indicates that the string value is a file path.
Note
 This list of values has been submitted to the OGC Naming Authority for registration in their definition server.
Note
 Other encodings for geometric, feature and feature collection typed inputs/outpus are allowed but are not described in this Standard.

Situations might arise where communities of interest wish to extend this list of values for their own purposes.

The following JSON Schema fragment illustrates the use of the format key to include a semantic hint to a process input that is of a geometric type.

Example of semantic hints using the format key
"geometryInput": {
  "title": "Geometry input",
  "description": "This is an example of a geometry input.  In this case the geometry can be expressed as a GML of GeoJSON geometry.",
  "minOccurs": 2,
  "maxOccurs": 5,
  "schema": {
    "oneOf": [
      {
        "type": "string",
        "contentMediaType": "application/gml+xml; version=3.2",
        "contentSchema": "http://schemas.opengis.net/gml/3.2.1/geometryBasic2d.xsd"
      },
      {
        "format": "geojson-geometry"
      }
    ]
  }
}

Cardinality

Overview

The cardinality on an input is specified using the minOccurs and maxOccurs parameters from the input’s definition in the process description. The default values of minOccurs and maxOccurs are 1 indicating that a single input of the corresponding name must be specified in an execute request. The following table covers the various combinations of minOccurs and maxOccurs values.

Table 2. Cardinality rules for process inputs.
minOccurs maxOccurs Interpretation Example

0

0

Not Allowed

0

1

A single input value may be optionally specified.

"input": {value}

1

1

A single input value must be specified.

"input": {value}

1

N

At least 1 input value must be specified.
Regardless of the number of input values provided, those values must be encoded using an array.

"input": [{value}] OR
"input": [{value1},…​,{valueN}]

M

N

All values provided must be encoded using an array.

"input": [{value1},…​,{valueM}] OR
"input": [{value1},…​,{valueM},…​,{valueN}]
Note
 The tokens {value}, {value1}, {valueN} or {valueM} represent values of the type expected for the input according to its definition. This can include array values.
Interaction of minOccurs/maxOccurs and minItems/maxItems

The schema member of the input definition in the process description defines the schema of a single instance of an input. If the input happens to be an array then the minItems and maxItems properties may be used to define the limits of the array. The use of minItems and maxItems in the definition of the input does not affect how minOccurs and maxOccurs are interpreted and the same cardinality rules apply.

Consider the following definitions of an input named "input".

Table 3. Schema examples for cardinality
Example Schema Examples instances 
inputs:
  input:
    schema:
      type: array
      maxItems: 2
      items:
        type: string

In this case the schema of an input value is defined as an array and so will always be encoded as an array in an execute request.

 
"input": ["value1"]

or

"input": ["value1","value2"]
 
inputs:
  input:
    maxOccurs: 2
    schema:
      type: string

In this case, the schema of the input is defined as a plain string with a cardinality of 2. Inputs with cardinalities of greater than 1 are encoded as arrays in an execute request. This situation is equivalently encoded to the previous row.
Servers, however, being internally aware of the definition of each input, can disambiguate the input values accordingly (treating the values in this example as string values and the values in the above example as arrays of values).

 
"input": ["value1"]

or

"input": ["value1","value2"]
 
inputs:
  input:
    maxOccurs: 2
    schema:
      type: array
      maxItems: 2
      items:
        type: string

In this case we have an input with cardinality greater than 1 but that has values that themselves are defined as arrays. Since inputs with cardinality greater than 1 are encoded as arrays in an execute request, the result is that the inputs are encoded as arrays of arrays.

 
"input": [["value1"]]

or

"input": [["value1","value2"]]

or

"input": [["value1"],["value2"]]

or

"input": [["value1","value3"],["value2"]]

or

"input": [["value1"],["value2","value3"]]

or

"input": [["value1","value4"],["value2","value3"]]

Execution unit requirements

The executionUnitRequirements parameter is used to specify runtime requirements for the corresponding input. For example, if the input value needs to be locally staged for the execution unit then this requirement would be indicated using the executionUnitRequirements parameters.

Describing a process output

Overview

Schema for describing a process output
link:../../openapi/schemas/processes-core/outputDescription.yaml[role=include]
Note
 This schema can also be obtained from outputDescription.yaml

(see also: descriptionType.yaml).

Data classes parameter

T.B.D.

Data access APIs

T.B.D.

Example

The following URL is an example of retrieving a process description from the /processes/{processID} endpoint.

https://processing.example.org/processes/EchoProcess

The description of the example EchoProcess process might be:

link:../examples/json/ProcessDescription.json[role=include]

The EchoProcess process simply echoes each process input value it is given.
⚡