Overview of CoverageJSON
The full specification for CoverageJSON is published on GitHub, which also records all discussions that led to the design decisions in the format. The specification is split up into two documents: the core part, and a set of optional domain types that ease interoperability.
High-level structure
In CovJSON, 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, plus referencing info. An axis can contain primitive values like latitudes or longitudes but can also contain complex values like tuples or polygons.
CovJSON knows the concept of a domain type which allows clients to easily identify a certain domain structure. Typically, a domain type constrains the axes (e.g. value type, names, length) and allowed reference systems. CovJSON defines a number of common domain types where custom ones can be used with the extension mechanism.
The following is a complete example of a grid domain with longitude, latitude, and time axes:
{
"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"
}
}]
}
Encoding of data values
Data in CovJSON is held in Range objects which represent multi-dimensional arrays. There are two subtypes of Range objects:
- An NdArray object encodes a multi-dimensional array in its entirety.
- A TiledNdArray object splits up a multi-dimensional array into several parts and links to those parts via URI templates (RFC 6570) where each part is an NdArray object. A single TiledNdArray may define several split-ups, called tilesets, to cater for different access scenarios.
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"
}]
}
A single tile has the following structure:
{
"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 */
]
}
CovJSON documents
A single CoverageJSON document can contain one of the following types of object:
- A single Coverage
- A collection of Coverages. (TODO describe this more?)
- A standalone Domain
- An NdArray or 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.
CovJSON, JSON-LD and RDF
To a limited extent, a CovJSON 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 section REF below, and in (TODO: insert link to Montreal paper).
We did not consider that coversion 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.
Metadata model
Metadata in CovJSON revolves around describing the semantics of domain points and data values. Reference systems are used to provide metadata for domain points, whereas Parameter objects provide semantics for data values. Other metadata, like provenance information, can be recorded via the extension mechanism.
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 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).
By using the canonical CovJSON 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 .
Extension points
We allow data providers to extend the format in a controlled manner. The possible extensions that can be defined by users include:
- Custom properties (e.g. high-level metadata such as licence information)
- Custom domain types
- 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
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.