Open Geospatial Consortium

Submission Date: <yyyy-mm-dd>

Approval Date:   <yyyy-mm-dd>

Publication Date:   <yyyy-mm-dd>

External identifier of this OGC® document: http://www.opengis.net/doc/IS/json-fg-1/0.2

Internal reference number of this OGC® document:    21-045

Version: 0.2.2

Category: OGC® Implementation Standard

Editor:   Clemens Portele, Panagiotis (Peter) A. Vretanos

OGC Features and Geometries JSON - Part 1: Core

Copyright notice

Copyright © 2023 Open Geospatial Consortium

To obtain additional rights of use, visit https://www.ogc.org/legal/

Warning

This document is not an OGC Standard. This document is distributed for review and comment. This document is subject to change without notice and may not be referred to as an OGC Standard.

Recipients of this document are invited to submit, with their comments, notification of any relevant patent rights of which they are aware and to provide supporting documentation.

Document type:    OGC® Standard

Document subtype:    if applicable

Document stage:    Draft

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.

Table of Contents

i. Abstract

GeoJSON is a very popular encoding for feature data. GeoJSON is widely supported, including in most deployments of APIs implementing the OGC API Features Standard. However, GeoJSON has intentional restrictions that prevent or limit its use in certain geospatial application contexts. For example, GeoJSON is restricted to WGS 84 coordinates, does not support volumetric geometries and has no concept of classifying features according to their type.

OGC Features and Geometries JSON (JSON-FG) is a proposal for GeoJSON extensions that provide standard ways to support such requirements. The goal is to focus on capabilities that may require some geospatial expertise, but that are useful for many. Edge cases are considered out-of-scope of JSON-FG.

Since JSON-FG specifies extensions to GeoJSON that conform to the GeoJSON standard, valid JSON-FG features or feature collections are also valid GeoJSON features or feature collections.

The Open Geospatial Consortium (OGC) invites organisations and developers that have a need for the extensions specified by this specification to implement and test the extensions. Please submit feedback in the GitHub repository of the specification. Are these extensions useful for your use cases? Are they simple enough to implement?

Note
There are a number of open issues under discussion at the time of the release of this draft (version 0.2). Notes in this document link to related issues in the GitHub repository.

Uptake in implementations and sufficient feedback from implementation experience will be a prerequisite for this specification to eventually progress towards an OGC Standard.

Caution
This is a DRAFT. The technical requirements specified in this document can change in future versions.

ii. Keywords

The following are keywords to be used by search engines and document catalogues.

ogcdoc, OGC document, JSON, JSON-FG, GeoJSON, feature, geometry

iii. Preface

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent rights. The Open Geospatial Consortium shall not be held responsible for identifying any or all such patent rights.

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the standard set forth in this document, and to provide supporting documentation.

iv. Security Considerations

The security considerations for GeoJSON as specified in Section 10 of IETF RFC 7946 also apply to JSON-FG.

v. OGC Considerations

If and once the JSON-FG Standard is approved by the OGC Members, the following actions need to be taken by OGC before publication:

The following actions need to be taken after publication:

  • OGC will register the media type application/fg+json specified in Clause Media Types with IANA.

This section will be removed before the JSON-FG Standard is published.

vi. Submitting organizations

The following organizations submitted this Document to the Open Geospatial Consortium (OGC):

  • CubeWerx

  • Esri

  • Geonovum

  • interactive instruments

vii. Submitters

All questions regarding this submission should be directed to the editor or the submitters:

Name

Affiliation

Clemens Portele (editor)

interactive instruments

Panagiotis (Peter) A. Vretanos (editor)

CubeWerx

Linda van den Brink

Geonovum

Satish Sankaran

Esri

1. Scope

The OGC Features and Geometries JSON (JSON-FG) Standard extends the GeoJSON format to support a limited set of additional capabilities that are out-of-scope for GeoJSON, but that are important for a variety of use cases involving feature data.

The JSON-FG Standard specifies the following minimal extensions to the GeoJSON format:

  • The ability to use Coordinate Reference Systems (CRSs) other than WGS 84 (OGC:CRS84);

  • The ability to use non-Euclidean metrics, in particular ellipsoidal metrics;

  • Support for solids and prisms as geometry types;

  • The ability to encode temporal characteristics of a feature; and

  • The ability to declare the type and the schema of a feature.

Geographic features, their properties, and their spatial extents that can be represented as GeoJSON objects are encoded as GeoJSON. Additional information not specified in the GeoJSON RFC is mainly encoded in additional members of the GeoJSON objects. The additional members use keys that do not conflict with existing GeoJSON keys. This was done so that existing and future GeoJSON clients can continue to successfully parse and understand GeoJSON encoded content. JSON-FG enabled clients will also be able to parse and understand the additional members.

JSON Schema is used to formally specify the JSON-FG syntax.

2. Conformance

This Standard defines three requirements classes. JSON documents are the standardization target for all requirements classes.

The requirements classes are:

  • "Core": The Core conformance class extends GeoJSON with additional members that specify how Temporal information, extended Geometry information and Reference systems information can be encoded in a JSON-FG document. In addition, Metadata is added to declare the JSON-FG conformance classes that the JSON document conforms to. The Core conformance class has a dependency on GeoJSON. This means that a JSON-FG document that conforms to Core must also conform to GeoJSON.

  • "3D": The 3D conformance class adds support for Polyhedron, MultiPolyhedron, Prism, and MultiPrism geometries in a 3D CRS. The 3D conformance class has a dependency on the Core conformance class. This means that a JSON-FG document that conforms to the 3D conformance class must also conform to the Core conformance class.

  • "Feature Types and Schemas": The Feature Types and Schemas conformance class adds support for Feature types and Feature schemas. Features are often categorized by type. This requirements class adds members to a JSON-FG document so that contained features can be tagged with a type value. This conformance class includes guidance about how to include information about the feature schema in a JSON-FG document. The Feature Types and Schemas conformance class has a dependency on the Core conformance class. This means that a JSON-FG document that conforms to the Feature Types and Schemas conformance class must also conform to the Core conformance class.

JSON documents must, at a minimum, conform to the Core requirements class in order to use the JSON-FG media type.

Conformance with the JSON-FG Standard shall be checked using all the relevant tests specified in Annex A (normative) of this document. The framework, concepts, and methodology for testing, and the criteria to be achieved to claim conformance are specified in the OGC Compliance Testing Policies and Procedures and the OGC Compliance Testing web site.

In order to conform to this OGC® Standard, a software implementation shall choose to implement one or more of the conformance levels specified in Annex A (normative).

All requirements-classes and conformance-classes described in this document are owned by the Standard(s) identified.

3. References

The following normative documents contain provisions that, through reference in this text, constitute provisions of this document. For dated references, subsequent amendments to, or revisions of, any of these publications do not apply. For undated references, the latest edition of the normative document referred to applies.

Internet Engineering Task Force (IETF). RFC 3339: Date and Time on the Internet: Timestamps. Edited by G. Klyne, C. Newman. 2002. Available at https://www.rfc-editor.org/rfc/rfc3339.html

Internet Engineering Task Force (IETF). RFC 7946: The GeoJSON Format. Edited by H. Butler, M. Daly, A. Doyle, S. Gillies, S. Hagen, T. Schaub. 2016. Available at https://www.rfc-editor.org/rfc/rfc7946.html

Open Geospatial Consortium (OGC). OGC 06-103r4: OpenGIS® Implementation Standard for Geographic information - Simple feature access - Part 1: Common architecture. Edited by J. Herring. 2011. Available at https://portal.opengeospatial.org/files/?artifact_id=25355

Open Geospatial Consortium (OGC). OGC API - Features - Part 5: Schemas 1.0 (DRAFT). Edited by C. Portele, P. Vretanos. Available at https://docs.ogc.org/DRAFTS/23-058.html

4. Terms, Definitions and Abbreviated Terms

4.1. Terms and Definitions

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

coordinate reference system

coordinate system that is related to an object by a datum [OGC Topic 2]

Note
More information about coordinate reference systems and common problems when dealing with coordinates may be found in the W3C/OGC Spatial Data on the Web Best Practice in the section 'Coordinate Reference Systems (CRS)'.
feature

abstraction of real world phenomena [ISO 19101-1:2014]

Note
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'.
feature collection

a set of features from a dataset

feature schema

schema that describes the properties of a feature type

feature type

class of features having common characteristics [ISO 19156:2023]

JSON document

an information resource (series of octets) described by the application/json media type [JSON Schema 2020-12]

Note
The terms "JSON document", "JSON text", and "JSON value" are interchangeable.
JSON-FG document

a JSON document that conforms to the Requirements Class "Core" of OGC Features and Geometries JSON - Part 1: Core

<JSON> key

the name of a member

<JSON> member

a name/value pair in a JSON object

primary geometry

the geometry that the publisher considers as the most important spatial characteristic of a feature (OGC API - Features - Part 5: Schemas)

Note
A feature can be described by multiple spatial properties. For example, a radio tower can have a property with a point value that describes the location of the tower and another property with a multi-polygon value that describes the area of coverage. Some feature formats can represent only a single geometry per feature. In those cases, the primary geometry will be used when the feature is encoded in such a format.
Note
The primary geometry of a feature can also vary depending on the zoom level. At a smaller scale, the primary geometry could be a point while a polygon could be used at a larger scale.
primary temporal information

the time instant or time interval that the publisher considers as the most important temporal characteristic of a feature (OGC API - Features - Part 5: Schemas)

Note
A feature can be described by multiple temporal properties. For example, an event can have a property with an instant or interval when the event occurred or will occur and another property when the event was recorded in the dataset. The primary temporal information can also be built from two properties, e.g., when the feature has two properties describing the start instant and end instant of an interval.
publisher

entity responsible for making a resource available (Dublin Core Metadata Initiative - DCMI Metadata Terms)

4.2. Abbreviated Terms

API

Application Programming Interface

CRS

Coordinate Reference System

JSON

JavaScript Object Notation

JSON-FG

OGC Features and Geometries JSON

JSON-LD

JSON for Linking Data

OGC

Open Geospatial Consortium

SWG

Standards Working Group

WGS 84

World Geodetic System 1984

5. Conventions

5.1. Identifiers

The normative provisions in this Standard are denoted by the URI:

http://www.opengis.net/spec/json-fg-1/0.2

All requirements and conformance tests that appear in this document are denoted by partial URIs which are relative to this base.

5.2. Use of JSON terminology

The following terms are used as specified in JSON. In particular:

  • "member" refers to a name/value pair of an object;

  • "key" refers to the name of a member;

  • "value" refers to the value of a member, which may be an object, array, string, number, boolean, or null.

For example, the GeoJSON "geometry" member has the key "geometry" and one of the GeoJSON geometry objects (or null) as its value.

5.3. Use of JSON Schema

Where possible, JSON Schema is used to formally specify the JSON-FG syntax. Additional requirements are used where JSON-Schema is not sufficient to express aspects of the JSON-FG syntax such as the relationship between the JSON-FG place member and the fallback GeoJSON geometry member. All schemas are in Annex 'Schemas (Normative)'.

In addition, JSON Schema is used to describe the schema of feature types, see Feature schemas.

5.4. Use of CURIEs as a compact URI notation

JSON-FG uses CURIEs (Compact URIs) as a compact notation of OGC URIs, in particular for OGC URIs of coordinate reference systems.

The policy for using CURIEs in OGC standards is documented here.

This Standard also allows the use of CURIEs where an OGC URI is expected, such as in the "coordRefSys" member or the "conformsTo" member. To be unambiguous, the use of safe CURIEs is recommended.

5.5. Extensibility

JSON-FG is designed to be extensible. Extensions to the core, to any of the other conformance classes defined in this document or the addition of new capabilities can be specified in revisions to this Standard. Extensions can also be specified in additional documents that would become additional parts of the JSON-FG Standard. Finally, extensions can be specified by communities. However, such documents will not be vetted by the OGC.

Readers of JSON-FG documents should therefore be prepared to encounter unexpected keys or unexpected values. Keys that are not recognized should be ignored. Unexpected values of a known key should be mapped to null.

The JSON Schemas are designed to support extensions. JSON-FG documents that include custom extensions, but conform to JSON-FG requirements classes will still validate against the normative JSON-FG schemas published in the OGC Schema Repository.

The "$id" member of the schemas does not include information about the version of the Standard or the part of the JSON-FG standard. Future revisions of this Standard or additional parts of JSON-FG will update and extend the JSON-FG schemas. Changes to the JSON-FG schemas should not invalidate existing JSON-FG documents without custom extensions.

Note
The "CustomGeometry" object specified in "geometry-objects.json" supports this evolution of the JSON-FG schemas over time. The schema will match any geometry objects that are not specified by GeoJSON or JSON-FG. If in the future additional geometry types are added to JSON-FG, the type names would be excluded from the "type" member in "CustomGeometry". See Geometry types Arc and Circle for an example.
Note
The "$id" member identifies a schema resource with its canonical URI. The member is specified by JSON Schema.

Custom extensions should use a URI in "$id" that is controlled by the community of interest. A HTTP GET request to the URI should return the JSON Schema document.

See Extending JSON-FG for examples of how future parts or communities could extend the schemas.

6. Introduction

6.1. Motivation

JavaScript Object Notation (JSON) is a popular encoding format for geospatial data. The light weight, simple syntax, and clear human and machine readability of JSON as well as universal support in all modern programming languages appeals to developers. The GeoJSON format as defined in IETF RFC 7946 is a very popular JSON encoding for geographic data. GeoJSON is supported by many commercial and open-source geospatial technology products and libraries. GeoJSON is also supported in most deployments of APIs implementing the OGC API Features Standard. However, GeoJSON has limitations that prevent or limit its use in certain cases, including:

  • WGS 84 is the only allowed Coordinate Reference System (CRS);

  • Geometries are restricted to points, curves, and surfaces with linear interpolation; and

  • No general capability is available to specify the schema of a feature, its type, or its temporal characteristics.

6.2. Scenarios

The following general scenarios are useful in understanding the principles that were 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 the OGC API Features Standard. The scene uses a projected CRS, such as EPSG:5555. The API advertises support for both GeoJSON and 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 descriptions use application/vnd.ogc.fg+json as the media type for JSON-FG.

6.2.1. Using a GeoJSON client

Consider the case where the client implementation only supports GeoJSON and not JSON-FG. An assumption is that the client does support CRS transforms.

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 should not include the JSON-FG extensions. Further, the response is provided in the WGS 84 CRS with axis order longitude/latitude. The client can then 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 is also a valid GeoJSON document. Therefore, the client is still able to use and display the features. The client will, however, not understand the additional information introduced by JSON-FG. To avoid issues for GeoJSON clients parsing JSON-FG documents, the names of any JSON-FG extension members must not conflict with the names of existing GeoJSON members to avoid issues for GeoJSON clients parsing JSON-FG documents.

6.2.2. Using a JSON-FG client

The client implementation supports both 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 header such as Accept: application/vnd.ogc.fg+json, application/geo+json;q=0.8 and a crs=http://www.opengis.net/def/crs/EPSG/0/5555 query parameter. The header states that the client prefers JSON-FG, but if JSON-FG is not available it will also accept GeoJSON. The response will include the headers Content-Type: application/vnd.ogc.fg+json as well as Content-Crs: http://www.opengis.net/def/crs/EPSG/0/5555 and include the JSON-FG building blocks including the geometry in the requested projected CRS and temporal information.

In the second scenario (file access), the JSON-FG client is in the same position as the GeoJSON client. The client has no access to a media type and has to inspect the file to determine the type. The file could be GeoJSON, JSON-FG or some other kind of document that the client does not understand. JSON-FG documents include explicit declarations that conform to both GeoJSON and JSON-FG. Therefore, the client can identify the document as a JSON-FG document and process the content. Since the JSON-FG document provides spatial and temporal information about each feature, the client can zoom in on the features and, for example, provide a time slider so that the user can filter the features that are displayed.

7. JSON-FG building blocks

This Clause describes the JSON building blocks required to extend GeoJSON features and feature collections. The following clauses specify the formal requirements classes.

The Annex 'Considerations (Informative)' contains considerations for each of the JSON-FG building blocks.

Remarks and known open issues are included in notes.

7.1. Overview

The following JSON building blocks are specified by this Standard:

An additional discussion topic during the development of the JSON-FG Standard was the relationship between a feature and other web resources that are represented as links. The JSON-FG Standard does not mandate a specific approach for representing relationships as links. However, Annex 'Links (Informative)' documents and discusses patterns of how to represent relationships as links.

Annex 'Examples (Informative)' has examples of JSON-FG documents.

7.2. General Approach

The GeoJSON RFC clearly specifies in Clauses 6 and 7 that additional members can be added to the GeoJSON objects as long as they do not conflict with members as specified by GeoJSON ("foreign members").

JSON-FG extends GeoJSON in two ways:

  • By adding new JSON members to the "Feature" and "FeatureCollection" objects;

  • By specifying additional geometry objects.

As a result, JSON-FG does not place constraints on the information in the "properties" member (like GeoJSON) and JSON-FG readers do not have to parse the "properties" object. This approach avoids name clashes with existing feature properties in the "properties" object.

Some GeoJSON readers, however, only provide access to the pre-defined JSON members in GeoJSON features, such as "id", "geometry", "bbox" and "properties". If the target audience of JSON-FG documents uses such tools, it is recommended to also include the additional top-level members like "time", "place", "featureType", and "coordRefSys" in the "properties" object.

7.3. Metadata

To indicate that a JSON document is a JSON-FG document and to indicate the JSON-FG version and conformance classes implemented in the document, a conformsTo member is required to be included in the JSON-FG document object.

The value of the member is an array of strings, where each string is a URI of a conformance class.

Example 1. Conformance declaration using URIs
1
2
3
4
"conformsTo" : [
  "http://www.opengis.net/spec/json-fg-1/0.2/conf/core",
  "http://www.opengis.net/spec/json-fg-1/0.2/conf/3d"
]

As an alternative to URIs, the Compact URI (CURIE) [ogc-json-fg-1-{x.y}:{conformanceClassId}] can also be used. {x.y} is the version number (0.2 for this version), {conformanceClassId} the local identifier of the implemented conformance class.

Example 2. Conformance declaration using CURIEs
1
"conformsTo" : [ "[ogc-json-fg-1-0.2:core]", "[ogc-json-fg-1-0.2:3d]" ]

7.4. Temporal information

7.4.1. Overview

Many features have a geometry property that provides information about the primary spatial characteristics of the feature. In GeoJSON, this information is encoded in the "geometry" member. Features often have temporal information. In most cases, time is either an instant (e.g., an event) or an interval (e.g., an activity or a temporal validity). In the OGC API Features Standard the temporal property is reflected in the parameter "datetime" for temporal filtering of features that is supported by all compliant Feature API instances.

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 this Standard and might be specified in future extensions.

7.4.2. Description

Features can have temporal properties. These properties will typically be included in the "properties" member.

  • In many datasets all temporal properties are instants (represented by a date or a timestamp) and intervals are 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".

As GeoJSON does, JSON-FG does not place constraints on the information in the "properties" member. JSON-FG specifies a new JSON member in a feature object (key: "time"). The member describes temporal information (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 "time" member.

The publisher of the data needs to decide which temporal feature properties are used in the "time" member.

The value of "time" is either null (no temporal information) or an object.

Table 1. Properties of the "time" object
Property Type Description

date

string

An instant with a granularity of a date. See below for more details about instants.

timestamp

string

An instant with the granularity of a timestamp. See below for more details about instants.

interval

[ string ]

An interval, described by an array of the two instants (start and end). See below for more details about intervals.

If both values intersect, then including both an instant and an interval is valid. In this case, clients should use the interval property and may use the date or timestamp property to determine the temporal characteristics of the feature.

The "time" object may be extended with additional members. Clients processing a "time" object must be prepared to parse additional members. Clients should ignore members that they do not understand. For example, in cases where the "time" member neither includes an "instant" or "interval", a client may process the feature as a feature without temporal information.

Note
The data publisher decides how temporal properties inside the "properties" member are encoded. The schema for the "time" 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.

7.4.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")

Conceptually, an instant is a "temporal entity with zero extent or duration" [Time Ontology in OWL]. In practice, the temporal position of an instant is described using data types where each value has some duration or granularity. The value should be described with a granularity that is sufficient for the intended use of the data.

In the case of a timestamp the granularity is a second or smaller. All timestamps must be in the time zone UTC ("Z").

In the case of a date the granularity is a day. Dates as instants will be used when a granularity of a day independent of its timezone is sufficient for the intended use of the data. If that is not the case and the timezone is important for the intended use, the temporal information should be provided as an interval with start and end timestamps.

Note
The JSON-FG Standard only provides guidance as to how to represent feature data in JSON. Providing guidance as to how to cast JSON-FG data to other data types is out of scope. The OGC Common Query Language (CQL2) Standard uses the same model of instants and intervals as JSON-FG and includes additional guidance how to compare values.
Example 3. A date
1
"time" : { "date": "1969-07-20" }
Example 4. A timestamp
1
"time" : { "timestamp": "1969-07-20T20:17:40Z" }

Dates and timestamps are the initial range of instant values. The range may be extended in the future to support additional use cases. Clients processing values of time must be prepared to receive other values. Clients may ignore values that they do not understand.

7.4.4. Intervals

An interval is described by start and end instants. Both start and end instants are included in the interval, i.e., the interval is closed.

The unbounded end of an interval is represented by a double-dot string ("..") for the start/end. This follows the convention of ISO 8601-2 for an open start or end.

Note
There is a proposal to use null instead of "..".
Example 5. An interval with dates
1
"time" : { "interval": [ "1969-07-16", "1969-07-24" ] }
Example 6. An interval with timestamps
1
"time" : { "interval": [ "1969-07-16T05:32:00Z", "1969-07-24T16:50:35Z" ] }
Example 7. An half-bounded interval
1
"time" : { "interval": [ "2014-04-24T10:50:18Z", ".." ] }

The options described above are the initial range of interval values - the granularity is either days or (sub-)seconds and interval ends may be unbounded. The value range may be extended in the future to support additional use cases. Clients processing values of time must be prepared to receive other values. Clients may ignore values that they do not understand.

7.5. Geometry

7.5.1. Overview

Features typically have a geometry that provides information about the primary spatial characteristics of the feature.

In GeoJSON, geometry information is encoded in the "geometry" member. Geometries are encoded according to the OGC Simple Features Standard (2D or 2.5D points, line strings, polygons or aggregations of them) using a WGS 84 CRS (OGC:CRS84 or OGC:CRS84h).

A key motivation for the development of the JSON-FG Standard is to support additional requirements, especially the ability to express other CRSs and solid geometries.

To avoid confusing existing GeoJSON readers, such geometries are provided in a new member in the feature object with the key "place".

Note
There is an ongoing discussion to use a different key instead of "place". This discussion has to be resolved and this note must be removed before finalizing the JSON-FG Standard.

7.5.2. Description

The primary geometry of a feature is provided in the "geometry" and/or "place" members of the feature object as specified in the next sub-clause. The value of both members is an object representing a geometry - or null.

The valid values of the "geometry" member are specified in the GeoJSON standard.

The value range of the "place" member is an extended and extensible version of the value range of the GeoJSON "geometry" member:

  • Extended by additional geometry objects (additional JSON-FG geometry types Polyhedron, MultiPolyhedron, Prism, and MultiPrism) as well as by the capabilities to declare the coordinate reference system of the coordinates.

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

Note
The JSON-FG standard does not add a new JSON-FG geometry collection that includes the new JSON-FG geometry types, because geometry collections are rarely used as feature geometries.
Note
There is an ongoing discussion about which 3D geometries should be included in JSON-FG and how they should be grouped into conformance classes. This discussion has to be resolved and this note must be removed before finalizing the JSON-FG Standard.
Note
There is an ongoing discussion on a proposal to add additional geometry types supporting curves with circular arc interpolation to JSON-FG. This discussion has to be resolved and this note must be removed before finalizing the JSON-FG Standard.

All coordinates in a "place" member are in the same coordinate reference system. This includes GeometryCollection geometries, where all geometries must be in the same coordinate reference system.

Use of "geometry" and/or "place"

If the geometry is a valid GeoJSON geometry (one of the GeoJSON geometry types, in WGS 84), the geometry is encoded as the value of the "geometry" member. The "place" member then has the value null.

If the geometry cannot be represented as a valid GeoJSON geometry, the geometry is encoded as the value of the "place" member.

In addition, a valid GeoJSON geometry may be provided as the value of the "geometry" member in the WGS 84 CRS as specified in the GeoJSON standard. Otherwise, the "geometry" member is set to null. If present, the geometry that is the value of the "geometry" member is a fallback for readers that support GeoJSON, but not JSON-FG. This fallback geometry could be a simplified version of the value of the "place" member - like the building footprint in the example "building with a polyhedron geometry and the polygon footprint" which is the polygon projection of the solid geometry. The fallback geometry can also be the same point/line string/polygon geometry that is the value of the "place" member, but in a WGS 84 CRS (potentially with fewer vertices to reduce the file size). It is the decision of the publisher, how the fallback geometry in a WGS 84 CRS is derived from the geometry that is the value of the "place" member. In the example, this is the footprint of the building, but it also could be a representative point (to reduce the data volume) or a 3D MultiPolygon representing the outer shell of the polyhedron (for clients that support visualizations in 3D).

The presence of such fallback geometries in a JSON-FG document is indicated by a value "geojson" in the media type parameter "compatibility" (see application/fg+json).

Note
GeoJSON states that "geometry" is null, if the feature is "unlocated". A real-world entity is obviously not unlocated when "place" has a value. However, the GeoJSON representation of the feature can still considered to be "unlocated", if a representation in a WGS 84 CRS cannot be determined. Examples for such situations are: a local engineering CRS or a planetary CRS is used for the geometry in "place", or if the known consumers of the JSON-FG document do not need the fallback geometry.
Metrics

If the CRS uses longitude and latitude as coordinates, clients should perform geometrical computations - including computation of length or area on the curved surface that approximates the earth’s surface. Details are provided, for example, in the drafts of Features and Geometry - Part 2: Metrics.

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)
Note
Antimeridian: is the meridian 180° both east and west of the prime meridian in a geographical coordinate system. The longitude at this line can be given as either east or west.
Polyhedron

A solid is defined by its bounding surfaces. Each bounding surface is a closed, simple surface, also called a shell.

Each solid has a unique exterior shell and any number of shells that are inside the exterior shell and that describe voids. The interior shells do not intersect each other and cannot contain another interior shell.

A polyhedron is a solid where each shell is a multi-polygon. 'Closed' means that the multi-polygon shell is watertight, it splits space into two distinct regions: inside and outside of the shell. 'Simple' means that the polygons that make up the shell do not intersect, they only touch each other along their common boundaries.

Cologne Cathedral LoD 2
Figure 1. A Polyhedron (Cologne Cathedral).

The JSON representation of the coordinates of a polyhedron is a non-empty array of multi-polygon arrays. Each multi-polygon array is a shell. The first shell is the exterior boundary, all other shells are voids.

Note
As in a GeoJSON Polygon, the first and last positions of each ring have identical values.

The dimension of all positions is three.

The Cologne Cathedral with polyhedron geometries is provided as an example in Annex C.

MultiPolyhedron

A multi-polyhedron is a collection of polyhedron objects. These are arbitrary aggregations. There is no assumption regarding the topological relationships between the polyhedron objects, but in most cases the polyhedron objects will not intersect each other.

Note
According to ISO 19107:2020 ("Spatial schema"), the geometry of the multi-polyhedron is the set theoretic union of all polyhedron objects. For example, if there are overlapping polyhedron objects, the volume of the multi-polyhedron will be smaller than the sum of the polyhedron volumes.

The collection of polyhedron objects is represented as a JSON array. The order of the polyhedron objects in the array is not significant.

Prism

A prism is defined by a base shape (e.g. Polygon or Circle) that is then extruded from some optional lower limit to an upper limit.

The limits are measured relative to a specified 3D CRS. That is either the default 3D CRS (OGC:CRS84h) or another 3D CRS specified using the coordRefSys key.

If the base shape is a point, then the extrusion is a line extending from the lower limit to the upper limit.

A pylon feature with a base shape of a point is provided as an example in Annex C.

If the base shape is a line string, then the extrusion is a ribbon following the path of the line string and extending from the lower limit to the upper limit.

A fence feature with a base shape of a line string is provided as an example in Annex C.

If the base shape is a polygon, then the extrusion is a solid whose footprint takes the shape of the specified polygon and extended from the lower limit to the upper limit. If the polygon base shape contains holes, these manifest as voids in the extruded shape.