JSONFG -- OGC Features and Geometries JSON
Added in version 3.8.
Driver short name
JSONFG
Driver built-in by default
This driver is built-in by default
This driver implements read/write support for access to features encoded in OGC Features and Geometries JSON - Part 1: Core format.
JSON-FG is a set of extensions over the GeoJSON format.
The following extensions are supported:
capturing the feature type in a
featureType
element to affect features to separatecapturing a coordinate reference system (not necessarily WGS 84) in a
coordRefSys
element, that is the one used by geometries written in theplace
elementtime
element at Feature levelminimum support for Polyhedron geometries (with a single outer shell) and Prism with Point, LineString or Polygon base.
Warning
This driver implements a draft version of the standard.
Driver capabilities
Supports Create()
This driver supports the GDALDriver::Create()
operation
Supports Georeferencing
This driver supports georeferencing
Supports VirtualIO
This driver supports virtual I/O operations (/vsimem/, etc.)
Connection string
The JSON-FG driver accepts three types of sources of data:
Uniform Resource Locator (URL) - a Web address to perform HTTP request
Plain text file with JSON-FG data, typically with a .json extension
Text passed directly and encoded in JSON-FG
The URL/filename/text might be prefixed with
JSONFG:
to avoid any ambiguity with other drivers. Alternatively, starting
with GDAL 3.10, specifying the -if JSONFG
option to command line utilities
accepting it, or JSONFG
as the only value of the papszAllowedDrivers
of
GDALOpenEx()
, also forces the driver to recognize the passed
URL/filename/text.
Time support
On reading:
Feature.time.date elements are mapped to a OGR
time
field of type Date. If there is a property also calledtime
, the OGR field for Feature.time is calledjsonfg_time
Feature.time.timestamp elements are mapped to a OGR
time
field of type DateTimeFeature.time.interval elements are mapped to a OGR
time_start
andtime_end
fields of type Date or DateTime. If there are properties with those names, the OGR fields for Feature.time are prefixed withjsonfg_
Unbounded intervals (..
) are mapped to a unset OGR feature field.
On writing, if fields called time
, time_start
, time_end
of type
Date or DateTime are created, their content is used to set the Feature.time
element with the reverse logic as the above explained reading side.
The field names may also be prefixed with jsonfg_
to distinguish them from
fields time
, time_start
, time_end
that must be written in
Feature.properties
Configuration options
Configuration options can be specified in command-line tools using the syntax --config <NAME>=<VALUE>
or using functions such as CPLSetConfigOption()
(C) or gdal.config_options
(Python).
The following configuration options are available:
OGR_JSONFG_MAX_OBJ_SIZE=<MBytes>: Defaults to
200
. size in MBytes of the maximum accepted single feature, or 0 to allow for a unlimited size (GDAL >= 3.5.2).
Open options
Open options can be specified in command-line tools using the syntax -oo <NAME>=<VALUE>
or by providing the appropriate arguments to GDALOpenEx()
(C) or gdal.OpenEx
(Python).
The following open options are supported:
GEOMETRY_ELEMENT=[AUTO/PLACE/GEOMETRY]: Defaults to
AUTO
. Determines which JSON element to use to create geometry from. By default when theplace
element is set, geometries are created from its content. And when it is absent or null, the content of thegeometry
element is used. Setting this option toPLACE
restricts the reading to theplace
elements. Setting this option toGEOMETRY
restricts the reading to thegeometry
elements.
Dataset creation options
Dataset creation options can be specified in command-line tools using the syntax -dsco <NAME>=<VALUE>
or by providing the appropriate arguments to GDALCreate()
(C) or Driver.Create
(Python).
The following dataset creation options are supported:
SINGLE_LAYER=[YES/NO]: Defaults to
NO
. Whether a single layer will be written. If set to YES, thecoordRefSys
andfeatureType
elements can be written at the FeatureCollection level instead inside each Feature.
Layer creation options
Layer creation options can be specified in command-line tools using the syntax -lco <NAME>=<VALUE>
or by providing the appropriate arguments to GDALDatasetCreateLayer()
(C) or Dataset.CreateLayer
(Python).
The following layer creation options are supported:
COORDINATE_PRECISION_GEOMETRY=<integer>: Defaults to
7
. Maximum number of figures after decimal separator to write in coordinates ofgeometry
element.COORDINATE_PRECISION_PLACE=<integer>: Maximum number of figures after decimal separator to write in coordinates of
place
element.SIGNIFICANT_FIGURES=<integer>: Defaults to
17
. Maximum number of significant figures when writing floating-point numbers. If explicitly specified, andCOORDINATE_PRECISION_GEOMETRY
orCOORDINATE_PRECISION_PLACE
is not, this will also apply to coordinates.WRITE_GEOMETRY=[YES/NO]: Defaults to
YES
. By default, when a non-WGS 84 CRS is assigned to the layer, the geometry is written in theplace
element, and a reprojected version of it to WGS 84 is written in thegeometry
element. This option can be set to NO to avoid writing thegeometry
element whenplace
is written. Setting this option to NO has no effect if the layer CRS is WGS 84, in which case geometries must be written ingeometry
.ID_FIELD=value: Name of the source field that must be written as the 'id' member of Feature objects.
ID_TYPE=[AUTO/String/Integer]: Type of the 'id' member of Feature objects.
ID_GENERATE=[YES/NO]: Auto-generate feature ids
VSI Virtual File System API support
The driver supports reading and writing to files managed by VSI Virtual File System API, which includes "regular" files, as well as files in the /vsizip/ (read-write), /vsigzip/ (read-write), /vsicurl/ (read-only) domains.
Writing to /dev/stdout or /vsistdout/ is also supported.
Geometry coordinate precision
Added in version GDAL: 3.9
The GeoJSON driver supports reading and writing the geometry coordinate
precision, using the OGRGeomCoordinatePrecision
settings of the
OGRGeomFieldDefn
Those settings are used to round the coordinates
of the geometry of the features to an appropriate decimal precision.
Note
The COORDINATE_PRECISION_GEOMETRY
or COORDINATE_PRECISION_PLACE
layer
creation option has precedence over the values set on the OGRGeomFieldDefn
.
Implementation details: the coordinate precision is stored as
xy_coordinate_resolution_place
and z_coordinate_resolution_place
members at the
FeatureCollection level, for the geometries written in the place
element.
Their numeric value is expressed in the units of the SRS.
For the geometry
standard GeoJSON element, the coordinate precision is stored as
xy_coordinate_resolution
and z_coordinate_resolution
members, and their
numeric value is expressed in the units of the OGC:CRS84 SRS (hence decimal degrees
for xy_coordinate_resolution
)
Example:
{
"type": "FeatureCollection",
"xy_coordinate_resolution_place": 1.0,
"z_coordinate_resolution_place": 1.0,
"xy_coordinate_resolution": 8.9e-6,
"z_coordinate_resolution": 1e-1,
"features": []
}