I. Abstract
The OGC Testbed-17 Features and Geometries JSON task investigated proposals for how feature data could be encoded in JSON so that:
-
Different Coordinate Reference Systems (CRS) are supported and
-
Communities can build and formally specify profiles of the fully CRS-enabled JSON with limited sets of supported geometry types and with clear constraints for feature type definitions.
GeoJSON, a standard of the Internet Engineering Task Force (IETF), was used as a starting point.
This Engineering Report (ER) captures the results and discussions, including material that was submitted to the OGC Features and Geometries JSON Standards Working Group.
II. Executive Summary
JavaScript Object Notation (JSON) is a popular encoding format for geospatial data. The lightweight, simple syntax, and clear human and machine readability of JSON appeals to developers. GeoJSON has become a very popular encoding and is supported in most deployments of APIs implementing OGC API Features. However, GeoJSON has limitations that prevent or limit its use in some cases, e.g., if other coordinates should be in a projected coordinate reference system.
To support additional use cases, in 2021 the OGC formed a new Standards Working Group (SWG) to develop an OGC Features and Geometries JSON standard (JSON-FG).
As identified in the SWG charter, the standard will:
-
Include the ability to use Coordinate Reference Systems (CRSs) other than WGS84;
-
Support the use of non-Euclidean metrics, in particular ellipsoidal metrics;
-
Support solids and multi-solids as geometry types; and
-
Provide guidance on how to represent feature properties, e.g., including temporal properties.
JSON Schema has been identified as the mechanism to formally specify the syntax of JSON-FG.
Given the popularity of GeoJSON, the participants determined that a design goal is that JSON-FG will be specified as a superset of GeoJSON. Valid JSON-FG instances are also valid GeoJSON instances.
In order to support the work of the SWG, Testbed-17 included a task to:
-
Develop specification proposals for the SWG;
-
Engage with the SWG in discussions; and
-
Implement and test draft JSON-FG specifications in three server and three client implementations.
The general JSON-FG design pattern is that information that can be represented as GeoJSON is encoded as GeoJSON. Additional information is mainly encoded in additional top-level members of GeoJSON objects. The members use keys that do not conflict with GeoJSON including the obsolete version that pre-dates the IETF standard. GeoJSON clients will be able to parse and understand all aspects that are specified by GeoJSON, JSON-FG clients will also parse and understand the additional capabilities.
The following extensions were discussed and developed during the testbed:
Of these, the first five resulted in requirements and normative statements.
For the topic “relationships and links”, the participants identified and documented potential JSON-FG encoding patterns. However, the participants agreed that depending on the data and how the data is expected to be used, the preferences of data publishers for one or the other pattern will vary.
The work on “offline containers” is out-of-scope of the SWG charter and was a Testbed-only activity.
All Technology Integration Experiments (TIEs) were completed successfully. Problems identified during initial experiments were usually a result of simple errors or temporary unavailability of server deployments.
Most of the JSON-FG extensions to GeoJSON were tested and proved useful for clients processing the JSON feature data. The experiences are consistent with the feedback from the Aviation task in Testbed-17 on the benefits of using JSON-FG as a feature encoding in the aviation domain [4].
The experiences support the current JSON-FG approach that:
-
Extends GeoJSON (every JSON-FG document is a valid GeoJSON document);
-
Focusses on minimal extensions to GeoJSON that are useful in many contexts relevant to OGC members and avoid edge cases;
-
Specifies the extensions as additional top-level JSON members (do not add constraints on “properties” or any other GeoJSON member); and
-
Specifies the extensions in a modular way, so that implementations can pick and choose the capabilities that they need.
Extending existing GeoJSON writers and readers with the additional JSON members was in general straightforward in the six software components implementing JSON-FG. However, more testing and developer feedback will be needed to mature the draft JSON-FG specification.
There are also open issues that should be discussed in the Features and Geometries JSON SWG and, if possible, future Innovation Program initiatives, including, but not limited to the following:
-
Recommendations when to include the fallback GeoJSON “geometry” member or not and OGC API building blocks to control the behavior.
-
Support for 3D geometries through polyhedron geometry objects or other encodings (base surface plus height, support for circles, more compact coordinate encodings).
-
How to simplify the parsing of the JSON schemas describing the feature schemas.
-
Continue to investigate the options for representing relationships with or links to other resources.
-
Potential support for a “geometryDimension” member and a potential conformance class for homogeneous feature collections.
III. Keywords
The following are keywords to be used by search engines and document catalogues.
ogcdoc, OGC document, JSON
IV. Security considerations
No security considerations have been made for this document.
V. Submitting Organizations
The following organizations submitted this Document to the Open Geospatial Consortium (OGC):
- interactive instruments GmbH
VI. Submitters
All questions regarding this document should be directed to the editor or the contributors:
Name | Organization | Role |
---|---|---|
Clemens Portele | interactive instruments | Editor |
Ignacio Correas | Skymantics | Contributor |
Patrick Dion | Ecere Corporation | Contributor |
Jérôme Jacovella-St-Louis | Ecere Corporation | Contributor |
Stefano Bovio | GeoSolutions | Contributor |
Felipe Carrillo Romero | Hexagon | Contributor |
Panagiotis (Peter) Vretanos | CubeWerx | Contributor |
OGC Testbed-17: OGC Features and Geometries JSON Engineering Report
1. Scope
OGC Features and Geometries JSON (JSON-FG) extends GeoJSON to support a limited set of additional capabilities that are out-of-scope for GeoJSON, but that are essential or important for a variety of use cases involving feature data.
Information that can be represented as GeoJSON is encoded as GeoJSON. Additional information is mainly encoded in additional top-level members of GeoJSON objects. The members use keys that do not conflict with GeoJSON including the obsolete version that pre-dates the IETF standard. GeoJSON clients will be able to parse and understand all aspects that are specified by GeoJSON, JSON-FG clients will also parse and understand the additional capabilities.
JSON Schema is used to formally specify the JSON-FG syntax.
This document includes the current JSON-FG specification, describes implementations and technology experiments as well as recommendations.
2. Terms, definitions and abbreviated terms
This document uses the terms defined in OGC Policy Directive 49, which is based on the ISO/IEC Directives, Part 2, Rules for the structure and drafting of International Standards. In particular, the word “shall” (not “must”) is the verb form used to indicate a requirement to be strictly followed to conform to this document and OGC documents do not use the equivalent phrases in the ISO/IEC Directives, Part 2.
This document also uses terms defined in the OGC Standard for Modular specifications (OGC 08-131r3), also known as the ‘ModSpec’. The definitions of terms such as standard, specification, requirement, and conformance test are provided in the ModSpec.
For the purposes of this document, the following additional terms and definitions apply.
2.1. Terms and definitions
2.1.1. coordinate reference system
coordinate system that is related to an object by a datum (source: OGC Topic 2, version 5.0)
2.1.2. feature
abstraction of real world phenomena [ISO 19101-1:2014]
Note 1 to entry: More details about the term ‘feature’ may be found in the W3C/OGC Spatial Data on the Web Best Practice in the section ‘Spatial Things, Features and Geometry’.
2.1.3. feature collection
a set of features from a dataset
2.2. Abbreviated terms
AIXM
-
Aeronautical Information Exchange Model
AMDB
-
Airport Mapping Database
AMXM
-
Aerodrome Mapping Exchange Model
API
-
Application Programming Interface
CNS
-
Communications, Navigation and Surveillance
CRS
-
Coordinate Reference System
DSS
-
Discovery and Synchronization Service
FAA
-
Federal Aviation Administration
JSON
-
JavaScript Object Notation
JSON-FG
-
OGC Features and Geometries JSON
JSON-LD
-
JSON for Linking Data
KMEM
-
Memphis airport
OGC
-
Open Geospatial Consortium
REM
-
Route Exchange Model
SFDPS
-
SWIM Flight Data Publication Service
STAC
-
SpatioTemporal Asset Catalog
SWG
-
Standards Working Group
SWIM
-
System Wide Information Management
TIE
-
Technology Integration Experiment
UAS
-
Unmanned Aircraft System
UI
-
User Interface
USS
-
UTM Service Suppliers
UTM
-
UAS Traffic Management
3. Introduction
Clause 4 summarizes the reasons for and the scope of the development of JSON-FG in both the Standards Working Group (SWG) and in Testbed-17.
This discussion is followed by a brief chapter, Clause 5, that summarizes key user stories driving the design of JSON-FG.
The next chapter, Clause 6, specifies the extensions to GeoJSON and discusses design decisions and considerations. The OGC Testbed-17 Engineering Report “Features and Geometries JSON CRS Analysis of Alternatives” [3] has additional discussion about representing and referencing coordinate reference systems in a JSON-FG document.
The server and client implementations are described in Clause 7.
The final chapter, Clause 8, summarizes and discusses results from the Technology Integration Experiments (TIEs). The chapter identifies open issues and recommendations.
4. Motivation and Requirements
JavaScript Object Notation (JSON) is a popular encoding format for geospatial data. The lightweight, simple syntax, and clear human and machine readability of JSON appeals to developers. GeoJSON has become a very popular encoding and is supported in most deployments of APIs implementing OGC API Features. However, GeoJSON has limitations that prevent or limit its use in some cases, including:
-
WGS 84 is the only coordinate reference system that is supported;
-
Geometries are restricted to points, curves and surfaces with linear interpolation; and
-
No general capability is available to specify the schema of a feature, its type or its temporal extent.
In 2021, the OGC Membership approved the formation of a OGC Features and Geometries JSON Standards Working Group (SWG). The goal of the SWG is to specify minimal extensions to the GeoJSON Standard to support additional uses cases that are important to many OGC members.
The main extensions identified in the SWG charter are to:
-
Include the ability to use Coordinate Reference Systems (CRSs) other than WGS 84,
-
Allow the use of non-Euclidean metrics, in particular ellipsoidal metrics,
-
Support solids and multi-solids as geometry types, and
-
Provide guidance on how to represent feature properties, e.g., including temporal properties.
Testbed-17 participants were tasked to support the work of the SWG and in addition to also look into the following topics:
-
How to support profiles with reduced geometry options and value constraints for features properties?
-
How to support usage of Features and Geometries JSON in offline containers?
5. Scenario
The following general scenarios are useful in understanding the principles that have been used in the JSON-FG design:
-
In order to display features in a 3D scene, a client accesses a Web API that shares a building dataset and that implements OGC API Features. The scene uses a projected CRS. The API advertises support for both GeoJSON and OGC JSON-FG as feature representations and support for the projected CRS in addition to WGS 84.
-
A client accesses a JSON-FG file with building data that is stored locally or as a static file in the cloud (e.g., in an Object Storage or a GitHub repository). Again, the file is accessed to display features in a 3D scene and a time slider is used to suppress features outside of a user-specified time interval.
NOTE The following description uses a hypothetical media type application/fg+json for OGC JSON-FG.
5.1. Using a GeoJSON client
The client supports only GeoJSON and not JSON-FG.
In the first scenario (API access), the client requests the GeoJSON representation of the feature using Accept: application/geo+json. This is because the client only supports a GeoJSON feature encoding. The response will in general not include the JSON-FG extensions and is provided in WGS 84 with axis order longitude/latitude as the spatial CRS. The client will transform the geometry to the projected CRS.
In the second scenario (file access), the client has no access to a media type and has to inspect the file to determine if the file is a GeoJSON document that it can process. While the document is a JSON-FG document it should also be a valid GeoJSON document, so that the client is still able to use and display the features. The client will, however, not understand the additional information introduced by JSON-FG. Any JSON-FG extensions must not conflict with existing GeoJSON members to avoid issues for GeoJSON clients parsing JSON-FG documents.
5.2. Using a JSON-FG client
The client supports GeoJSON and JSON-FG.
In the first scenario (API access), the client will typically request the JSON-FG representation of the feature using an HTTP like Accept: application/fg+json, application/geo+json;q=0.8 in the projected CRS. The header states that the client prefers JSON-FG, but will also accept GeoJSON, if JSON-FG is not available. The response will state Content-Type: application/fg+json and include the JSON-FG extensions which will include the spatial geometry in the requested projected CRS and the temporal extent.
In the second scenario (file access), the client is in the same position as the GeoJSON client — it has no access to a media type and has to inspect the file to determine — if the file is a GeoJSON, JSON-FG or some other kind of document that it does not understand. JSON-FG documents include explicit declarations that conform to both GeoJSON and JSON-FG. Therefore, the client can easily identify the document as a JSON-FG document and process the content. Since the JSON-FG document identifies the spatial and temporal extent of each feature, the scene extent and, for example, a time slider can be provided by the client so that the user can filter the features to display in the scene.
6. Specification of JSON-FG extensions
6.1. General Approach
OGC Features and Geometries JSON (JSON-FG) extends GeoJSON to support a limited set of additional capabilities that are out-of-scope for GeoJSON, but that are essential or important for a variety of use cases involving feature data.
Information that can be represented as GeoJSON is encoded as GeoJSON. Additional information is mainly encoded in additional top-level members of GeoJSON objects. The members use keys that do not conflict with GeoJSON including the obsolete version that pre-dates the IETF standard. GeoJSON clients will be able to parse and understand all aspects that are specified by GeoJSON, JSON-FG clients will also parse and understand the additional capabilities.
JSON Schema is used to formally specify the JSON-FG syntax.
6.2. Media types
A media type should eventually be registered for JSON-FG, for example, application/fg+json.
Until the JSON-FG extensions are stable, a different media type should be used to avoid issues with implementations of drafts of the extensions. The implementations in the testbed used application/vnd.ogc.fg+json as the media type.
Since a JSON-FG document also conforms to GeoJSON, both the GeoJSON and the JSON-FG media types can be used. APIs that provide feature data that conforms to both GeoJSON and JSON-FG should declare support for both media types in the API definition to support clients that know JSON-FG and also those that only support GeoJSON.
6.3. Extension overview
6.4. Requirements classes
The following is a proposal of how to aggregate the JSON-FG extensions into requirements classes:
-
“Core”: Support for Clause 6.8, Clause 6.9 and Clause 6.10, except support for Clause 6.9.2.3 and Clause 6.9.2.4. Depends on GeoJSON.
-
“3D”: Geometries are in a 3D CRS and may be a Clause 6.9.2.3 or Clause 6.9.2.4. Depends on “Core”.
-
“Feature Types and Schemas”: Support for Clause 6.6 and Clause 6.7. No dependencies.
Implementations must support at least the Core requirements class to use the JSON-FG media type.
The Features API SWG or the Features and Geometries JSON SWG could consider defining mechanisms for how to add optional support for “Feature Types and Schemas” and for GeoJSON output as these capabilities can be useful for GeoJSON clients, too.
6.5. An example feature
The following feature instance is an example of a building feature that includes all new capabilities proposed for JSON-FG. The JSON-FG extensions are described in the following sections.
Example — Building with a polyhedron geometry and the polygon footprint
{
"type": "Feature",
"id": "DENW19AL0000giv5BL",
"featureType": "app:building",
"when": {
"interval": [ "2014-04-24T10:50:18Z", null ]
},
"coordRefSys": "http://www.opengis.net/def/crs/EPSG/0/5555",
"where": {
"type": "Polyhedron",
"coordinates": [
[
[
[ 479816.67, 5705861.672, 100 ],
[ 479824.155, 5705853.684, 100 ],
[ 479829.666, 5705858.785, 100 ],
[ 479822.187, 5705866.783, 100 ],
[ 479816.67, 5705861.672, 100 ]
]
],
[
[
[ 479816.67, 5705861.672, 110 ],
[ 479824.155, 5705853.684, 110 ],
[ 479829.666, 5705858.785, 120 ],
[ 479822.187, 5705866.783, 120 ],
[ 479816.67, 5705861.672, 110 ]
]
],
[
[
[ 479816.67, 5705861.672, 110 ],
[ 479824.155, 5705853.684, 110 ],
[ 479824.155, 5705853.684, 100 ],
[ 479816.67, 5705861.672, 100 ],
[ 479816.67, 5705861.672, 110 ]
]
],
[
[
[ 479824.155, 5705853.684, 110 ],
[ 479829.666, 5705858.785, 120 ],
[ 479829.666, 5705858.785, 100 ],
[ 479824.155, 5705853.684, 100 ],
[ 479824.155, 5705853.684, 110 ]
]
],
[
[
[ 479829.666, 5705858.785, 120 ],
[ 479822.187, 5705866.783, 120 ],
[ 479822.187, 5705866.783, 100 ],
[ 479829.666, 5705858.785, 100 ],
[ 479829.666, 5705858.785, 120 ]
]
],
[
[
[ 479822.187, 5705866.783, 120 ],
[ 479816.67, 5705861.672, 110 ],
[ 479816.67, 5705861.672, 100 ],
[ 479822.187, 5705866.783, 100 ],
[ 479822.187, 5705866.783, 120 ]
]
]
]
},
"geometry": {
"type": "Polygon",
"coordinates": [
[
[ 8.709204563652449, 51.50352856284526, 100 ],
[ 8.709312860802727, 51.503457005181794, 100 ],
[ 8.709391968693081, 51.50350306810203, 100 ],
[ 8.709283757429898, 51.503574715968284, 100 ],
[ 8.709204563652449, 51.50352856284526, 100 ]
]
]
},
"links": [
{
"href": "https://ogc-api.nrw.de/lika/v1/collections/gebaeude_bauwerk/items/DENW19AL0000giv5BL?f=json",
"rel": "self",
"type": "application/geo+json",
"title": "This document"
},
{
"href": "https://ogc-api.nrw.de/lika/v1/collections/gebaeude_bauwerk/items/DENW19AL0000giv5BL?f=html",
"rel": "alternate",
"type": "text/html",
"title": "This document as HTML"
},
{
"href": "https://ogc-api.nrw.de/lika/v1/collections/gebaeude_bauwerk?f=json",
"rel": "collection",
"type": "application/json",
"title": "The collection the feature belongs to"
},
{
"href" : "https://ogc-api.nrw.de/lika/v1/collections/flurstueck/items/05297001600313______",
"rel" : "http://www.opengis.net/def/rel/ogc/1.0/within",
"title" : "Cadastral parcel 313 in district Wünnenberg (016)"
},
{
"href":"https://inspire.ec.europa.eu/featureconcept/Building",
"rel":"type",
"title":"This feature is of type 'building'"
},
{
"href": "https://ogc-api.nrw.de/lika/v1/collections/gebaeude_bauwerk/schema",
"rel": "describedby",
"type": "application/schema+json",
"title": "JSON Schema of this document"
},
{
"href":"http://schemas.opengis.net/tbd/Feature.json",
"rel":"describedby",
"type":"application/schema+json",
"title":"This document is a JSON-FG Feature"
},
{
"href":"https://geojson.org/schema/Feature.json",
"rel":"describedby",
"type":"application/schema+json",
"title":"This document is a GeoJSON Feature"
}
],
"properties": {
"lastChange": "2014-04-24T10:50:18Z",
"built": "2012-03",
"function": "Agricultural building",
"height_m": 20.0,
"owners": [
{
"href": "https://example.org/john-doe",
"title": "John Doe"
},
{
"href": "https://example.org/jane-doe",
"title": "Jane Doe"
}
]
}
}
6.6. Identifying the feature type(s)
6.6.1. Overview
Features are often categorized by type. Typically, all features of the same type have the same schema and the same properties.
Many GIS clients depend on knowledge about the feature type when processing feature data. For example, associating a style to a feature in order to render that feature on a map.
GeoJSON is schema-less in the sense that it has no concept of feature types or feature schemas.
In most cases, a feature is an instance of a single feature type. The current draft revision of the Simple Features standard supports features that are instances of multiple types. JSON-FG, therefore, also supports multiple feature types.
The related element Identifying the schema specifies which elements of the JSON Schema documents are identified that the JSON-FG document conforms to. This element specifies how to represent feature type information in the JSON object that represents the feature.
6.6.2. Description
6.6.2.1. The “featureType” member
The feature types of a feature are declared in a top-level member with the key “featureType”. The value is either a string (in the standard case of a single feature type) or an array of strings (to support features that instantiate multiple feature types). Each string should be a code, convenient for the use in filter expressions.
6.6.2.2. Homogeneous feature collections
Some clients will process feature collections differently depending on whether the collection is homogenous with respect to the feature type or the geometry type. These clients will benefit from information that declares the feature and/or geometry type for all features in a collection.
If the JSON document is a feature collection and all features in the feature collection have the same “featureType” value, the “featureType” member can and should be added once for the feature collection. The “featureType” member can then be omitted in the feature objects. Declaring the feature type(s) once signals to clients that the feature collection is homogeneous with respect to the type, which clients can use to optimize their processing.
If the JSON document is a feature collection and all features in the feature collection have the same geometry type as their primary geometry (point, curve, surface, solid, including homogenous aggregates), a “geometryDimension” member can and should be added once for the feature collection with the dimension of the geometry (0 for points, 1 for curves, 2 for surfaces, 3 for solids, null/not set for mixed dimensions or unknown). Declaring the geometry dimension once signals to clients that the feature collection is homogeneous with respect to the dimension, which clients can use to optimize their processing.
6.6.2.3. Links to a semantic type
If a persistent resource exists, such as in a registry, that describes a feature type, a link to that resource with link relation type type should be added. In the case of multiple feature types per feature, multiple links are added.
OGC API Features already specifies a general “links” member with an array of link objects based on RFC 8288 (Web linking) and feature responses from APIs implementing OGC API Features will already include a “links” member. JSON-FG builds on this approach and includes a “type” link to a resource identifying the abstract semantic type of which the feature is considered to be an instance.
Table 1 — Link properties
Property | Type | Description |
---|---|---|
href | URI | REQUIRED. The URI of a persistent resource that describes a feature type that is instantiated by the feature that is the link context. |
rel | String | REQUIRED. The link relation type, always “type”. |
type | String | To indicate a hint about a specific media type in which the target of the link is available, set the value to that media type; for example, “text/html”. |
title | String | Include this link attribute for a human readable label of the link, e.g. for use in a derived HTML representation. |
Additional link attributes may be added to the Link object.
6.6.3. Discussion
The following aspects were discussed:
Initial experiments used JSON-LD @type member to identify the feature type(s) of the feature. This approach, however, was changed to the current approach for the following reasons:
-
In many cases, feature types are specified by communities or data publishers without a persistent URI.
-
There is demand for feature type tokens that can be processed and filtered with simple string comparisons, with URI expansions.
-
While JSON-FG can be used with additional JSON-LD annotations, it is a design goal to avoid normative dependencies on JSON-LD.
If JSON-LD is used, the “featureType” member can be mapped to “@type”.
-
-
This approach is similar to the approach taken by OGC API Records to identify the type of a record.
-
In a JSON-FG extension to OGC API Features (or maybe in the new part “Schemas”), the Collection resources should be extended to include (optional) information about the feature types and geometry types included the collection. There could be a recommendation for “featureType” and “geometryDimension” as queryables for such collections.
6.6.4. Open questions
The following question remains open:
-
Should there be a capability to distinguish between feature types that “just” identify a concept, but have no associated or no well-defined schema, and feature types that have an associated schema (the schema would be linked using a “describedby” link relation type)?
6.7. Identifying the schema(s)
6.7.1. Overview
A schema is metadata about a JSON document that clients can use to validate the JSON document or to derive additional information about the content of the JSON document, such as a textual description of the feature properties or their value range.
NOTE As of 2021, the OGC Features API Standards Working Group is working on a specification in the OGC API Features series for using JSON schemas to describe the schema of features.
The JSON-FG standard will provide guidance on how to include information about the schema of a JSON document that is a single feature or a feature collection.
6.7.2. Description
The JSON Schema specification [7] recommends to use a describedby link relation to the schema:
It is RECOMMENDED that instances described by a schema provide a link to a downloadable JSON Schema using the link relation “describedby” […].
OGC API Features already specifies a general “links” member with an array of link objects based on RFC 8288 (Web linking). Therefore, feature responses from APIs implementing OGC API Features will already include a “links” member. JSON-FG builds on this approach and includes a “describedby” link to a JSON Schema document, if schema information is important for the target users of the JSON feature documents.
Table 2 — Link properties
Property | Type | Description |
---|---|---|
href | URI | REQUIRED. The URI of a JSON Schema document that describes the JSON document that is the link context. |
rel | String | REQUIRED. The link relation type, which is always “describedby” for the link to the JSON Schema document. |
type | String | REQUIRED. To indicate that the target of the link is a JSON Schema document, set the value to “application/schema+json”. |
title | String | Include this link attribute for a human readable label of the link, e.g. for use in a derived HTML representation. |
An example of a link object:
{
"href": "https://demo.ldproxy.net/zoomstack/collections/airports/schema",
"rel": "describedby",
"type": "application/schema+json",
"title": "JSON Schema of this document"
}
Additional link attributes may be added to the Link object.
Each JSON-FG document is either a feature or a feature collection.
A feature collection document must contain a link to the JSON-FG feature collection schema at http://schemas.opengis.net/json-fg/1.0/FeatureCollection.json. If the document is also a GeoJSON feature collection, it must contain a link to the GeoJSON feature collection schema at https://geojson.org/schema/FeatureCollection.json. The document should also contain another link to a schema document that specifies the properties of the features in the collection.
A feature document must contain a link to the JSON-FG feature schema at http://schemas.opengis.net/json-fg/1.0/Feature.json. If the document is also a GeoJSON feature, it must contain a link to the GeoJSON feature schema at https://geojson.org/schema/Feature.json. The document should also contain another link to a schema document that specifies the properties of the feature.
NOTE These are canonical URIs. Clients can identify that a JSON document is a GeoJSON and JSON-FG feature collection or feature by string comparisons.
6.7.3. Discussion
The following aspects were discussed:
-
Some environments use a “$schema” member to reference the schema of a JSON document. However, that is not the approach recommended by the JSON Schema specification itself. In JSON Schema, the value of a “$schema” property is always the URI of a meta-schema.
The OGC API specification for feature schemas should support at least the following two types of schemas so that they can be referenced from JSON documents retrieved from an API:
-
The schema of a feature, and
-
The schema of a feature collection, which is basically a FeatureCollection object that references the feature schema.
This issue will be addressed by the Features API SWG (see issue #612). This topic was a topic in the November 2021 Code Sprint on OGC API Features and link relation types, relative API paths to the schema resources and JSON schema profiles were discussed.
-
6.7.4. Open questions
The following questions remain open:
-
The current JSON Schema version is 2020-12, which is also used in OpenAPI 3.1, but that version is not yet widely implemented. The JSON-FG schemas have been created using version 2019-09. Should schemas be published in multiple versions?
The current approach to signal to clients that the instance conforms to GeoJSON and/or JSON-FG is to link to the respective schemas. See the discussion in issue 10. There are at least two potential aspects that should be investigated:
-
The GeoJSON schemas are in draft 07 of JSON Schema and not available in the more recent versions 2019-09 or 2020-12. Many parsers seem to have issues with mixed schema versions. However, that is less of an issue, if the GeoJSON schemas, the JSON-FG schemas and the API-specific or community schemas are referenced separately and do not reference each other. This will still be an issue, if the schema of a particular feature type wants to reference, for example, the GeoJSON Point schema to constrain the geometries to points.
-
The status and persistence of the GeoJSON schemas is unclear.
The GeoJSON maintainers should be contacted by the SWG to discuss these topics.
-
-
The JSON-FG schema documents will only be published on schemas.opengis.net once the JSON-FG standard has been approved. Until then, the schema documents are available at https://raw.githubusercontent.com/opengeospatial/ogc-feat-geo-json/main/proposals/Feature.json and https://raw.githubusercontent.com/opengeospatial/ogc-feat-geo-json/main/proposals/FeatureCollection.json.
-
If features are accessed using building blocks from OGC API Features, a collection can be comprised of features with different feature types. The Features API SWG should include guidance in the Schema extension how to construct a feature schema for such a collection. Multiple options exist, including:
-
A schema using “oneOf” with one set of properties for each feature type;
-
A schema with a single properties object with the superset that all features conform to; and
-
A separate schema per feature type.
-
-
JSON Schema is a rich language and should be considered limiting the language constructs that should be used in describing the feature schema / profile. A potential starting point is the current proposal for a JSON Schema profile for queryable feature properties.
-
The schema of a feature type will typically specify the details of the feature properties, but it can also profile the top-level members including the “geometry”, “where” and “when” members. A typical example is to restrict the list of allowed geometry types. To simplify parsing the feature schemas it could be discussed, if canonical schemas for well-known types should be used in “$ref” members. For example, if the spatial geometry is restricted to points, the “geometry” and “where” members could reference https://geojson.org/schema/Point.json.
6.8. Encoding the primary temporal extent
6.8.1. Overview
Many features have a spatial geometry that provides information about the location of the feature. In GeoJSON, this information is encoded in the top-level “geometry” member. Features are also often associated with temporal information. In most cases this is either an instant (e.g., an event) or an interval (e.g., an activity or a temporal validity). In OGC API Features this is reflected in the datetime parameter for temporal filtering of features.
JSON-FG adds support for the most common case: Associating a feature with a single temporal instant or interval in the Gregorian calendar.
More complex cases and other temporal coordinate reference systems are out-of-scope for JSON-FG for now and might be specified in future extensions.
6.8.2. Description
Features can have temporal properties. These will typically be included in the “properties” member.
-
In many datasets all temporal properties are instants (a date or a timestamp) and intervals will be described using two temporal instants, one for the start and one for the end.
-
Multiple temporal properties are sometimes used to describe different temporal characteristics of a feature. For example, the time instant or interval when the information in the feature is valid (sometimes called “valid time”) and the time when the feature was recorded in the dataset (sometimes called “transaction time”). Another example is the Observations & Measurements standard, where an observation has multiple temporal properties including “phenomenon time”, “result time” and “valid time”.
Like GeoJSON, JSON-FG does not place constraints on the information in the “properties” member. JSON-FG specifies a new top-level JSON member in a feature object (key: “when”). The member describes a default temporal extent (an instant or an interval) that can be used by clients without a need to inspect the “properties” member or to understand the schema of the feature. Clients that are familiar with a dataset can, of course, inspect the information in the “properties” member instead of inspecting the “when” member.
The publisher of the data needs to decide which temporal feature properties are used in the “when” member.
The value of “when” is an object.
Table 3 — Properties of the “when” object
Property | Type | Description |
---|---|---|
instant |
string |
The temporal extent as an instant. See below for more details about instants. |
interval |
[ string ] |
The temporal extent as an interval, an array of two instants. See below for more details about intervals. |
If both values intersect it is valid to include both an instant and an interval. Clients should use the interval and may use the instant to determine the temporal extent of the feature.
The “when” object may be extended with additional members. Clients processing a “when” object must be prepared to parse additional members. Clients may ignore members that they do not understand. For example, in cases where the “when” member neither includes an “instant” or “interval”, a client may process the feature as a feature without a temporal extent.
NOTE The data publisher decides how temporal properties inside the “properties” member are encoded. The schema for the “when” member does not imply a recommendation that temporal feature properties reuse the same schema. For example, it is expected that a date-valued feature attribute will in most cases be represented as string with an RFC 3339 date value.
6.8.3. Instants
An instant is a value that conforms to RFC 3339 (Date and Time on the Internet: Timestamps) and is consistent with one of the following production rules of the ISO 8601 profile specified in the RFC:
-
full-date (e.g., "1969-07-20")
-
date-time (e.g., "1969-07-20T20:17:40Z")
Note that all timestamps have to include a time zone. The use of UTC is recommended (“Z”).
The JSON schema for an instant:
oneOf:
- type: string
format: date
- type: string
format: date-time
This describes the initial range of instant values. This range may be extended in the future to support additional use cases. Clients processing instant values must be prepared to receive other values. Clients may ignore values that they do not understand.
6.8.4. Intervals
An interval is described by the start and end instants. Both start and end instants are included in the interval.
Open ranges at the start or end are represented by a null value for the start/end.
type: array
minItems: 2
maxItems: 2
items:
oneOf:
- oneOf:
- type: string
format: date
- type: string
format: date-time
- null
This describes the initial range of interval values. This range may be extended in the future to support additional use cases. Clients processing interval values must be prepared to receive other values. Clients may ignore values that they do not understand.
6.8.5. Discussion
The following aspects were discussed:
-
The current specification of the “when” member could be extended with minimal extensions beyond the RFC 3339 timestamps to support additional use cases, but this would be left to a future extension:
-
Supporting instant values of a year (e.g., “1969”) or a month (e.g., “1967-07”) in addition to dates and timestamps could be useful for extents that cover a complete month or year.
-
Supporting instant values of the proleptic Gregorian calendar (i.e., dates before 1582 including negative years) could be useful for historic information.
-
An alternative interval encoding would be to use ISO 8601-1/8601-2 and represent intervals as a string, too, instead of an array. In this case, the value of “interval” would be encoded as:
-
"1969-07-16/1969-07-24"
-
"1969-07-16T05:32:00Z/1969-07-24T16:50:35Z"
-
"2019-10-14/.."
The main reason for the current design is that this is easier to parse. In a structured language like JSON it is natural to be explicit and use the structures. For example, GeoJSON does not represent the geometry as a WKT string, but as a JSON structure. The JSON encoding of the candidate Common Query Language (CQL2) standard also follows that approach for spatial and temporal geometries. Strings are used for instants (date and timestamp values according to RFC 3339), which are supported in most programming environments. However, any temporal type that is constructed from multiple instants uses JSON structures.
Another reason for the current design is that it can support additional temporal types in the future besides instants and intervals. An example is a time series with an array of timestamps.
-
-
The current proposal only specifies the use of “when” in the context of a feature. Other contexts could also be supported in the future. For example, a temporal extent for each geometry in a geometry collection or for properties where the value changes over time.
-
SpatioTemporal Asset Catalog (STAC) specifies a property datetime that is included in the “properties” member. This approach was not followed for two reasons:
-
Like the feature identifier and the default spatial geometry of a feature, the default temporal extent of a feature should be a “first-class” citizen in the JSON encoding of the feature.
-
The use of reserved property names might conflict with existing features that include a “datetime” property with a different specification.
-
-
Just as the STAC “datetime” property, “when” does not provide an indication of the semantics associated with the temporal information. One potential approach to provide hints to clients could be the use of a JSON-LD context to associate the “when” member with a property definition in some vocabulary.
-
Currently there is no information about the semantics of the temporal extent. Is it a temporal extent of a feature that is a version of a real-world entity and there are potential predecessor/successors features of the same entity? Or, in case of a bitemporal dataset, is it the valid time or the transaction/record time? Etc. It was decided to keep the JSON-FG simple and leave support for more complex requirements to extensions. Support for versioned feature data is one of the planned future work items of the Features API SWG.
6.8.6. Open questions
The following questions remain open:
-
For timestamps, the current proposal recommends the use of UTC. GeoPackage, the next versions of CDB and the Common Query Language will only support UTC as a time zone in literal values. Should JSON-FG follow this approach?
-
ISO 8601 also supports intervals by a duration (a start instant and the duration or the duration and an end instant). Should this also be supported or does that make parsing just more complex for clients?
-
There is an existing initiative for a temporal GeoJSON extension (“GeoJSON-T”). The proposal also uses “when” as a key, but with a different schema for the “when” object. The GeoJSON-T design supports more complex use cases that go beyond the scope of the proposal. To avoid confusion, the SWG should either use a different key than “when” or agree on a joint approach with the GeoJSON-T author (there should be support for simple instants/intervals as a minimal profile, additional capabilities would then extend that minimal profile).
6.9. Encoding the primary spatial geometry
6.9.1. Overview
Features typically have a spatial geometry that provides information about the location of the feature.
In GeoJSON, this information is encoded in the top-level “geometry” member. Geometries are according to the Simple Features Standard (2D or 2.5D points, line strings, polygons or aggregations of them) in WGS 84 as the coordinate reference system (OGC:CRS84 or OGC:CRS84h).
A key motivation for JSON-FG is to support additional requirements, including other CRSs as well as solids, where the boundary is specified using polygons.
To avoid confusing existing GeoJSON readers, such geometries will be provided in a new top-level member with the key “where” (or another key).
6.9.2. Description
The main spatial location of a feature is provided in the “geometry” and “where” members of the feature object. The value of both keys is an object representing a spatial geometry — or null.
The value of the “geometry” member is specified in the GeoJSON standard.
The value range of the “where” member is an extended and extensible version of the value range of the value range of the “geometry” member:
-
Is extended by the value options (additional JSON-FG geometry types Clause 6.9.2.3 and Clause 6.9.2.4) as well as by the capabilities to declare the coordinate reference system of the coordinates of the geometry.
-
Is extensible and future parts of Features and Geometries JSON or community extensions may specify additional members or additional geometry types. JSON-FG readers should be prepared to parse values of “where” that go beyond the schema that is implemented by the reader. Unknown members should be ignored and geometries that include an unknown geometry type should be mapped to null.
6.9.2.1. Use of “geometry” and/or “where”
If the geometry that describes the main geometry of the feature can be represented as a valid GeoJSON geometry (one of the GeoJSON geometry types, in WGS84), it is encoded as the value of the “geometry” member. The “where” member has the value null.
If the geometry cannot be represented as a valid GeoJSON geometry, it is encoded as the value of the “where” member. In addition, a valid GeoJSON geometry may be provided in the “geometry” member in the coordinate reference system WGS84 as specified in the GeoJSON standard (otherwise “geometry” is set to null). The geometry in “geometry” is a fallback for readers that support GeoJSON, but not JSON-FG. This could be a simplified geometry, like the building footprint in the example “building with a polyhedron geometry and the polygon footprint” instead of the solid geometry or the same point/line string/polygon geometry, but in WGS 84 (potentially with fewer vertices to reduce the file size).
NOTE The OGC Code Sprint in November 2021 discussed the API building blocks to request a fallback geometry in the “geometry” member or not. It was agreed that the default behavior is to omit the “geometry” member, if a “where” member is included. If a JSON-FG client wants to include the fallback geometry — typically, because the data will be published and shared with other users and tools — the requested media type should include a parameter compatibility=geojson (that is, the media type would be application/fg+json;compatibility=geojson). This approach was validated with two implementations.
6.9.2.2. Metrics
If the CRS uses axis order longitude and latitude, clients should perform geometrical computations — including computation of length or area on the curved surface that approximates the earth’s surface. Details are provided in the drafts of “Features and Geometry — Part 2: Metrics” [5].
Note that this differs from GeoJSON which states:
A line between two positions is a straight Cartesian line, the shortest line between those two points in the coordinate reference system. In other words, every point on a line that does not cross the antimeridian between a point (lon0, lat0) and (lon1, lat1) can be calculated as F(lon, lat) = (lon0 + (lon1 - lon0) * t, lat0 + (lat1 - lat0) * t) with t being a real number greater than or equal to 0 and smaller than or equal to 1. Note that this line may markedly differ from the geodesic path along the curved surface of the reference ellipsoid.
— GeoJSON (RFC 7946)
6.9.2.3. Polyhedron
A polyhedron is a non-empty array of multi-polygon arrays. Each multi-polygon array is a shell and must be closed. The first shell is the exterior boundary, all other shells are holes.
Example — JSON Schema for a polyhedron geometry
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"$id": "http://schemas.opengis.net/tbd/Polyhedron.json",
"title": "A polyhedron geometry",
"type": "object",
"required": [
"type",
"coordinates"
],
"properties": {
"type": {
"type": "string",
"enum": [
"Polyhedron"
]
},
"coordinates": {
"type": "array",
"minItems": 1,
"items": {
"type": "array",
"minItems": 1,
"items": {
"type": "array",
"minItems": 1,
"items": {
"type": "array",
"minItems": 4,
"items": {
"type": "array",
"minItems": 3,
"maxItems": 3,
"items": {
"type": "number"
}
}
}
}
}
},
"bbox": {
"type": "array",
"minItems": 6,
"maxItems": 6,
"items": {
"type": "number"
}
}
}
}
6.9.2.4. MultiPolyhedron
A multi-polyhedron is an array of polyhedron objects. The order of the polyhedron geometry objects in the array is not significant.
Example — JSON Schema for a multi-polyhedron geometry
{
"$schema": "https://json-schema.org/draft/2019-09/schema",
"$id": "http://schemas.opengis.net/tbd/MultiPolyhedron.json",
"title": "A multi-polyhedron geometry",
"type": "object",
"required": [
"type",
"coordinates"
],
"properties": {
"type": {
"type": "string",
"enum": [
"MultiPolyhedron"
]
},
"coordinates": {
"type": "array",
"items": {
"type": "array",
"minItems": 1,
"items": {
"type": "array",
"minItems": 1,
"items": {
"type": "array",
"minItems": 1,
"items": {
"type": "array",
"minItems": 4,
"items": {
"type": "array",
"minItems": 3,
"maxItems": 3,
"items": {
"type": "number"
}
}
}
}
}
}
},
"bbox": {
"type": "array",
"minItems": 6,
"maxItems": 6,
"items": {
"type": "number"
}
}
}
}
6.9.3. Discussion
The following aspect was discussed:
-
As of the writing of this ER, JSON-FG will not support multiple geometries per feature (note that multiple geometries can be included inside the “properties” member) or any hints about the semantics of the geometry. The latter could potentially be addressed using JSON-LD contexts where this is important.
-
The OGC Code Sprint in November 2021 also tested JSON-FG data with draft OGC API Features building blocks to access feature data suitable for display at a certain map scale / zoom level. This included API building blocks for simplifying geometries that are not points as well as filtering features that are typically not shown in maps at the scale or zoom level. This was validated with multiple implementations (a JSON-FG client and three OGC API Features servers).
6.9.4. Open questions
The following questions remain open:
-
Including information in some kind of ‘header’ would be helpful. This would support how a client should parse the content (as JSON-FG with its extensions, as standard GeoJSON, etc.), in particular, if the data is parsed as a file, not as an API response with a content type header.
-
Should a JSON Pointer be allowed in “where”, if “where” and “geometry” are the same geometry to reduce duplication?
-
Should a 3D geometry that represents a simple solid constructed using an extruded polygon also be supported? This would consist of a (horizontal) 2D polygon and separate attributes for the lower and upper limits. How often are such geometries used? With respect to “extruded polygons” it seems like they could be useful, but it is unclear if the added complexity of an additional geometry type is valuable enough. This is a broader topic as to how to handle geometries that are constructed using “regular” feature properties.
6.10. Encoding of reference systems
6.10.1. Overview
Without any other information, the following defaults apply in a JSON-FG file:
-
spatial coordinate reference system: OGC:CRS84 (2D) or OGC:CRS84h (3D)
-
temporal coordinate reference system: Gregorian
For asserting CRS information in a JSON-FG file:
-
The key coordRefSys is defined and can be used to assert a CRS at the collection, feature or value levels.
-
The value of the coordRefSys key can be:
-
a URI reference with an epoch,
-
or as an array of CRS references (with or without epoch) for an ad hoc compound CRS.
It is anticipated that if a CRS is asserted for a JSON-FG file, that assertion will be made at the top level of the document, either at the collection level or the feature level depending on the contents of the document.
NOTE The key was originally coord-ref-sys, but the naming style of keys was harmonized to consistently use lowerCamelCase. The implementations described in chapter Clause 7 have used the original key.
6.10.2. Description
Spatio-temporal objects are specified relative to some reference system.
GeoJSON (both the current RFC and the legacy version) fixed the reference system for geometric values to the “WGS84 datum, and with longitude and latitude units of decimal degrees”. The legacy version included a “prior arrangement” provision to allow other reference systems to be used and also defined the crs key for specifying the reference system. This prior arrangement mechanism survived into the RFC but the accompanying crs key did not. The result is that there is no interoperable way to unambiguously specify a different CRS if GeoJSON files and the safest thing to do is to stick with CRS84(h) for GeoJSON members and ignore the prior arrangement provision and the old crs key.
JSON-FG is not bound by these restrictions and so this document outlines a proposal for handling reference systems in JSON-FG documents that does not interfere with anything, past or present, defined in any of the GeoJSON specifications. The GeoJSON elements can continue to operate as always but JSON-FG elements can avail themselves of enhanced CRS support.
6.10.2.1. Reference system values
A reference system can be specified in a JSON-FG document using a coordRefSys member in one of three ways:
-
As a simple reference using a URI;
-
As a simple reference using a URI accompanied by an epoch value;
-
As an array of reference system values denoting an ad hoc compound reference system.
Used at the collection level, the coordRefSys key asserts the coordinate reference system for JSON-FG spatiotemporal values found anywhere in the document that are not otherwise tagged with closer-to-scope coordinate reference system information.
Used at the feature level, the coordRefSys key asserts the coordinate reference system for geometric JSON-FG value found anywhere in the feature that are not otherwise tagged with closer-to-scope coordinate reference system information.
Used at the geometry level, the coordRefSys key asserts the coordinate reference system for the geometry JSON-FG value within which the key is contained.
6.10.2.2. Value schema
The following JSON Schema fragment defines a reference system value:
The schema of a reference system value
{
"$defs": {
"refsysSimpleref": {
"type": "string",
"format": "uri"
},
"refsysByref": {
"type": "object",
"required": [ "href" ],
"properties": {
"href": {
"type": "string",
"format": "uri"
},
"epoch": {
"type": "string"
}
}
},
"refsys": {
"oneOf": [
{ "$ref": "#/$defs/refsysSimpleref" },
{ "$ref": "#/$defs/refsysByref" },
{
"type": "array",
"items": {
"oneOf": [
{ "$ref": "#/$defs/refsysSimpleref" },
{ "$ref": "#/$defs/refsysByref" },
]
}
}
]
}
},
"$ref": "#/$defs/refsys"
}
A simple reference system value by reference.
"http://www.opengis.net/def/crs/EPSG/0/3857"
A reference system value by reference and with an epoch.
{
"href": "http://www.opengis.net/def/crs/EPSG/0/4979",
"epoch": "2016.47"
}
A ad hoc compound reference system value
[
{
"href": "http://www.opengis.net/def/crs/EPSG/0/4258",
"epoch": "2016.47"
},
"http://www.opengis.net/def/crs/EPSG/0/7837"
]
6.10.3. Discussion
This ER only includes a summary of the CRS topic. The detailed description and discussion is part of the Features and Geometries JSON CRS Analysis of Alternatives Engineering Report [3].
6.11. Relationships and links
Features can have properties that are relationships with other features or resources like codelists, etc. There are multiple options for how to encode such relationships and JSON-FG could provide guidance for how to represent such relationships.
Relationships will often be direct properties of the feature, but they may also occur in embedded JSON objects.
Like all other properties, properties that are relationships may have a maximum multiplicity greater than one. That is, the JSON representation may be an array of relationships.
JSON-FG will not mandate a specific way to represent relationships and links in the feature object. There are, however, three basic patterns of how to represent relationships and links. Each pattern may or may not be applicable to the intended use of the data.
Pattern 1 seems best suited: If the intended use of the data benefits from a consistent place where links are included in the JSON document.
Pattern 2 seems best suited: If the JSON features should closely reflect the application schema of the features (in case a schema is available).
The same also applies to pattern 3, but this option seems mainly useful in combination with JSON-LD. Also, the information is not sufficient to render a useful HTML representation from the JSON representation without fetching the linked resources.
Depending on the data and how the data is expected to be used, the preferences of data publishers for one or the other pattern will vary.
6.11.1. Pattern 1: Add all relationships to a “links” member of the JSON object that is the link anchor
This option is consistent with the general approach used in the current OGC API standards. This option uses Web linking and a consistently named JSON member with an array of OGC API Link objects.
The semantics of the relationship / association role is expressed via the link relation type. Where possible, link relation types registered with IANA or OGC should be used, but the data publisher can also define their own link relation types. Note that this introduces overhead, because it requires minting persistent URIs for the link relation types. Where this is too much, an existing link relation type should be used and “related” could be used as a fallback.
6.11.2. Pattern 2: Encode links like other feature properties — using a simplified link object
This option treats the relationships like other properties and uses a simplified OGC API Link object without a “rel” attribute, since the semantics of the link is already expressed by the property.
A variation could be to require the use of a valid link relation type as the key of the JSON member, which would basically move the link relation type to a key to group all links with the same link relation type.
Another variation of this option would be to flatten the link objects.
Note that instead of using a Link object to reference the related resource, the related resource could also be embedded — at least as long as the referenced resource can be represented as a JSON object.
6.11.3. Pattern 3: Only use the URI
This option is similar to option 2, but the link objects are reduced to the href value. As a result, this option is more concise, but it lacks information that would be useful for the human (unless the URIs are dereferenced to fetch a label/title). In addition, since this approach does not use web linking according to RFC 8288, no link relation types for the links are available.
6.11.4. Discussion
The following aspects were discussed:
-
A GeoJSON feature that is encoded by a Web API implementing OGC API standards will often already include a “links” member with an array of OGC API Link objects. The OGC API Link object is a JSON implementation of web links according to RFC 8288. The OGC API Features standard currently only specifies requirements for links to resources in the API to support clients navigating the API.
Are links part of the resource or metainformation? There is a general, somewhat philosophical discussion topic related to links between resources.
In general, the links of a web resource are considered metainformation, and strictly the links do not have to be part of the cachable representations of the resource. RFC 8288 (Web linking) supports this by supporting that links are only represented as HTTP headers, outside of the representations. Changes to a link would not impact the ETag or Last-Modified headers of the resource.
The links in feature (collection) resources specified in OGC API Features (“self”, “alternate”, “next”, “collection”) or in JSON Schema (“describedby”) are a good example. A change in any of those links does not indicate a change in the resource itself, but it indicates a technical change in the implementation. For example, another alternate representation has been added or the schema has moved to a different URI.
However, because the OGC API standards include the links in the JSON representation — like most of the existing approaches to JSON-based Web APIs, a change in the links will also invalidate cached representations of the resource (and update the ETag and Last-Modified headers). A conscious decision is to include the links in the JSON representation. This approach seems to meet the expectations of developers today.
The same applies to many of the explicit or implicit relationships that are expressed in geospatial datasets today. Whether a second building is erected on the parcel or not does not really change the parcel. It could be argued that the relationship between the parcel and the building is metainformation and a change to a relation does not change the parcel — and should not invalidate any cached representations. Links between the resources could be managed — and accessed — as separate resources (e.g. linksets).
Nevertheless, many users and developers will prefer a more “traditional” way of sharing geospatial features with relationships included in the resource representation and the discussion below is based on this assumption.
-
An extension to CQL2 to properly support filtering links should be considered by the Features API SWG, too.
6.11.5. Open questions
The following question remains open:
-
Link relation types for the topological interval relationships as specified in OWL Time are already registered with IANA. The registration of the named spatial topological relationships specified in the Simple Feature Access standard [6] should be considered, either in the IANA or the OGC register. Such link relation types are useful for cases where relationships are pre-computed or are computed on the fly but are presented, because the clients cannot easily compute them.
6.12. Use in offline containers
6.12.1. Overview
This clause describes the work done in the OGC Feature and Geometries JSON thread of Testbed-17 that investigated the use of JSON-FG in offline containers.
For situations with intermittent or no network connectivity it can be necessary to create an offline container of the data of interest. Such a container allows the data to be pre-loaded onto a device and then used locally when the device is disconnected and thus has no network access.
Brief consideration was given to using a JSON-FG file itself as the offline container. However, the testbed participants felt that too many additional extensions beyond what is described in this ER would be required to accommodate all the information that typically accompanies feature data. Such accompanying information includes descriptive metadata, styling information, CRS definitions, etc. Unambiguously accommodating all this information in a single file would present a unique access pattern that would require specifically designed tools and would thus limit the use of existing OGC-aware tools to access the information in the container.
Geospatial data is often associated with coordinate system references and there often exist relationships between data items manifested as links in the data. Such CRS references and links to other resources require network connectivity and without it, other provisions need to be made in an offline container to satisfy such linking requirements.
6.12.2. File structure of an offline container
The original approach for creating an offline container was to reuse work previously done in the OWS-8 Testbed and described in the “OGC OWS-8 Bulk Geodata Transfer Using GML Engineering Report” (OGC 11-085r1). OGC 11-085r1 describes an offline container called a GBT file.
A GBT file is a ZIP archive that contains feature data encoded as GML. Accompanying the GML data are files describing the application schema of each GML file in the GBT and SLD files that contain styling information. The result of the OWS-8 work was two utilities named gbtexport and gbtimport. The gbtexport utility would read a source datastore and generate a GBT file. The gbtimport utility would read a GBT file and load it into a target datastore.
In the work done for Testbed 17, only the gbtexport utility was considered since the goal was to create an offline container and not necessarily reload the contents of that container into some other datastore; although that is certainly possible.
The following is a listing of the contents of the GBT file from OWS-8 created using the gbtexport utility:
Archive: foundation.gbt
Geodata Bulk Transfer (GBT) file of "foundation" data store, packaged on 2008-10-27.
Length Date Time Name
--------- ---------- ----- ----
3672595 10-27-2008 07:53 aerofacp_1m.gml
4690 10-27-2008 07:53 aerofacp_1m.xsd
1347 10-27-2008 07:53 aerofacp_1m.sld
37749241 10-27-2008 07:53 coastl_1m.gml
3389 10-27-2008 07:53 coastl_1m.xsd
1332 10-27-2008 07:53 coastl_1m.sld
1958 10-27-2008 07:53 ows-manifest.xml
--------- -------
41431873 5 files
The file structure is flat and the various files are associated using a manifest file, ows-manifest.xml. The manifest file was created according to the OGC Web Service Common Implementation Specification. Although this structure is suitable for the offline container use case, in 2021 it makes more sense to use a file structure that is more likely to be understood by current tools that access OGC feature data.
For Testbed 17, the code for the gbtexport utility was resurrected and modified to generate an offline container using JSON-FG as the primary means of encoding feature data. Like GBT, the offline container is a ZIP archive. The following is a sample listing of the contents of an offline container (i.e. ZIP archive) created using the updated gtbexport utility:
Archive: foundation.gbt
Geodata Bulk Transfer (GBT) file of "foundation" data store, packaged on 2021-10-13.
Length Date Time Name
--------- ---------- ----- ----
0 10-13-2021 20:07 collections/
0 10-13-2021 21:40 collections/coastl_1m/
44915138 10-13-2021 07:45 collections/coastl_1m/items.json
0 10-13-2021 19:18 collections/coastl_1m/schemas/
3693 10-13-2021 22:31 collections/coastl_1m/schemas/collection.json
2392 10-13-2021 19:17 collections/coastl_1m/schemas/feature.json
0 10-13-2021 19:18 collections/coastl_1m/metadata/
0 10-13-2021 19:18 collections/coastl_1m/metadata/iso19115.xml
0 10-13-2021 21:40 collections/coastl_1m/styles/
0 10-13-2021 21:43 collections/aerofacp_1m/
5019561 10-13-2021 20:06 collections/aerofacp_1m/items.json
0 10-13-2021 19:20 collections/aerofacp_1m/schemas/
3031044 10-13-2021 07:51 collections/aerofacp_1m/schemas/collection.json
1576 10-13-2021 19:20 collections/aerofacp_1m/schemas/feature.json
0 10-13-2021 19:15 collections/aerofacp_1m/metadata/
0 10-13-2021 06:42 collections/aerofacp_1m/metadata/iso19115.xml
0 10-13-2021 21:43 collections/aerofacp_1m/styles/
4098 10-13-2021 20:09 collections.json
--------- -------
52977502 18 files
NOTE 1 The ISO metadata files in this example are just placeholders to illustrate how associated metadata is included in the offline container. As such, their size is 0 bytes.
Anyone familiar with the OGC API — Features — Part 1: Core specification will recognize the file structure presented above; it mirrors the path structure of the OGC resource tree with some extensions to handle other associated resources such as metadata and/or styles.
NOTE 2 The original intent was to absorb the capabilities of the gbtexport utility into the CubeWerx OGC API Features server. The offline container would simply be another output format supported by the server. However, the current inability to simultaneously request features from multiple collections through the API and constraints on time and resources limited the scope of work to updating the existing code for the gbtexport utility.
6.12.3. The manifest
The original GBT file from OWS-8 contained an ows-manifest.xml file that listed all the files in the archive. In TB17 the role of manifest is now played by the collections.json file. The following JSON document illustrates the contents of the collections.json file:
Example — Sample collection.json file from an offline container
{
"title": "foundation GBT",
"description": "Geodata Bulk Transfer (GBT) file of the \"foundation\" data store, packaged on 2021-10-13.",
"refSystems": {
"CRS84": {
"valueType": "ogcwkt",
"value": "GEOGCS[\"WGS 84\",DATUM[\"WGS_1984\",SPHEROID[\"WGS 84\", 6378137, 298.257223563]],PRIMEM[\"Greenwich\", 0],UNIT[\"degree\", 0.0174532925199433],AUTHORITY[\"EPSG\", \"4326\"]]"
}
},
"collections": [
{
"itemType": "feature",
"id": "aerofacp_1m",
"title": "Airport Facilities Points",
"description": "VPF Narrative Table for \"Airport Facilities Points\":\n\nInformation on airports/airfields (GB005) was derived from the DAFIF (Digital Aeronautical Flight Information File) and TINT (Target Intelligence) in areas where such data was available. Each airfield's DAFIF reference number was placed in the 'na3' (classification name) attribute field. Only airfields which had at least one hard surface runway longer that 3,000 feet (910 meters) were collected.\n",
"nFeatures": 9335,
"links": [
{
"href": "collections/aerofacp_1m/items.json",
"rel": "items",
"type": "application/vnd.ogc.fg+json",
"title": "the vector features of this collection as OGC Features & Geometries JSON"
},
{
"href": "collections/aerofacp_1m/schemas/collection.json",
"rel": "http://www.opengis.net/def/rel/ogc/0.0/schema-collection",
"title": "the schema of this collection",
"type": "application/schema+json"
},
{
"href": "collections/aerofacp_1m/schemas/feature.json",
"rel": "http://www.opengis.net/def/rel/ogc/0.0/schema-item",
"title": "the schema of feature instances of this collection",
"type": "application/schema+json"
},
{
"href": "collections/aerofacp_1m/metadata/iso19115.json",
"rel": "describedby",
"title": "ISO19115 metadata describing this collection",
"type": "application/xml"
}
],
"extent": {
"spatial": {
"bbox": [
[
-179.878326416016,
-54.9311103820801,
179.339859008789,
79.52944183349609
]
],
"crs": "#/refSystems/CRS84"
}
},
"crs": [
"#/refSystems/CRS84"
]
},
{
"itemType": "feature",
"id": "coastl_1m",
"title": "Coastlines",
"description": "VPF Narrative Table for \"Coastlines\":\n\nCoastline/shorelines (BA010) have been portrayed for coastal islands but not inland islands.\n",
"nFeatures": 36371,
"links": [
{
"href": "collections/coastl_1m/items.json",
"rel": "items",
"type": "application/vnd.ogc.fg+json",
"title": "the vector features of this collection as OGC Features & Geometries JSON"
},
{
"href": "collections/coastl_1m/schemas/collection.json",
"rel": "http://www.opengis.net/def/rel/ogc/0.0/schema-collection",
"title": "the schema of this collection"
},
{
"href": "collections/coastl_1m/schemas/feature.json",
"rel": "http://www.opengis.net/def/rel/ogc/0.0/schema-item",
"title": "the schema of feature instances of this collection"
},
{
"href": "collections/coastl_1m/metadata/iso19115.json",
"rel": "describedby",
"title": "ISO19115 metadata describing this collection",
"type": "application/xml"
}
],
"extent": {
"spatial": {
"bbox": [
[
-179.999420166016,
-85.582763671875,
179.9999,
83.62741851806639
]
],
"crs": "#/refSystems/CRS84"
}
},
"crs": [
"#/refSystems/CRS84"
]
}
],
"links": [
{
"href": "collections.json",
"rel": "self",
"type": "application/json",
"title": "this page of collections as JSON"
}
]
}
The collections.json file is based on the structure of the collections object from OGC API — Features with some additions. Specifically, the nFeatures member is added to include a count of the number of features in the collection and the refSystems member is added as a dictionary of CRSs used in the file. All CRS references are to this local dictionary.
NOTE See CRS Consideration.
6.12.4. Feature data
Each feature collection included in an offline container is encoded as a JSON-FG file with the fixed name items.json. The items.json file is located in the collections/{collectionId} directory (e.g.: collections/coastl_1m/items.json) of the offline container.
Each feature collection file is created as specified in this document with modifications to handle CRS references as described in the OGC Testbed-17 Features and Geometries JSON CRS Analysis of Alternatives ER [3].
{
"type": "FeatureCollection",
"timeStamp": "2021-10-25T22:06:27-04:00",
"numberMatched": 36372,
"numberReturned": 36372,
"refSystems": {
"CRS84": {
"valueType": "ogcwkt",
"value": "GEOGCS[\"WGS 84\",DATUM[\"WGS_1984\",SPHEROID[\"WGS 84\", 637813
7, 298.257223563]],PRIMEM[\"Greenwich\", 0],UNIT[\"degree\", 0.0174532925199433]
,AUTHORITY[\"EPSG\", \"4326\"]]"
}
},
"coordRefSys": "#/refSystems/CRS84",
"bbox": [
-179.999420166016,
-85.582763671875,
179.9999,
83.62741851806639
],
"links": [
{
"href": "items.json",
"rel": "self",
"type": "application/vnd.ogc.fg+json; charset=utf-8"
},
{
"href": "schemas/collection.json",
"rel": "describedby",
"type": "application/schema+json; charset=utf-8"
}
],
"features": [
{
"type": "Feature",
"featureType": "coastl_1m",
"id": "CWFID.COASTL_1M.0.0",
"geometry": {
"type": "LineString",
"coordinates": [ ... ]
},
"where": null,
"properties": {
"id": 4671,
"f_code": "BA010",
"acc": 2,
"exs": 44,
"tile_id": 730,
"edg_id": 9
}
},
.
.
.
]
}
Sample items.json file from an offline container
By default the gbtexport utility will copy all features from a source collection into the offline container. However, the gbtexport utility accepts parameters that allow spatial, temporal and/or scalar predicates to be specified to define a subset of features to be copied to the offline container.
6.12.5. Coordinate reference system references
As specified in the Encoding of reference systems clause, CRS information is asserted in a JSON-FG file using the coordRefSys key. The value of the coordRefSys key is a URI. Usually, this URI points to the definition of the CRS. In an intermediate or no connectivity environment such CRS URIs cannot be resolved.
In order to make CRS URIs resolvable, the gbtexport utility includes a dictionary of CRSs at the head of each JSON-FG file using the refSystems member discussed in the OGC Testbed-17 Features and Geometries JSON CRS Analysis of Alternatives ER [3] and then rewrites all remote CRS references in the JSON-FG file to be local reference to the corresponding entry in the dictionary. The following JSON fragment illustrates the use of the refSystems member:
{
"type": "FeatureCollection",
"timeStamp": "2021-10-25T22:06:27-04:00",
"numberMatched": 36372,
"numberReturned": 36372,
"refSystems": {
"CRS84": {
"valueType": "ogcwkt",
"value": "GEOGCS[\"WGS 84\",DATUM[\"WGS_1984\",SPHEROID[\"WGS 84\", 637813
7, 298.257223563]],PRIMEM[\"Greenwich\", 0],UNIT[\"degree\", 0.0174532925199433]
,AUTHORITY[\"EPSG\", \"4326\"]]"
}
},
"coordRefSys": "#/refSystems/CRS84",
.
.
.
}
Consideration: Because many clients have built-in knowledge about common CRSs, such as CRS84, an open question is whether or not this refSystems mechanism for converting remote CRS references to local CRS references is of value.
6.12.6. Schemas
For the purpose of validation each feature collection included in the offline container may be accompanied by a JSON Schema file that declares the schema of the collection and the schema for a feature instance. The schema file for the collection is named collection.json. The schema file for feature instances is named feature.json. Both files are located in the collections/{collectionsId}/schemas directory. The Identifying the schema(s) clause describes how to reference these schemas within a JSON-FG file.
6.12.7. Relationships and links
The Relationships and links clause describes patterns for linking features to other features and other resources. Since an offline container is meant to be used in an intermittent or no connectivity environment, such references will break. In order to make such links resolvable, the resources being references need to be copied into the offline container and all remote references need to be rewritten into local references.
Consider the case where collection A includes features that reference features from collection B. If collection A is copied into an offline container then collections B also needs to be copied into the offline container. However, only instances of B necessary to resolve references from instances of A need to be included in the offline container. Furthermore, all link in instances of A that references instances of B need to be rewritten to reference the local copies of B.
NOTE The gdbexport utility was updated to handle the resolution of feature references but not references to other resources (e.g. code lists). Also, because of time, resource and data constrains this capability could not be tested during the testbed.
6.12.8. gbtexport utility
The gbtexport utility was created for OWS-8 and was modified for Testbed 17. The utility generates an offline container as a ZIP archive with a file structure that mirrors the OGC API resource tree structure. The following is the argument list for the gbtexport utility:
BT (Geodata Bulk Transfer) exporter, version 9.3.63
Copyright © 1997-2021 CubeWerx Inc.
Usage: gbtexport keyword=value ... (or) -keyword value ... -boolflag
KEYWORD ABB DESCRIPTION DEFAULT
--------- --- -------------------------------------------------- -------
PATH U address of data store to export (REQUIRED) (none)
DRIVER D data-store format type (auto)
FSET F feature set(s) of data store to export (all)
SQLFILTER SQL SQL filter(s), parallel to FSET(s) (none)
WINDOW bounding box to export (minX,minY,maxX,maxY) (all)
WINDOWCS coordinate system of bounding box (auto)
FROMDATE from date/time (YYYY-MM-DD HH:mm:ss) -INF
TODATE to date/time (YYYY-MM-DD HH:mm:ss) INF
LAYERS boolean - export corresponding layers as well? TRUE
SLDVERSION version of SLD to use if LAYERS=TRUE (auto)
PACK boolean - generate space-efficient XML or JSON? TRUE
TITLE T title of GBT file (auto)
ABSTRACT A abstract of GBT file (auto)
OUTFILE O path of GBT file to generate (auto)
RESOLVEREF R resolve references to other features (FALSE)
REFLEVEL RL number of level of indirection (1)
ZIPCOMMAND full path to the zip command (auto)
ZIPLEVEL compression level (0=none ... 9=max) 6
VERBOSITY VB verbosity level: 0=quiet, 1=normal, 2+=more detail 1
CHECKONLY boolean - don't export; merely do integrity checks FALSE
LOGFILE LOG file to write logging information to (none)
(also: convert-library hints and XML-generation hints)
The following table defines the parameters relevant to the work done in Testbed 17:
Table 4
Parameter Name | Description |
---|---|
FSET | a comma-separated list of feature collections to copy to the offline container |
SQLFILTER | a scalar SQL filter expression for defining a subset of features to copy to the offline container |
WINDOW | equivalent to the bbox parameter |
WINDOWCS | equivalent to the bbox-crs parameter |
FROMDATE/TODATE | equivalent to the datetime parameter |
OUTFILE | name of the offline container |
% gbtexport foundation/foundation fset=aerofacp_1m,coastl_1m
Simple invocation of the gbtexport utility
6.12.9. Future work
The following topics could be addressed in future initiatives:
-
The work in Testbed 17 was limited to features. However, there is no reason why other OGC resource types (e.g. map or vector tiles) could not be included in the offline container as well.
-
Link resolution is limited to relationships between features. Links to other resources (e.g. code lists) could also be handled.
-
Testing on a mobile device.
7. Implementations
This chapter describes the server and client implementations.
7.1. Overview
Three server and three client implementations with support for JSON-FG extensions were implemented as deliverables in Testbed-17.
Servers:
-
D100 Features and Geometries JSON Server for Aviation (interactive instruments)
-
D101 Features and Geometries JSON Server for Aviation (Skymantics)
Clients:
-
D102 Features and Geometries JSON Client for Aviation (Hexagon)
-
D103 Features and Geometries JSON Client for Aviation (Ecere)
Ecere also implemented support for JSON-FG in its server component as an in-kind contribution.
Each component implementation is described in a section in this chapter. In addition to the description of the component and any issues encountered or lessons learned during the implementation, each server section also describes the JSON-FG options that are supported with examples. Each client section also describes the JSON-FG options that are supported and used by the client as well as the TIEs executed with the server components.
7.2. Technology Integration Experiments (TIEs)
The following eight functional tests were executed between each client-server pair. Two of the tests were optional, depending on the capabilities of the clients and servers.
Table 5
All mandatory TIEs were successfully completed. The following table provides an overview of the executed and successful TIEs:
Table 6
Server / Client | D116 GeoSolutions | D103 Ecere | D102 Hexagon |
---|---|---|---|
D100 interactive instruments | 8/8 | 8/8 | 6/8 |
D101 Skymantics | 8/8 | 8/8 | 6/8 |
D115 CubeWerx | 8/8 | 8/8 | 6/8 |
GeoSolutions also demonstrated a successful TIE visualizing JSON-FG provided by the Ecere server.
More details about the TIE results for each client are included in the description of each client.
7.3. D100 Features and Geometries JSON Server for Aviation (interactive instruments)
Deliverable D100 was implemented by interactive instruments. The component also represents deliverable D104 from the Testbed-17 Aviation API task. The component and its four APIs are described in detail in the Aviation API Engineering Report [4]. This section only describes the JSON-FG extensions implemented by the server.
A JSON-FG document can be requested from the server using the media type application/vnd.ogc.fg+json or the f query parameter with the value “jsonfg”.
The following figure shows the HTML representation of a Notice to Airmen (NOTAM) and the corresponding JSON-FG representation.