Skip to content
[WIP] OpenAPI for Coverages
Branch: master
Clone or download
cmheazel June 15 Update
Final review version prior to the hackathon
Latest commit af0f446 Jun 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
CIS+WCS-standards PB: added relevant background information Mar 23, 2019
core June 15 Update Jun 16, 2019
19-yyy.html re-publish draft Jun 14, 2019
19-yyy.pdf re-publish draft Jun 14, 2019
CONTRIBUTORS.md Additional cleanup Mar 5, 2019
DEVELOPMENT.md Additional cleanup Mar 5, 2019
LICENSE First file Mar 5, 2019
README.md Update README.md Apr 12, 2019
asciidoctor.json Create asciidoctor.json Jun 5, 2019

README.md

1 Introduction

This OGC API Coverages specification establishes how to access coverages as defined by the Coverage Implementation Schema (CIS) 1.1 through OpenAPI.

Current scope:

  • Only gridded coverages are addressed, not MultiPoint/Curve/Surface/SolidCoverages. Reason is that gridded coverages receive most attention today.
  • Only GeneralGridCoverage is addressed, other coverage types will follow later. Reason is to have a first version early which shows and allows to evaluate the principles.
  • Only coverage extraction functionality is considered, not general processing (as is provided with Web Coverage Service (WCS) extensions such as the Processing Extension). Exceptions from this rule are subsetting including band subsetting, scaling, and CRS conversion and data format encoding, given their practical relevance.
  • Subsetting is considered in the query component only for now. As typically all dimensions in a coverage are of same importance subsetting might not fit perfectly in the hierarchical nature of the path component. Further, subsetting may reference any axis and leave out any other, which makes positional parameters unsuitable. Nevertheless subsetting in the path component particularly limited to fixed subsets might be considered in a future version.

As such, the functionality provided below resembles OGC Web Coverage Service (WCS) 2.1 Interface Standard - Core.

2 Principles

OpenAPI establishes URL-based access patterns, as defined by RFC 3986 "Uniform Resource Identifier (URI): Generic Syntax", RFC 3987 "Internationalized Resource Identifiers (IRIs)", and RFC 6570 "URI Template" following a syntax like http://www.acme.com/path/to/resource/{id}{?query,parameters} whereby

  • /path/to/resource/{id} defines the local path to the resource to be retrieved on the node identified by the head part, http://www.acme.com.
  • the {?query,parameters} represent key/value pairs with further parameters passed to the request.

As a general rule,

  • accessing a coverage component is done in the path section,
  • subsetting is done in the query parameter section
  • format encoding is controlled via HTTP headers

As the coverage model normatively is given by the corresponding XML schema (JSON and RDF are built in sync with XML) specification of the OpenAPI access paths follows this schema. Note, though, that OWS Common, while normatively referenced in CIS, is not followed by OpenAPI, so here deviations will occur.

For path expressions abbreviations (i.e., aliases) may be defined for convenience.

3 OGC API Coverages Requests

This clause defines the basics of accessing OGC coverages via OpenAPI.

3.1 General

Requirement: A service offering OGC API Coverages access shall be accessible via an URL as service endpoint (subsequently referred to as Base URL).

Example: http://acme.com/oapi

Requirement: Coverage access paths, as defined in the next clause, are concatenated to the Base URL via a "/" character, followed (optionally) by a query part.

Example: http://acme.com/oapi/collections/{collectionid}/coverages/{coverageid}/rangeset

A request may be denied for server-specific reasons, such as quota.

3.2 Coverage Access Paths

In this clause, the path component of OGC API Coverages access is established.

Access paths follow the XML Schema of CIS in their structure.

To access coverage service constituents, such as formats supported, OGC 14-121 Web Query Service provides guidance, see https://github.com/opengeospatial/ogc_api_coverages/blob/master/CIS%2BWCS-standards/14-121_Web-Query-Service_2016-06-19.pdf .

3.3 Coverage Query Parameters

In this clause, the query component of OGC API Coverages access is established.

Subsetting parameters may be mixed in a query part, in no particular order.

3.3.1 Coverage Subsetting

Without any subsetting parameter the whole coverage extent is the target resource addressed. If a subsetting operation is provided then the coverage subset indicated is the target resource addressed.

Coverage subsetting is indicated through the SUBSET parameter name. The value following the "=" symbol is built as follows:

SubsetSpec:            SUBSET = axisName ( intervalOrPoint )
axisName:              {NCName}
intervalOrPoint:       interval | point
interval:              low :  high
low:                   point | *
high:                  point | *
point:                 {number} | " {text} "    //" = double quote = ASCII code 0x42

where {NCName} is an XML-style identifier not containing ":" (colon) characters, {number} is an integer or floating-point number, and {text} is some general ASCII text (such as a time and date notation in ISO 8601). A coverage access request may have any number of SUBSET parameters, however for each axis of the coverage at most one SUBSET parameter may be provided.

In case of an interval a trim operation is specified, with lower and upper bound. In case of a point a slicing operation is specified. For the detailed semantics of subsetting, trimming, and slicing see OGC WCS.

3.4 Coverage Encoding

Without any format encoding HTTP header (Accept and Accept-Encoding) a representation of the coverage in its Native Format will be returned. If an encoding HTTP header is provided then a representation of the coverage in the format indicated will be returned. The syntax for format encoding HTTP headers is defined in RFC 7231 "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content".

The format chosen must be able to represent the output of the request.

For the detailed semantics of format encoding see OGC WCS.

4 Examples

This section contains examples for coverage access, subsetting, and encoding. It assumes a service endpoint of http://acme.com/oapi/ .

4.1 Service Metadata

The first part is about service metadata. Currently this is wild speculation as it will mainly be defined through OGC API Common.

4.2 Coverage Finding

4.3 Coverage Access

The second part is about coverage access, which (as described earlier) is driven by the coverage structure and, hence, given:

4.4 Coverage Subsetting

The third part is about query parameters:

5 Open Issues

  • Establish service parameter access, based on OGC API Common
  • What is the output format of items typically returned as XML or JSON, such as DomainSet and RangeType? Should maybe FORMAT be applicable here as well? If so, should it be listed as a possible output format (which might be confusing)?
  • OGC 14-121 Web Query Service provides a definition of path syntax, but adds more functionality (such as selection predicates), all based on the XPath standard. Such extra functionality might come handy.
You can’t perform that action at this time.