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

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:

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

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.

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

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.

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

{
  "$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"
      }
    }
  }
}

{
  "$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.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 simple URI reference,

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

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.

   {
      "$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"
   }

"http://www.opengis.net/def/crs/EPSG/0/3857"

{
  "href": "http://www.opengis.net/def/crs/EPSG/0/4979",
  "epoch": "2016.47"
}

[
  {
    "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.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:

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

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

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

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

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.

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.

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.

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

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