The Collection Input conformance class allows an OGC API collection, accessible using one or more OGC API data access mechanisms, to be specified as an input to a process. Specifically, the processing server acts as a client and fetches values from the OGC API collection using one of the available OGC API data access mechanisms and then feeds the fetched values as input values to the process being executed. The server from which input values are retrieved is referred to as the value source server.
Unless an implementation also conforms to the Remote Collections conformance class, only collections that are locally accessible in the current OGC API deployment are supported.
Unless an implementation also conforms to the Local Filtering conformance class, filtering of values retrived from an OGC API collection is performed by the value source server.
The following requirements describe how an execute requests references an OGC API collection and how an implementation requests data from that collection to use as input to a process.
The following requirements describe how to access data from an OGC API collection and the ability of an implementation to modify the accessed data by first applying filters, selecting a subset of fields or deriving new fields before providing the data as input to a process.
|
Note
|
The server may also do some intelligent remapping of parameters. For example, if a bbox parameter is specified in the execute request, but the value source server only supports the geometry parameter, the implementation may convert the bounding box to a 4-point polygon and map the specified bbox parameter to the geometry parameter supported by the value source server.
|
Parameter filter
A search or filter condition. This condition determines which resources from the OGC API collection are included in the result set and are thus passed as values to the corresponding process input. The filter parameter can be a string where the search condition is encoded in some text-based query langauge (e.g. cql2-text) or a CQL2 JSON object that encodes the search condition using JSON.
Parameter filterCrs
Asserts the CRS used for the coordinate values of the filter parameter. The default is WGS 84 or WGS 84h depending on whether ellispoidal jeight is included with the coordinates or not:
-
WGS 84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84)
-
WGS 84h longitude/latitude/ellipsoidal height (http://www.opengis.net/def/crs/OGC/0/CRS84h_
Parameter filterLang
Indicates the language used to encode a filter expression specified using the filter parameter. Query languages can include CQL2 text, CQL 2 JSON or OGC Filter Encoding (XML).
Parameter bbox
Only resources that have a geometry that intersects the bounding box are selected to be passed as input values to an executing process. If a resource has multiple spatial geometry properties, it is the decision of the value source server whether only a single spatial geometry property is used to determine the extent or all relevant geometries.
Parameter bboxCrs
Asserts the CRS used for the coordinate values of the bbox parameter. The default is WGS 84 or WGS84h depending on whether ellipsoidal height is included or not:
-
WGS 84 longitude/latitude [4 numbers] (http://www.opengis.net/def/crs/OGC/1.3/CRS84)
-
WGS 84h longitude/latitude/ellipsoidal height [6 numbers] (http://www.opengis.net/def/crs/OGC/0/CRS84h_
Parameter datetime
Either a date-time or an interval, half-bounded or bounded. Date and time expressions adhere to RFC 3339. Half-bounded intervals are expressed using double-dots. Only resources that have a temporal property that intersects the value of datetime are selected. If a resource has multiple temporal properties, it is the decision of the server whether only a single temporal property is used to determine the extent or all relevant temporal properties.
Parameter subset
Retrieve only part of the data by slicing or trimming along one or more axis. For trimming: {axisAbbrev}({low}:{high}) (preserves dimensionality). An asterisk (*) can be used instead of {low} or {high} to indicate the minimum/maximum value. For slicing: {axisAbbrev}({value}) (reduces dimensionality).
Parameter subsetCrs
Asserts the CRS used for the coordinate values of the subset parameter. The default is WGS 84 or WGS 84h depending on whether ellispoidal height in included with the coordinates or not:
-
WGS 84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84)
-
WGS 84h longitude/latitude/ellipsoidal height (http://www.opengis.net/def/crs/OGC/0/CRS84h_
Parameter geometry
Only resources that have a geometry that intersects the geometry specified using the geometry parameter are selected. The value of the geometry parameter can be specified using WKT or GeoJSON. If a resource has multiple spatial geometry properties, it is the decision of the server whether only a single spatial geometry property is used to determine the extent or all relevant geometries.
Parameter geometryCrs
Asserts the CRS used for the coordinate values of the geometry parameter. The default is WGS 84 or WGS84h depending on whether ellipsoidal height is included or not:
-
WGS 84 longitude/latitude (http://www.opengis.net/def/crs/OGC/1.3/CRS84)
-
WGS 84h longitude/latitude/ellipsoidal height (http://www.opengis.net/def/crs/OGC/0/CRS84h_
Parameter limit
The optional limit parameter limits the number of items that are presented in the response document. Only items are counted that are on the first level of the collection in the response document. Nested objects contained within the explicitly requested items shall not be counted.
Parameter ids
The optional ids parameter allows a specific list of resources, indicated by their identifiers, to be fetched from the OGC API collection. Only resources whose identifier matches one of the values listed for this parameter shall appear in the result set.
Parameter q
The optional q parameter supports keyword searching. Only resources whose text fields contain one or more of the specified search terms are selected. The specific set of text keys/fields/properties of a resource to which the q operator is applied is up to the discretion of the server. Implementations should, however, apply the q operator to the title, description and keywords keys/fields/properties if they exist in the resource.
Parameter assets
T.B.D. A list of STAC asset tags.
Parameter crs
If the parameter is specified, then the coordinates of all geometry-valued properties in a response document are in the requested CRS. Otherwise the coordinates are in the default CRS, that is http://www.opengis.net/def/crs/OGC/1.3/CRS84 for coordinates without height and http://www.opengis.net/def/crs/OGC/0/CRS84h for coordinates with ellipsoidal height.
Parameter properties
A filter that selects resource properties to be included in a response document. The elements in the properties parameter can be the names of resource properties, aliases for resources properties or synthetic properties. Synthetic properties are properties that are computed on the fly and can reference resource property names or aliases for resource properties.
Parameter aliases
A dictionary of aliases that can be used as values for the properties parameter. Aliases can be alternative names for resource properties or synthetic properties. Synthetic properties are named expressions that are computed at run-time. Expressions for synthetic properties are encoded using some expression language and can include references to resource property names or aliases for resource properties..
The passThroughParameters property is a dictionary of query parameters that are passed directly to the value source server. The keys used in this object should be identical to query parameters that the value source server recognizes.
In the case where the OAProc server supports local filtering, the passThroughParameters property provides a mechanism to force filtering to occur on the value source server.
The Remote Collections conformance class allows to reference a remote OGC API collection in addition to any local collections.
The following requirements describe how an execute request references a remote OGC API collection as a source of input values to a process.
The Collection Output conformance class specifies how clients can trigger the execution of a process as a result of requesting output data using OGC API data access mechanisms.
This provides an alternative to the synchronous and asynchronous execution mechanisms defined in this Standard for which spatial, temporal and other filtering prameters would need to be hardcoded in the execute request. When lengthy batch processing is not desirable, completely new execute requests each with different spatial, temporal and other filtering parameters and returning a partial output would need to be continuously be re-submitted.
This conformance class supports submitting an execute request once and then accessing the output using OGC API data access mechanisms in a manner that is completely agnostic of process execution.
Compared to separate execute requests, this mechanism makes it easier for implementations to optimize for scenarios where small partial outputs are streamed from the same pre-established processing pipeline. Parsing the execute request, validating inputs, and handshakes with remote components only needs to be performed once. An implementation could also preempt future requests based on past requests, offsetting the latency of a complex processing pipeline.
The following requirements describe an execution mechanism that triggers on-demand processing for particular spatial, temporal and other filtering parameters and results in one or more references to a collection description document that provides links to request output data using standard OGC API data access mechanisms.
This Standard does not impose any particular approach to materializing output collections resulting from a process execution request.
As described in Filtering, implementation of this Standard that support collection input rely on the value source server to perform any input data filtering specified in an execution request.
Servers that implement this conformance class, support local filtering in those instances where the value source server does not support the input data filtering requested in the execution request.