# 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 separate

- capturing a coordinate reference system (not necessarily WGS 84) in a `coordRefSys` element, that is the one used by geometries written in the `place` element

- `time` element at Feature level

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

## CRS support

Starting with GDAL 3.12, if writing a CRS which has no known identifier, the CRS definition will be written as a PROJJSON object like:

    "coordRefSys": {
        "type": "PROJJSON",
        "value": {
            "$schema": "https://proj.org/schemas/v0.7/projjson.schema.json",
            "type": "CRS type",
            "name": "CRS name",
            "...[snip]...": {}
        }
    }

## Time support

On reading:

- Feature.time.date elements are mapped to a OGR `time` field of type Date. If there is a property also called `time`, the OGR field for Feature.time is called `jsonfg_time`

- Feature.time.timestamp elements are mapped to a OGR `time` field of type DateTime

- Feature.time.interval elements are mapped to a OGR `time_start` and `time_end` fields of type Date or DateTime. If there are properties with those names, the OGR fields for Feature.time are prefixed with `jsonfg_` 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

## Circular-arc geometry support

Added in version 3.12.

Reading and writing of CircularString, CompoundCurve, CurvePolygon, MultiCurve and MultiSurface geometries is supported.

## Geometry measure support

Added in version 3.12.

Geometry with measure values (M component) can be read and written. The unit and description of the measure, if included in the file, is reported in the `MEASURES` layer metadata domain. On the writing side, the `MEASURE_UNIT` and `MEASURE_DESCRIPTION` layer creation option can be set.

## 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 the `place` element is set, geometries are created from its content. And when it is absent or null, the content of the `geometry` element is used. Setting this option to `PLACE` restricts the reading to the `place` elements. Setting this option to `GEOMETRY` restricts the reading to the `geometry` 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, the `coordRefSys` and `featureType` 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 of `geometry` 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, and `COORDINATE_PRECISION_GEOMETRY` or `COORDINATE_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 the `place` element, and a reprojected version of it to WGS 84 is written in the `geometry` element. This option can be set to NO to avoid writing the `geometry` element when `place` is written. Setting this option to NO has no effect if the layer CRS is WGS 84, in which case geometries must be written in `geometry`.

- 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

- MEASURE_UNIT=<string>: (GDAL >= 3.12) Unit of measures (M) values

- MEASURE_DESCRIPTION=<string>: (GDAL >= 3.12) Description of measures (M) values

## 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": []
    }

## See Also

- OGC Features and Geometries JSON - Part 1: Core

- GeoJSON driver