protocol

# `geojson_protocol`

GeoJSON (RFC 7946) parser, generator, and validator protocol.

Availability:
`logtalk_load(geojson(loader))`
Author: Paulo Moura
Version: 1:0:0
Date: 2026-06-15
Compilation flags:
`static`
Dependencies:
(none)
Remarks:
(none)
Inherited public predicates:
(none)

## Public predicates

### `parse/2`

Parses a GeoJSON document from the given source (`file(Path)`, `stream(Stream)`, `codes(List)`, `chars(List)`, or `atom(Atom)`) into a native GeoJSON term.

Compilation flags:
`static`
Template:
`parse(Source,Term)`
Mode and number of proofs:
`parse(++compound,--term)` - `one_or_error`
Exceptions:
`Source` is a variable:
`instantiation_error`
`Source` is neither a variable nor a valid source:
`domain_error(geojson_source,Source)`
Parsed JSON does not represent a valid GeoJSON document:
`domain_error(geojson,Document)`

### `generate/2`

Generates GeoJSON content using the representation specified in the first argument (`file(Path)`, `stream(Stream)`, `codes(List)`, `chars(List)`, or `atom(Atom)`) from a native GeoJSON term.

Compilation flags:
`static`
Template:
`generate(Sink,Term)`
Mode and number of proofs:
`generate(+compound,++term)` - `one_or_error`
Exceptions:
`Sink` is a variable:
`instantiation_error`
`Sink` is neither a variable nor a valid sink:
`domain_error(geojson_sink,Sink)`
`Term` is not a valid GeoJSON term:
`domain_error(geojson,Term)`

### `validate/1`

True iff the argument is a valid native GeoJSON term according to RFC 7946.

Compilation flags:
`static`
Template:
`validate(Term)`
Mode and number of proofs:
`validate(@term)` - `zero_or_one`

### `validate/2`

Validates a native GeoJSON term returning a list of reason terms whose final argument is the failing path.

Compilation flags:
`static`
Template:
`validate(Term,Errors)`
Mode and number of proofs:
`validate(@term,-list(compound))` - `one_or_error`
Exceptions:
`Term` is a variable:
`instantiation_error`
Remarks:

> - invalid_geojson_term(Path): The term is not any supported GeoJSON geometry, feature, or feature collection representation.

> - invalid_geometry(Path): A geometry member is neither a valid geometry term nor `@null` where `@null` is allowed.

> - invalid_properties(Path): A feature properties member is neither `@null` nor a valid JSON object term in the selected representation.

> - invalid_options(Path): The options argument is not a list.

> - option_not_allowed(Name, Path): An option with the given name is not allowed for the enclosing GeoJSON term.

> - duplicate_option(Name, Path): The same option name occurs more than once in the options list.

> - unknown_option(Option, Path): An option term is not recognized as one of the supported options.

> - invalid_bbox(Path): A bounding box is not a list of four or six numbers.

> - bbox_longitude_out_of_range(Path): A bounding box longitude value lies outside the RFC 7946 range `[-180,180]`.

> - bbox_latitude_out_of_range(Path): A bounding box latitude value lies outside the RFC 7946 range `[-90,90]`.

> - bbox_latitude_order(Path): The south latitude value is greater than the north latitude value in a bounding box.

> - bbox_altitude_order(Path): The minimum altitude value is greater than the maximum altitude value in a three-dimensional bounding box.

> - bbox_dimension_mismatch(Actual, Expected, Path): A bounding box length does not match the dimensionality required by the represented geometry, feature, or collection.

> - invalid_id(Path): A feature identifier is neither a number nor a valid string term in the selected representation.

> - invalid_foreign_members(Path): Foreign members are not represented as a valid pair list or embedded JSON object term, or contain an invalid pair term.

> - prohibited_member(Key, Path): A prohibited foreign member name such as `crs` was used.

> - reserved_foreign_member(Key, Path): A reserved GeoJSON member name was used as a foreign member key.

> - invalid_position(Path): A position is not a list of at least two numeric coordinates.

> - position_longitude_out_of_range(Path): A position longitude value lies outside the RFC 7946 range `[-180,180]`.

> - position_latitude_out_of_range(Path): A position latitude value lies outside the RFC 7946 range `[-90,90]`.

> - invalid_json_object_pair(Path): A JSON object member is not represented using a supported key-value pair term.

> - invalid_json_key(Path): A JSON object key is not a valid string term in the selected representation.

> - duplicate_json_object_key(Key, Path): The same JSON object key occurs more than once in the same object.

> - invalid_json_value(Path): A JSON value is not a number, boolean, null, valid string term, array, or object term.

> - insufficient_positions(MinimumLength, Path): A coordinate array contains fewer positions than required for the enclosing geometry.

> - invalid_position_array(Path): A coordinate array expected to contain positions is not a list of valid positions.

> - inconsistent_position_dimension(Path): Positions in the same coordinate array do not all have the same dimensionality.

> - invalid_line_string_array(Path): A MultiLineString coordinate array is not a valid list of line string coordinate arrays.

> - invalid_polygon(Path): A polygon coordinate structure is invalid, for example because it is not a non-empty list of linear rings.

> - ring_not_closed(Path): A linear ring does not repeat its first position as its last position.

> - invalid_multi_polygon(Path): A MultiPolygon coordinate array is not a valid list of polygon coordinate arrays.

> - invalid_geometry_collection(Path): A GeometryCollection geometries member is not a list.

> - invalid_feature_collection(Path): A FeatureCollection features member is not a list.

> - invalid_feature(Path): A value inside a FeatureCollection is not a valid feature term.

### `json_to_geojson/2`

Converts a JSON term, as returned by the `json` library, into a native GeoJSON term.

Compilation flags:
`static`
Template:
`json_to_geojson(JSON,GeoJSON)`
Mode and number of proofs:
`json_to_geojson(+term,-term)` - `one_or_error`
Exceptions:
`JSON` is a variable:
`instantiation_error`
`JSON` is not a valid GeoJSON JSON term:
`domain_error(geojson,JSON)`

### `geojson_to_json/2`

Converts a native GeoJSON term into a JSON term suitable for the `json` library.

Compilation flags:
`static`
Template:
`geojson_to_json(GeoJSON,JSON)`
Mode and number of proofs:
`geojson_to_json(+term,-term)` - `one_or_error`
Exceptions:
`GeoJSON` is a variable:
`instantiation_error`
`GeoJSON` is not a valid GeoJSON term:
`domain_error(geojson,GeoJSON)`

## Protected predicates

(none)

## Private predicates

(none)

## Operators

(none)

See also

geojson, json, geospatial