Skip to content

Latest commit

 

History

History
331 lines (252 loc) · 13.5 KB

clause_8_ogc-process-description.adoc

File metadata and controls

331 lines (252 loc) · 13.5 KB
Raw

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

Each process input is characterized by its schema, its cardinality and whether the input value can be passed by-value, by-reference or both.

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

(see also: descriptionType.yaml).

Schema

Note
 The schema fragment specified as the value of the schema parameter can be used to validate the corresponding process input value in an execute request.

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 for defining geometric, feature or feature collection inputs or outputs.

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 object 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 object 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 object 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 object is an instance of an OGC bounding box (bbox.yaml).
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"]]

Describing a process output

Schema for 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).

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.