Published

OGC Engineering Report

OGC Testbed-17: OGC Features and Geometries JSON Engineering Report
Clemens Portele Editor
OGC Engineering Report

Published

Document number:21-017r1
Document type:OGC Engineering Report
Document subtype:
Document stage:Published
Document language:English

License Agreement

Permission is hereby granted by the Open Geospatial Consortium, (“Licensor”), free of charge and subject to the terms set forth below, to any person obtaining a copy of this Intellectual Property and any associated documentation, to deal in the Intellectual Property without restriction (except as set forth below), including without limitation the rights to implement, use, copy, modify, merge, publish, distribute, and/or sublicense copies of the Intellectual Property, and to permit persons to whom the Intellectual Property is furnished to do so, provided that all copyright notices on the intellectual property are retained intact and that each person to whom the Intellectual Property is furnished agrees to the terms of this Agreement.

If you modify the Intellectual Property, all copies of the modified Intellectual Property must include, in addition to the above copyright notice, a notice that the Intellectual Property includes modifications that have not been approved or adopted by LICENSOR.

THIS LICENSE IS A COPYRIGHT LICENSE ONLY, AND DOES NOT CONVEY ANY RIGHTS UNDER ANY PATENTS THAT MAY BE IN FORCE ANYWHERE IN THE WORLD. THE INTELLECTUAL PROPERTY IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT OF THIRD PARTY RIGHTS. THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE DO NOT WARRANT THAT THE FUNCTIONS CONTAINED IN THE INTELLECTUAL PROPERTY WILL MEET YOUR REQUIREMENTS OR THAT THE OPERATION OF THE INTELLECTUAL PROPERTY WILL BE UNINTERRUPTED OR ERROR FREE. ANY USE OF THE INTELLECTUAL PROPERTY SHALL BE MADE ENTIRELY AT THE USER’S OWN RISK. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR ANY CONTRIBUTOR OF INTELLECTUAL PROPERTY RIGHTS TO THE INTELLECTUAL PROPERTY BE LIABLE FOR ANY CLAIM, OR ANY DIRECT, SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING FROM ANY ALLEGED INFRINGEMENT OR ANY LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR UNDER ANY OTHER LEGAL THEORY, ARISING OUT OF OR IN CONNECTION WITH THE IMPLEMENTATION, USE, COMMERCIALIZATION OR PERFORMANCE OF THIS INTELLECTUAL PROPERTY.

This license is effective until terminated. You may terminate it at any time by destroying the Intellectual Property together with all copies in any form. The license will also terminate if you fail to comply with any term or condition of this Agreement. Except as provided in the following sentence, no such termination of this license shall require the termination of any third party end-user sublicense to the Intellectual Property which is in force as of the date of notice of such termination. In addition, should the Intellectual Property, or the operation of the Intellectual Property, infringe, or in LICENSOR’s sole opinion be likely to infringe, any patent, copyright, trademark or other right of a third party, you agree that LICENSOR, in its sole discretion, may terminate this license without any compensation or liability to you, your licensees or any other party. You agree upon termination of any kind to destroy or cause to be destroyed the Intellectual Property together with all copies in any form, whether held by you or by any third party.

Except as contained in this notice, the name of LICENSOR or of any other holder of a copyright in all or part of the Intellectual Property shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Intellectual Property without prior written authorization of LICENSOR or such copyright holder. LICENSOR is and shall at all times be the sole entity that may authorize you or any third party to use certification marks, trademarks or other special designations to indicate compliance with any LICENSOR standards or specifications. This Agreement is governed by the laws of the Commonwealth of Massachusetts. The application to this Agreement of the United Nations Convention on Contracts for the International Sale of Goods is hereby expressly excluded. In the event any provision of this Agreement shall be deemed unenforceable, void or invalid, such provision shall be modified so as to make it valid and enforceable, and as so modified the entire Agreement shall remain in full force and effect. No decision, action or inaction by LICENSOR shall be construed to be a waiver of any rights or remedies available to it.

None of the Intellectual Property or underlying information or technology may be downloaded or otherwise exported or reexported in violation of U.S. export laws and regulations. In addition, you are responsible for complying with any local laws in your jurisdiction which may impact your right to import, export or use the Intellectual Property, and you represent that you have complied with any regulations or registration procedures required by applicable law to make this license enforceable.



I.  Abstract

The OGC Testbed-17 Features and Geometries JSON task investigated proposals for how feature data could be encoded in JSON so that:

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:

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:

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:

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:

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):

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:

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:

Testbed-17 participants were tasked to support the work of the SWG and in addition to also look into the following topics:

5.  Scenario

The following general scenarios are useful in understanding the principles that have been used in the JSON-FG design:

  1. 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.

  2. 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.4.  Requirements classes

The following is a proposal of how to aggregate the JSON-FG extensions into requirements classes:

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.3.  Discussion

The following aspects were discussed:

  1. 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”.

  2. This approach is similar to the approach taken by OGC API Records to identify the type of a record.

  3. 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:

  1. 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

PropertyTypeDescription
hrefURIREQUIRED. The URI of a JSON Schema document that describes the JSON document that is the link context.
relStringREQUIRED. The link relation type, which is always “describedby” for the link to the JSON Schema document.
typeStringREQUIRED. To indicate that the target of the link is a JSON Schema document, set the value to “application/schema+json”.
titleStringInclude 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:

  1. 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.

  2. 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:

  1. 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?

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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

PropertyTypeDescription
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:

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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:

  1. 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?

  2. 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?

  3. 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:

  1. 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.

  2. 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:

  1. 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.

  2. Should a JSON Pointer be allowed in “where”, if “where” and “geometry” are the same geometry to reduce duplication?

  3. 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:

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.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.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 NameDescription
FSETa comma-separated list of feature collections to copy to the offline container
SQLFILTERa scalar SQL filter expression for defining a subset of features to copy to the offline container
WINDOWequivalent to the bbox parameter
WINDOWCSequivalent to the bbox-crs parameter
FROMDATE/TODATEequivalent to the datetime parameter
OUTFILEname 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:

Clients:

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

#FunctionDescriptionClient ActionServer ResponseSuccess Criterion
1Landing PageRequest, receive, parse landing pageForm landing page request, parse response, display and/or act on itReceive landing page request, response with accepted / requested format (f=json, html)Client displays API “data” link and/or navigates to it
2CollectionsRequest, receive, parse array of collection objects in Collections documentFollow “data” link in landing page and receive / parse / display Collections documentReceive URL dereference from client, return Collections documentClient displays in menu and/or map form the Collections document and constituent collections
3Detect JSON-FGNegotiate JSON-FG media type for the items resource (“rel” : “items”), either by selecting a link with “type” set to application/vnd.ogc.fg+json, or using HTTP content negotiation mechanism.Follow/detect JSON-FG “items” link on the Collections pageProvide the link for JSON-FG items in the Collections endpointClient is able to select a JSON-FG representation
4CoordRefSysClient is able to parse the new property coord-ref-sys inside the JSON-FG collectionThe property coord-ref-sys should be taken into account in the rendering/visualization process once the JSON-FG collection is imported in the clientAdd the coord-ref-sys property inside the collection when requiredClient is able to parse the coord-ref-sys property
5WhereClient is able to parse the new property where inside the JSON-FG feature, or the equivalent GeoJSON geometry when a where property is not useful (i.e. geometry types supported by GeoJSON in CRS84)The property where (or geometry) should be taken into account in the rendering/visualization process once each feature of the JSON-FG collection is imported in the clientAdd the where property inside the feature when applicableClient is able to decide how to use the where (or geometry) property based on its own rendering environment
6WhenClient is able to parse the new property when inside the JSON-FG featureThe property when should be taken into account in the rendering/visualization process once each feature of the JSON-FG collection is imported in the clientAdd the when property inside the feature if the feature has information related to date/timeClient is able to read the when and render it (some examples: filter client side, filter server side, display when values in a chart, display the when values in a json, …​)
7Schemas / Metadata (optional)Client uses one of the endpoints that provides information about the attributes and use them in the rendering phase (queryables, schema-item, schema-collection)Client reads the attributes information from one of the provided endpointsServer exposes endpoints related to attributesClient is able to use the attributes value in the rendering phase (some examples: use attribute as upper lower limit of the 3d volume, use the attributes to apply a style, …​)
8CRS (optional)Collect all the available CRSs related to a selected collectionParse all the available CRSs of the collectionProvide available CRSs for the collectionsClient is able to parse/collect all the available CRSs

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/88/86/8
D101 Skymantics 8/88/86/8
D115 CubeWerx 8/88/86/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.