What is a Coverage?

The term "coverage" is defined in [[ISO19123]] as a "feature that acts as a function to return values from its range for any direct position within its spatial, temporal or spatiotemporal domain". In other words, a coverage maps points in space and time to data values. For example, an aerial photograph can be modelled as a coverage that maps positions on the ground to colours. A river gauge maps points in time to flow values. A weather forecast maps points in space and time to values of temperature, wind speed, humidity and so forth. The image below illustrates three different kinds of coverage: a gridded temperature field from a numerical simulation, a set of point measurements and a vertical profile.

Sometimes we see the word “coverage” used synonymously with “gridded data”, “raster data” or "imagery" but this isn’t really accurate. One can see from the above paragraph that non-gridded data (like a river gauge measurement) can also be modelled as coverages. Nevertheless, we often observe a bias toward gridded data in discussions (and software) that concern coverages.)

Existing Coverage representations

The [[ISO19123]] specification defines an abstract data model for representing the data and metadata needed to encode coverage data. This abstract model can be instantiated in many different concrete formats. The OGC Coverage Implementation Schema (CIS) specification ([[OGC-CIS]]) describes a concrete, directly instantiable data model and XML serialisation based on the Geography Markup Language (GML). Other serialisations have been defined, sometimes by retrospectively mapping existing binary data formats to the ISO19123 abstract data model (e.g. [[NetCDF]]). Version 1.1 of the CIS specification supports a JSON serialization, which is created through a direct translation from GML types to JSON objects. (We provide a brief comparison of CIS-JSON with CoverageJSON below.)

Motivation and objectives

This document describes the CoverageJSON format and explains how it is well-suited to representation of spatial data on the Web: with a number of advantages for use in a web context, in comparison to alternative established approaches for serialisation of coverage data. It is a good match to the Use Case Requirements [[SDW-UCR]] and Best Practices [[SDW-BP]] of the Spatial Data on the Web working group. It has been informed also by the Data on the Web Best Practices [[DWBP]]."

Serialisations (i.e. data formats) based upon community-specific binary formats and complex XML schemas provide usability challenges for the development of web applications. Javascript libraries do not always exist for these formats, and the formats are complex, requiring specialist knowledge on the part of the web developer. Our overall aim is to make it easier for web developers to consume coverage data in their applications, minimising the need for prior knowledge about community-specific data formats.

Therefore our objective in this work was to develop a well-structured, consistent and easy-to-use JSON format for coverage data that fulfils the following criteria:

• Able to encode many different kinds of coverage, including multidimensional grids, timeseries, vertical profiles, polygon-based coverages, point clouds and more.
• Able to encode both continuous-valued data (e.g. temperature) and categorical data (e.g. land cover classification).
• Able to encode geospatial data using a variety of coordinate reference systems.
• Able to encode both scalar data (e.g. temperature) and vector data (e.g. velocities).
• Able to encode data with quality information, e.g. numerical uncertainties and quality flags.
• Clear and readable, focusing on common practices in the JSON community.
• Use a minimal set of encoding rules, to avoid complicating the development of client code.

High-level structure

In CoverageJSON, a Coverage consists of the following objects:

• A Domain (exactly one), which encodes the set of points in space and time for which we have data values.
• A set of Range objects (one per scalar quantity), holding actual data values.
• A set of Parameter objects (one per scalar quantity), describing the data values.
• An optional set of ParameterGroup objects, which describe any semantic associations between Parameters.

A sample skeleton document encoding a three-dimensional gridded Coverage with two Parameters (sea surface temperature and sea ice area fraction) is shown here:

{
  "type" : "Coverage",
  "domain" : {
    "type": "Domain",
    "domainType" : "Grid",
    "axes" : {
      "x" : { /* Coordinate values */ },
      "y" : {                         },
      "t" : {                         }
    },
    "referencing" : [
      /* Coordinate referencing information */
    ]
  },
  "parameters" : {
    "SST"     : { /* Description of temperature values */ },
    "sea_ice" : { ... }
  },
  "ranges" : {
    "SST"     : { /* Encoding of temperature values, or link(s) */ },
    "sea_ice" : { ... }
  }
}
      

Encoding the Domain

A Domain is a collection of named orthogonal axes containing coordinate values, coupled with information about how to reference these values to one or more real-world coordinate reference systems. An axis can contain simple numeric values like latitudes or longitudes but can also contain composite values like tuples or polygons.

The following is a complete example of a simple grid domain with longitude, latitude, and time axes, using the WGS84 longitude-latitude coordinate reference system and the Gregorian calendar:

{
  "type" : "Domain",
  "domainType" : "Grid",
  "axes": {
    "x" : { "start": -179.5, "stop": 179.5, "num": 360 },
    "y" : { "start": 89.5, "stop": -89.5, "num": 180 },
    "t" : { "values": ["2001", "2002", "2003"] }
  },
  "referencing": [{
    "coordinates": ["x","y"],
    "system": {
      "type": "GeographicCRS",
      "id": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
    }
  }, {
    "coordinates": ["t"],
    "system": {
      "type": "TemporalRS",
      "calendar": "Gregorian"
    }
  }]
}
      

Note that different CRSs can be associated with different combinations of axes, providing a very flexible model that allows complex data to be encoded without the need to create composite CRSs. Axis values can also be categorical in nature (instead of numeric), enabling data values to be associated with entities that are not spatiotemporal coordinates.

This closely mirrors the structure of the RDF Data Cube Vocabulary [[VOCAB-DATA-CUBE]], in which orthogonal dimensions are combined to form the domain of the data cube. (A "dimension" in the data cube corresponds with an "axis" in CoverageJSON.) Therefore, although a formal mapping process has yet to be performed, we expect that interoperability between the RDF Data Cube and CoverageJSON is achievable. Some RDF Data Cube dimensions may be categorical or enumerated types rather than potentially continuous dimensions. The RDF Data Cube specification does not explicitly support spatiotemporal dimensions, but this is addressed in the [[QB4ST]] extensions.

This mechanism allows for a huge variety of domain structures to be encoded, from multidimensional grids to one-dimensional trajectories through four-dimensional space. To ease the burden on clients, CoverageJSON allows an optional domain type property to be defined (see the example above). If the data provider specifies that the domain is of a known type, the client then knows in more detail what to expect when the domain is inspected. For example, if the domain type is "Grid", the client knows that the domain MUST have axes that are called "x" and "y" (corresponding to the two horizontal spatial dimensions) and MAY have axes called "z" and "t" (corresponding respectively to the vertical and temporal dimensions). A number of common domain types are specified and there is a mechanism for data providers to define and register their own types. Note that in a typical document, short names ("Grid", "PointSeries", "Trajectory", etc.) are used to indicate the domain type, but in fact these are full URIs in disguise - this becomes apparent when viewing CoverageJSON document as RDF using the JSON-LD context (see below).

Encoding of data values

Data in CoverageJSON is held in Range objects, which represent multi-dimensional arrays. There are two subtypes of Range objects:

• An NdArray object encodes the array in its entirety, in line. In fact, the data values are encoded in a one-dimensional array, with a shape property that defines how to "unwrap" the one-dimensional array into a multi-dimensional one.
• A TiledNdArray object splits up a multi-dimensional array into several parts and links to those parts via URI templates ([[RFC6570]]) where each part is an NdArray object. A single TiledNdArray may define several ways of splitting up the array (each way is a tileset), to cater for different access scenarios.

Readers may wonder why multi-dimensional arrays are not encoded as nested arrays in CoverageJSON. Nested arrays (i.e. "arrays of arrays") are harder to manipulate and reason over, since there is no guarantee that the inner arrays are of a consistent length. With a one-dimensional array it is easy to verify that array.length matches the required number of elements, defined by the shape of the domain and the numbers in the shape property. In addition, Javascript engines can treat one-dimensional arrays more efficiently than nested arrays. APIs can be provided to extract slices in any dimension as if the array were truly multi-dimensional. This mirrors the approach taken by libraries such as numpy.

Here is an example of an NdArray:

{
  "type" : "NdArray",
  "dataType": "float",
  "axisNames": ["t", "y", "x"],
  "shape": [1, 90, 90],
  "values": [
    12.2, 12.0, 13.3, ...
    /* 8100 numbers (1*90*90) in row-major order */
  ]
}

Support for large datasets

For reasons of efficiency and convenience, data providers may prefer not to specify the range objects for all parameters inline in the same CoverageJSON document. In this case, there are two options:

1. For some or all parameters, create a separate JSON document containing an NdArray, which holds the values of that parameter. Then insert a link to this document in the Coverage document in place of the inline NdArray.
2. Additionally, the individual arrays may be split up into tiles, in which the values of each parameter are encoded in multiple JSON documents, each containing an NdArray.

The following illustrates how a coverage may be split up into a particular tileset:

{
  "type" : "TiledNdArray",
  "dataType": "float",
  "axisNames": ["t", "y", "x"],
  "shape": [3, 180, 360],
  "tileSets": [{
    "tileShape": [1, 90, 90],
    "urlTemplate": "http://example.com/{t}/{y}/{x}.covjson"
  }]
}
      

This is a 3 dimensional data set with dimensions (x, y, t) divided into two dimensional tiles for each t value: 4 along the X axis, 2 along the y axis and 3 along the t axis. Each tile is an NdArray, encoded as above.

Encoding of Parameter metadata

Data values are described in CoverageJSON using Parameter objects. These contain a minimal set of metadata needed to do something useful with the data values: a definition of the quantity being recorded (e.g. relative humidity, potential temperature, reflectance) and the units of measure in which the data values are expressed.

The sample JSON document below shows a Parameter object describing the sea surface temperature variable from the above skeleton JSON.

"SST" : {
  "type" : "Parameter",
  "observedProperty" : {
    "id" : "http://vocab.nerc.ac.uk/standard_name/sea_surface_temperature/",
    "label" : {
      "en" : "Sea Surface Temperature",
      "de" : "Meeresoberflächentemperatur"
    },
    "description" : {
      "en" : "The temperature of sea water near the surface",
      "de" : "Die Temperatur des Meerwassers nahe der Oberfläche"
    }
  },
  "unit" : {
    "label" : {
      "en" : "Degree Celsius",
      "de" : "Grad Celsius"
    },
    "symbol": {
      "value" : "Cel",
      "type" : "http://www.opengis.net/def/uom/UCUM/"
    }
  }
}

Note that the main features of the Parameter metadata in this example are:

• a URI link to the definition of the parameter in question,
• a strongly-typed unit string, using UCUM encoding rules,
• internationalisation of human-readable strings (labels).

Other metadata, such as provenance information, is not part of the core CoverageJSON specification, but can be recorded via the extension mechanism.

CoverageJSON documents

A single CoverageJSON document can contain one of the following types of object:

• A single Coverage
• A collection of Coverages
• A standalone Domain
• An NdArray
• A TiledNdArray

The top-level object within a document contains a “type” property that identifies the type of the object that it contains. Documents may be linked to other documents; in this way data providers can ensure that each individual document is of a manageable size, with large datasets being partitioned among a number of linked documents. (See "Support for large datasets" above.)

CoverageJSON, JSON-LD and RDF

To a limited extent, a CoverageJSON document can be converted into RDF through the use of a JSON-LD context header. The extent to which this is possible is discussed in [[COV-JSONLD-RDF]].

We did not consider that conversion to RDF should be a primary goal: we focused mainly on simplicity and readability of the format, under the assumption that few of the target users (web developers) would require a pure RDF representation of the data. Enabling a full conversion to RDF would require complicating the format (mainly for technical reasons including limitations of JSON-LD). Also, RDF is an unsuitable format for large arrays of data and so the Domain and Range would not convert efficiently.

Nevertheless, CoverageJSON makes frequent use of URIs to denote key concepts, such as units, observed properties, coordinate reference systems, domain types and links to other CoverageJSON documents. Clients can make use of these to detect these concepts unambiguously, whether or not they perform a translation to RDF.

By using the canonical CoverageJSON JSON-LD context, it is possible to convert the above Parameter directly into RDF triples:

_:SST <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <https://covjson.org/def/core#Parameter> .
_:SST <http://qudt.org/schema/qudt#unit> _:SST_UNIT .
_:SST_UNIT <http://qudt.org/schema/qudt#symbol> "Cel"^^<http://www.opengis.net/def/uom/UCUM/> .
_:SST_UNIT <http://www.w3.org/2004/02/skos/core#prefLabel> "Degree Celsius"@en .
_:SST_UNIT <http://www.w3.org/2004/02/skos/core#prefLabel> "Grad Celsius"@de .
_:SST <http://www.w3.org/2005/Incubator/ssn/ssnx/ssn#observedProperty> <http://vocab.nerc.ac.uk/standard_name/sea_surface_temperature/> .
<http://vocab.nerc.ac.uk/standard_name/sea_surface_temperature/> <http://purl.org/dc/terms/description> "Die Temperatur des Meerwassers nahe der Oberfläche"@de .
<http://vocab.nerc.ac.uk/standard_name/sea_surface_temperature/> <http://purl.org/dc/terms/description> "The temperature of sea water near the surface"@en .
<http://vocab.nerc.ac.uk/standard_name/sea_surface_temperature/> <http://www.w3.org/2004/02/skos/core#prefLabel> "Meeresoberflächentemperatur"@de .
<http://vocab.nerc.ac.uk/standard_name/sea_surface_temperature/> <http://www.w3.org/2004/02/skos/core#prefLabel> "Sea Surface Temperature"@en .

An interesting area of future work would be to define two-way mappings between CoverageJSON and an RDF Data Cube representation (using the QB4ST extensions to the latter). As noted above, there are a number of similarities between the two representations, and defining such mappings should be possible.

Extension points

CoverageJSON allows data providers to extend the format in a controlled manner to enable capabilities that are not supported by the core specification. The possible extensions that can be defined by users include:

• Custom properties (e.g. high-level metadata such as licence information)
• Custom domain types (enabling support for coverage types that are not foreseen in the existing domain types, e.g. rain radar measurements)
• Custom data types for axes
• Custom referencing system types (e.g. HEALPix grids)
• Different grammars for encoding unit symbols (e.g. UDUNITS)
• Alternative encodings for range values (e.g. compressed encodings)

In each case we recommend that URIs be used to denote these extensions (and to point to definitions), to avoid the possibility of clashes between extensions.

NetCDF and CF-NetCDF

[[NetCDF]] is a binary, platform-independent, domain-neutral data format for multidimensional data. Essentially, a NetCDF file is a collection of multidimensional arrays, plus metadata provided as key-value pairs. Metadata conventions are required to specialise NetCDF for particular communities. The Climate and Forecast conventions are the pre-eminent conventions for geospatial NetCDF data. NetCDF files that conform to these conventions are known as "CF-NetCDF files". Note that there are different varieties of the NetCDF format and data model. Here we are concerned with the "classic" NetCDF data model. The "enhanced" data model is not supported by the CF conventions and is much less widely used in practice.

The overall structure of CoverageJSON is quite close to that of [[NetCDF]], consisting essentially of a set of orthogonal domain axes that can be combined in different ways. One major difference is that in CoverageJSON, there is an explicit Domain object, whereas in NetCDF the domain is specified implicitly by linking data variables with coordinate variables. One consequence of this is that NetCDF files can contain several domains and hence several Coverages. A NetCDF file could therefore be converted to a single Coverage or a Coverage Collection in CoverageJSON.

OGC Coverage Implementation Schema (CIS)

The overall concepts of CoverageJSON are close to those of the [[ISO19123]] standard and the OGC standard Coverage Implementation Schema ([[OGC-CIS]]), which specialises ISO19123. The main points of difference are:

• CIS uses a different set of rules for gridded and non-gridded data, whereas CoverageJSON uses a single consistent set.
• CIS allows each Coverage to have exactly one CRS, whereas CoverageJSON allows different CRSs to be applied to different sets of coordinates in the domain (e.g. one CRS for x and y, and another CRS for z).
• Version 1.1 of CIS defines a JSON encoding that uses a near-literal translation of GML structures into JSON. CoverageJSON does not use GML as its starting point.

OGC TimeseriesML

CoverageJSON can be used to record data that take the form of timeseries, for example measurements of flow rate in in a river, or average London rainfall over time. [[TimeseriesML]] specializes in recording such data and provides some features that are not provided in CoverageJSON. In TimeseriesML, richer metadata can be added to describe in more detail the data values being measured (the range) and their relationship to time (the domain). For example, a data value in the range may be defined to represent an accumulation, maximum, minimum, average or several other functions of a quantity over time, and the time values in the domain may be defined to mark the start, end or middle of the time period in question. In CoverageJSON, this level of description is not yet possible.

Version 1.0 of TimeseriesML (the current version at the time of writing) does not permit the association of multiple parameters with each data point, whereas this is permitted in CoverageJSON.