Skip to content

Commit a96eb50

Browse files
author
Jon Blower
committed
Further edits to CovJSON document
1 parent 5729539 commit a96eb50

File tree

1 file changed

+43
-22
lines changed

1 file changed

+43
-22
lines changed

‎coverage-json/index.html‎

Lines changed: 43 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -96,10 +96,10 @@ <h2>Overview of CoverageJSON</h2>
9696
<h3>High-level structure</h3>
9797
<p>In CovJSON, a Coverage consists of the following objects:</p>
9898
<ul>
99-
<li>A Domain (exactly one), which encodes the set of points in space and time for which we have data values.</li>
100-
<li>A set of Range objects (one per scalar quantity), holding actual data values.</li>
101-
<li>A set of Parameter objects (one per scalar quantity), describing the data values.</li>
102-
<li>An optional set of ParameterGroup objects, which describe any semantic associations between Parameters.</li>
99+
<li>A <dfn>Domain</dfn> (exactly one), which encodes the set of points in space and time for which we have data values.</li>
100+
<li>A set of <dfn>Range</dfn> objects (one per scalar quantity), holding actual data values.</li>
101+
<li>A set of <dfn>Parameter</dfn> objects (one per scalar quantity), describing the data values.</li>
102+
<li>An optional set of <dfn>ParameterGroup</dfn> objects, which describe any semantic associations between Parameters.</li>
103103
</ul>
104104
<p>A sample skeleton document encoding a three-dimensional gridded Coverage with two Parameters (sea surface temperature and sea ice area fraction) is shown here:</p>
105105
<pre>
@@ -127,16 +127,27 @@ <h3>High-level structure</h3>
127127
}
128128
</pre>
129129

130-
<h3>Scalability and tiling</h3>
131-
<p>TODO: explain range tiling mechanism. Show JSON example. See picture below.</p>
130+
<h3>Encoding the Domain</h3>
131+
<p>TODO: explain the "domainType". All domains are collections of orthogonal axes, plus referencing info.</p>
132+
133+
<h3>Encoding of data values</h3>
134+
<p>TODO: explain NdArrays, and TiledNdArrays. Show JSON example of a tileSet. See picture below.</p>
132135
<img src="covjson-tiling.png" width="500"/>
133136

134137
<h3>CovJSON documents</h3>
135-
<p>TODO: talk about different kinds of documents and how they link together.</p>
138+
<p>A single CoverageJSON document can contain one of the following types of object:</p>
139+
<ul>
140+
<li>A single Coverage</li>
141+
<li>A collection of Coverages. (TODO describe this more?)</li>
142+
<li>A standalone Domain</li>
143+
<li>An NdArray or TiledNdArray</li>
144+
</ul>
145+
<p>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.</p>
136146

137147
<h3>CovJSON, JSON-LD and RDF</h3>
138148
<p>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).</p>
139149
<p>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.</p>
150+
<p>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.</p>
140151

141152
<h3>Metadata model</h3>
142153
<p>TODO: talk about scope of metadata, particularly describing Parameters. The sample JSON document below shows a Parameter object describing the sea surface temperature variable from the above skeleton JSON (TODO: insert link to section above somehow).</p>
@@ -146,53 +157,63 @@ <h3>Metadata model</h3>
146157
"observedProperty" : {
147158
"id" : "http://vocab.nerc.ac.uk/standard_name/sea_surface_temperature/",
148159
"label" : {
149-
"en": "Sea Surface Temperature",
150-
"de": "Meeresoberflächentemperatur"
160+
"en" : "Sea Surface Temperature",
161+
"de" : "Meeresoberflächentemperatur"
151162
},
152163
"description" : {
153-
"en": "The temperature of sea water near the surface",
154-
"de": "Die Temperatur des Meerwassers nahe der Oberfläche"
164+
"en" : "The temperature of sea water near the surface",
165+
"de" : "Die Temperatur des Meerwassers nahe der Oberfläche"
155166
}
156167
},
157168
"unit" : {
158169
"label" : {
159-
"en": "Degree Celsius",
160-
"de": "Grad Celsius"
170+
"en" : "Degree Celsius",
171+
"de" : "Grad Celsius"
161172
},
162173
"symbol": {
163-
"value": "Cel",
164-
"type": "http://www.opengis.net/def/uom/UCUM/"
174+
"value" : "Cel",
175+
"type" : "http://www.opengis.net/def/uom/UCUM/"
165176
}
166177
}
167178
}
168179
</pre>
169180
<p>Note that the main features of the metadata are: (i) a URI link to the definition of the parameter in question, (ii) a strongly-typed unit string, using UCUM encoding rules, (iii) internationalisation of human-readable strings (labels).<p>
170181
<p><strong>MAIK</strong> - would this Parameter object convert to RDF nicely? If so we could insert the triples that would result.</p>
171182

172-
<h3>Linked Data / Semantic Web support</h3>
173-
<p>Use of URIs, limited JSON-LD support</p>
174-
175183
<h3>Extension points</h3>
176184
<p>We allow data providers to extend the format in a controlled manner. The possible extensions that can be defined by users include:</p>
177185
<ul>
178186
<li>Custom properties (e.g. high-level metadata such as licence information)</li>
179187
<li>Custom domain types</li>
180188
<li>Custom data types for axes</li>
181-
<li>Custom referencing systems (e.g. HEALPix grids, REF)</li>
189+
<li>Custom referencing systems (e.g. <a href="http://healpix.jpl.nasa.gov">HEALPix</a> grids)</li>
182190
<li>Different grammars for encoding unit symbols (e.g. UDUNITS)</li>
183191
<li>Alternative encodings for range values</li>
184192
</ul>
185-
<p>In each case we recommend that URIs (full or compact) be used to denote these extensions (and to point to definitions), to avoid the possibility of clashes between extensions.</p>
193+
<p>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.</p>
186194
</section>
187195

188196
<section id="tools">
189197
<h2>Tools and libraries</h2>
190-
<p>TODO: describe them and link to the <a href="https://covjson.org/tools/">website</a>.</p>
198+
<p>TODO: outline them and link to the <a href="https://covjson.org/tools/">website</a>.</p>
191199
</section>
192200

193201
<section id="otherDataModels">
194202
<h2>Relationship with other data models</h2>
195-
<p>NetCDF, CIS, ISO19123, GeoJSON?</p>
203+
<h3>NetCDF and CF-NetCDF</h3>
204+
<p class="note">NetCDF (REF) is a binary, platform-independent data format for multidimensional data, which is independent of any community of practice. 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 (REF) conventions are the pre-eminent conventions for geospatial data. NetCDF files that conform to these conventions are known as "CF-NetCDF files".)</p>
205+
<p>The overall structure of CoverageJSON is quite close to that of NetCDF (REF), 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.</p>
206+
207+
<h3>OGC Coverage Implementation Schema (CIS)</h3>
208+
<p>The overall concepts of CoverageJSON are close to those of the ISO19123 standard (REF) and the OGC standard Coverage Implementation Schema (CIS, REF), which specialises ISO19123. The main points of difference are:</p>
209+
<ul>
210+
<li>CIS uses a different set of rules for gridded and non-gridded data, whereas CoverageJSON uses a single consistent set.</li>
211+
<li>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).</li>
212+
<li>The most recent version 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.</li>
213+
</ul>
214+
215+
<h3>Other data models</h3>
216+
<p>TODO: say something about TimeseriesML (and WaterML?) and note that CoverageJSON does not support all the details of encoding timeseries that these standards accommodate. Also, we don't support interleaved domain-range syntax, which these standards do support.</p>
196217
</section>
197218

198219
<section id="mappingToBP">

0 commit comments

Comments
 (0)